jawadur13/branchsync

1. Repository shape

- This is a two-tier monorepo: a Spring Boot 3 backend in backend/ and a React 18 + Vite + TypeScript frontend in frontend/.

- The system is centered on an internal bank workflow for inter-branch asset transfers rather than a generic CRUD app.

2. Primary runtime boundary

- The backend exposes all business capabilities through REST controllers under com.jamunabank.branchsync.controller.

- The frontend is a single-page application that consumes those APIs through Axios and routes users through protected pages based on JWT session state.

3. Core business domain

- The main domain object is the TransferRequest, which moves items between branches through a staged approval and fulfillment process.

- The workflow is designed around HQ-controlled routing: requesters initiate a transfer, but the destination branch is assigned later by HQ logistics.

4. Workflow engine

- Transfer lifecycle behavior lives in TransferService and is surfaced via TransferController.

- The flow includes internal approval, HQ verification, destination acceptance, release, pickup, delivery, and closure, with explicit rejection and return-to-HQ paths.

- Status history and printable transfer details are part of the transfer subsystem, not separate services.

5. Specialized inventory engines

- The repository contains two distinct inventory models:

- Cash: BranchCashBalance, CashLedgerEntry, CashManualAdjustment, CashTransferDenomination

- Stock: BranchStockBalance, StockLedgerEntry, StockManualAdjustment, StockItem

- These are behavior-driven by category type, with CASH, STOCK, and DOCUMENT_CASE handled differently in the business layer.

- Cash and stock are not just views; they have ledger-style accounting and manual adjustment approval flows.

6. Service layer boundaries

- The backend is organized into domain services: TransferService, CashService, StockService, ManagementService, and AuditService.

- Implementations live under service/impl, suggesting controllers are thin and business rules are concentrated in service classes.

- ManagementService owns master-data administration such as branches, departments, users, item categories, and stock items.

7. Persistence model

- Data access is via Spring Data JPA repositories in repository/, one repository per aggregate or ledger table.

- The schema is backed by MariaDB/MySQL and bootstrapped from backend/src/main/resources/db/migration/branchsync.sql.

- The model includes support tables for roles, departments, item categories, audit logs, branch balances, ledgers, and transfer state.

8. Security and authentication

- Authentication is JWT-based, with login handled by AuthController and token utilities in security/JwtUtils.

- User lookup integrates with Spring Security through CustomUserDetailsService and JwtAuthenticationFilter.

- The repo also includes a custom SHA-256 password encoder, indicating non-default password handling for the legacy or internal auth model.

9. Operational audit and exception handling

- AuditService and AuditLog provide transactional traceability for transfer actions.

- GlobalExceptionHandler standardizes API error responses using ErrorResponse, with domain-specific exceptions for business rule violations, missing resources, and role authorization failures.

- This makes the API behavior explicit and suitable for regulated operational workflows.

10. Frontend architecture

- The frontend is divided into reusable layout components, route guards, context-based auth state, and feature pages.

- Main user areas include dashboard, transfer creation/history/details, cash and stock ledgers and adjustments, branch directory, profile, and admin screens.

- ProtectedRoute and AuthContext are the main frontend boundaries enforcing authenticated access.

11. Admin and master-data management

- Dedicated controllers and pages manage the bank’s structural data: users, branches, departments, item categories, and stock items.

- The system separates operational users from system administrators, and many workflows depend on branch/department/role scoping.

- Lookup endpoints exist to populate dropdowns and contextual choices, such as available branches, departments per branch, and delivery personnel.

12. Tests, scripts, and delivery

- Backend tests focus on repository and service behavior, especially the transfer workflow.

- docker-compose.yml supports local orchestration, and the repo includes seed/test SQL scripts under backend/src/main/resources/db/test data.

- The architecture is therefore designed for local monorepo development with a database-backed API and a browser-based client, not for distributed microservices.