# jawadur13/branchsync architecture

> Architecture diagram of the GitHub repository jawadur13/branchsync, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jawadur13/branchsync
- Repository: https://github.com/jawadur13/branchsync

## Overview

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.

Main entry points: [`frontend/src/api/axiosConfig.ts`](https://github.com/jawadur13/branchsync/blob/main/frontend/src/api/axiosConfig.ts) (Axios Client), [`backend/src/main/java/com/jamunabank/branchsync/repository/TransferRequestRepository.java`](https://github.com/jawadur13/branchsync/blob/main/backend/src/main/java/com/jamunabank/branchsync/repository/TransferRequestRepository.java) (Repositories), [`frontend/src/main.tsx`](https://github.com/jawadur13/branchsync/blob/main/frontend/src/main.tsx) (React SPA), [`backend/src/main/java/com/jamunabank/branchsync/model/entity/TransferRequest.java`](https://github.com/jawadur13/branchsync/blob/main/backend/src/main/java/com/jamunabank/branchsync/model/entity/TransferRequest.java) (Domain Model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_app["Spring Boot<br/>api server"]
  node_auth_controller["Auth API<br/>controller"]
  node_transfer_controller["Transfer API<br/>controller"]
  node_cash_controller["Cash API<br/>controller"]
  node_stock_controller["Stock API<br/>controller"]
  node_management_controller["Admin API<br/>controller"]
  node_lookup_controller["Lookup API<br/>controller"]
  node_transfer_service["Transfer Service<br/>workflow service"]
  node_cash_service["Cash Service<br/>ledger service<br/>[CashService.java]"]
  node_stock_service["Stock Service<br/>ledger service<br/>[StockService.java]"]
  node_management_service["Management Service<br/>admin service"]
  node_audit_service["Audit Service<br/>trace service<br/>[AuditService.java]"]
  node_security["Security Stack<br/>jwt security"]
  node_domain[("Domain Model<br/>entities")]
  node_repositories["Repositories"]
  node_db[("MySQL Schema<br/>migration/sql<br/>[branchsync.sql]")]
end

subgraph group_frontend["Frontend"]
  node_frontend_app["React SPA<br/>frontend app<br/>[main.tsx]"]
  node_auth_context["Auth State<br/>react context<br/>[AuthContext.tsx]"]
  node_route_guard["Protected Route<br/>route guard<br/>[ProtectedRoute.tsx]"]
  node_layout["Layout Shell<br/>ui shell<br/>[Layout.tsx]"]
  node_api_client["Axios Client<br/>http client<br/>[axiosConfig.ts]"]
  node_user_pages["User Pages<br/>feature pages<br/>[Dashboard.tsx]"]
  node_admin_pages["Admin Pages<br/>feature pages<br/>[UserManagement.tsx]"]
end

node_app{{"BranchSync<br/>monorepo"}}

node_app -->|"hosts"| node_backend_app
node_app -->|"includes"| node_frontend_app
node_backend_app -->|"secured by"| node_security
node_auth_controller -->|"issues tokens"| node_security
node_auth_controller -->|"auth lookup"| node_repositories
node_transfer_controller -->|"delegates"| node_transfer_service
node_cash_controller -->|"delegates"| node_cash_service
node_stock_controller -->|"delegates"| node_stock_service
node_management_controller -->|"delegates"| node_management_service
node_lookup_controller -->|"reads refs"| node_management_service
node_transfer_service -->|"mutates"| node_domain
node_transfer_service -->|"persists"| node_repositories
node_transfer_service -->|"records"| node_audit_service
node_cash_service -->|"mutates"| node_domain
node_cash_service -->|"persists"| node_repositories
node_stock_service -->|"mutates"| node_domain
node_stock_service -->|"persists"| node_repositories
node_management_service -->|"mutates"| node_domain
node_management_service -->|"persists"| node_repositories
node_audit_service -->|"logs"| node_domain
node_audit_service -->|"persists"| node_repositories
node_repositories -->|"maps to"| node_db
node_frontend_app -->|"uses"| node_auth_context
node_frontend_app -->|"protects with"| node_route_guard
node_frontend_app -->|"renders through"| node_layout
node_frontend_app -->|"calls API via"| node_api_client
node_auth_context -->|"configures"| node_api_client
node_api_client -->|"authenticates against"| node_auth_controller
node_api_client -->|"consumes"| node_transfer_controller
node_api_client -->|"consumes"| node_cash_controller
node_api_client -->|"consumes"| node_stock_controller
node_api_client -->|"consumes"| node_management_controller
node_api_client -->|"consumes"| node_lookup_controller
node_route_guard -->|"allows"| node_user_pages
node_route_guard -->|"allows"| node_admin_pages

click node_backend_app "https://github.com/jawadur13/branchsync/blob/main/backend/src/main/java/com/jamunabank/branchsync/BranchSyncApplication.java"
click node_auth_controller "https://github.com/jawadur13/branchsync/blob/main/backend/src/main/java/com/jamunabank/branchsync/controller/AuthController.java"
click node_transfer_controller "https://github.com/jawadur13/branchsync/blob/main/backend/src/main/java/com/jamunabank/branchsync/controller/TransferController.java"
click node_cash_controller "https://github.com/jawadur13/branchsync/blob/main/backend/src/main/java/com/jamunabank/branchsync/controller/CashController.java"
click node_stock_controller "https://github.com/jawadur13/branchsync/blob/main/backend/src/main/java/com/jamunabank/branchsync/controller/StockController.java"
click node_management_controller "https://github.com/jawadur13/branchsync/blob/main/backend/src/main/java/com/jamunabank/branchsync/controller/OrgManagementController.java"
click node_lookup_controller "https://github.com/jawadur13/branchsync/blob/main/backend/src/main/java/com/jamunabank/branchsync/controller/LookupController.java"
click node_transfer_service "https://github.com/jawadur13/branchsync/blob/main/backend/src/main/java/com/jamunabank/branchsync/service/TransferService.java"
click node_cash_service "https://github.com/jawadur13/branchsync/blob/main/backend/src/main/java/com/jamunabank/branchsync/service/CashService.java"
click node_stock_service "https://github.com/jawadur13/branchsync/blob/main/backend/src/main/java/com/jamunabank/branchsync/service/StockService.java"
click node_management_service "https://github.com/jawadur13/branchsync/blob/main/backend/src/main/java/com/jamunabank/branchsync/service/ManagementService.java"
click node_audit_service "https://github.com/jawadur13/branchsync/blob/main/backend/src/main/java/com/jamunabank/branchsync/service/AuditService.java"
click node_security "https://github.com/jawadur13/branchsync/blob/main/backend/src/main/java/com/jamunabank/branchsync/security/SecurityConfig.java"
click node_domain "https://github.com/jawadur13/branchsync/blob/main/backend/src/main/java/com/jamunabank/branchsync/model/entity/TransferRequest.java"
click node_repositories "https://github.com/jawadur13/branchsync/blob/main/backend/src/main/java/com/jamunabank/branchsync/repository/TransferRequestRepository.java"
click node_db "https://github.com/jawadur13/branchsync/blob/main/backend/src/main/resources/db/migration/branchsync.sql"
click node_frontend_app "https://github.com/jawadur13/branchsync/blob/main/frontend/src/main.tsx"
click node_auth_context "https://github.com/jawadur13/branchsync/blob/main/frontend/src/context/AuthContext.tsx"
click node_route_guard "https://github.com/jawadur13/branchsync/blob/main/frontend/src/components/ProtectedRoute.tsx"
click node_layout "https://github.com/jawadur13/branchsync/blob/main/frontend/src/components/Layout/Layout.tsx"
click node_api_client "https://github.com/jawadur13/branchsync/blob/main/frontend/src/api/axiosConfig.ts"
click node_user_pages "https://github.com/jawadur13/branchsync/blob/main/frontend/src/pages/Dashboard.tsx"
click node_admin_pages "https://github.com/jawadur13/branchsync/blob/main/frontend/src/pages/admin/UserManagement.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_backend_app,node_auth_controller,node_transfer_controller,node_cash_controller,node_stock_controller,node_management_controller,node_lookup_controller,node_transfer_service,node_cash_service,node_stock_service,node_management_service,node_audit_service,node_security,node_domain,node_repositories,node_db toneBlue
class node_frontend_app,node_auth_context,node_route_guard,node_layout,node_api_client,node_user_pages,node_admin_pages toneAmber
class node_app toneNeutral
```

## Components

### Backend

Spring Boot API, domain services, persistence, and security

- [Spring Boot](https://github.com/jawadur13/branchsync/blob/main/backend/src/main/java/com/jamunabank/branchsync/BranchSyncApplication.java): api server · Backend application entry point · `backend/src/main/java/com/jamunabank/branchsync/BranchSyncApplication.java`
- [Auth API](https://github.com/jawadur13/branchsync/blob/main/backend/src/main/java/com/jamunabank/branchsync/controller/AuthController.java): controller · Login and session token issuance · `backend/src/main/java/com/jamunabank/branchsync/controller/AuthController.java`
- [Transfer API](https://github.com/jawadur13/branchsync/blob/main/backend/src/main/java/com/jamunabank/branchsync/controller/TransferController.java): controller · Transfer lifecycle endpoints · `backend/src/main/java/com/jamunabank/branchsync/controller/TransferController.java`
- [Cash API](https://github.com/jawadur13/branchsync/blob/main/backend/src/main/java/com/jamunabank/branchsync/controller/CashController.java): controller · Cash ledger and adjustment endpoints · `backend/src/main/java/com/jamunabank/branchsync/controller/CashController.java`
- [Stock API](https://github.com/jawadur13/branchsync/blob/main/backend/src/main/java/com/jamunabank/branchsync/controller/StockController.java): controller · Stock ledger and adjustment endpoints · `backend/src/main/java/com/jamunabank/branchsync/controller/StockController.java`
- [Admin API](https://github.com/jawadur13/branchsync/blob/main/backend/src/main/java/com/jamunabank/branchsync/controller/OrgManagementController.java): controller · Branch, user, department, and item administration · `backend/src/main/java/com/jamunabank/branchsync/controller/OrgManagementController.java`
- [Lookup API](https://github.com/jawadur13/branchsync/blob/main/backend/src/main/java/com/jamunabank/branchsync/controller/LookupController.java): controller · Reference-data and selection endpoints · `backend/src/main/java/com/jamunabank/branchsync/controller/LookupController.java`
- [Transfer Service](https://github.com/jawadur13/branchsync/blob/main/backend/src/main/java/com/jamunabank/branchsync/service/TransferService.java): workflow service · Approval, routing, fulfillment, and closure logic · `backend/src/main/java/com/jamunabank/branchsync/service/TransferService.java`
- [Cash Service](https://github.com/jawadur13/branchsync/blob/main/backend/src/main/java/com/jamunabank/branchsync/service/CashService.java): ledger service · Cash balances, ledgers, and manual adjustments · `backend/src/main/java/com/jamunabank/branchsync/service/CashService.java`
- [Stock Service](https://github.com/jawadur13/branchsync/blob/main/backend/src/main/java/com/jamunabank/branchsync/service/StockService.java): ledger service · Stock balances, ledgers, and manual adjustments · `backend/src/main/java/com/jamunabank/branchsync/service/StockService.java`
- [Management Service](https://github.com/jawadur13/branchsync/blob/main/backend/src/main/java/com/jamunabank/branchsync/service/ManagementService.java): admin service · Master data and structural administration · `backend/src/main/java/com/jamunabank/branchsync/service/ManagementService.java`
- [Audit Service](https://github.com/jawadur13/branchsync/blob/main/backend/src/main/java/com/jamunabank/branchsync/service/AuditService.java): trace service · Operational audit trail recording · `backend/src/main/java/com/jamunabank/branchsync/service/AuditService.java`
- [Security Stack](https://github.com/jawadur13/branchsync/blob/main/backend/src/main/java/com/jamunabank/branchsync/security/SecurityConfig.java): jwt security · JWT filter, user details, password encoding, and security config · `backend/src/main/java/com/jamunabank/branchsync/security/SecurityConfig.java`
- [Domain Model](https://github.com/jawadur13/branchsync/blob/main/backend/src/main/java/com/jamunabank/branchsync/model/entity/TransferRequest.java): entities · Transfer, balances, ledgers, users, branches, roles, and categories · `backend/src/main/java/com/jamunabank/branchsync/model/entity/TransferRequest.java`
- [Repositories](https://github.com/jawadur13/branchsync/blob/main/backend/src/main/java/com/jamunabank/branchsync/repository/TransferRequestRepository.java): jpa repositories · Spring Data access for aggregates and ledger tables · `backend/src/main/java/com/jamunabank/branchsync/repository/TransferRequestRepository.java`
- [MySQL Schema](https://github.com/jawadur13/branchsync/blob/main/backend/src/main/resources/db/migration/branchsync.sql): migration/sql · Schema and seed data for branches, ledgers, users, and transfer state · `backend/src/main/resources/db/migration/branchsync.sql`

### Frontend

React SPA, route protection, and API consumption

- [React SPA](https://github.com/jawadur13/branchsync/blob/main/frontend/src/main.tsx): frontend app · Vite-powered single-page client · `frontend/src/main.tsx`
- [Auth State](https://github.com/jawadur13/branchsync/blob/main/frontend/src/context/AuthContext.tsx): react context · Client session state and JWT awareness · `frontend/src/context/AuthContext.tsx`
- [Protected Route](https://github.com/jawadur13/branchsync/blob/main/frontend/src/components/ProtectedRoute.tsx): route guard · Authenticated page access control · `frontend/src/components/ProtectedRoute.tsx`
- [Layout Shell](https://github.com/jawadur13/branchsync/blob/main/frontend/src/components/Layout/Layout.tsx): ui shell · Shared navigation chrome and page framing · `frontend/src/components/Layout/Layout.tsx`
- [Axios Client](https://github.com/jawadur13/branchsync/blob/main/frontend/src/api/axiosConfig.ts): http client · API integration and token-aware requests · `frontend/src/api/axiosConfig.ts`
- [User Pages](https://github.com/jawadur13/branchsync/blob/main/frontend/src/pages/Dashboard.tsx): feature pages · Dashboard, transfers, ledgers, profile, and branch directory · `frontend/src/pages/Dashboard.tsx`
- [Admin Pages](https://github.com/jawadur13/branchsync/blob/main/frontend/src/pages/admin/UserManagement.tsx): feature pages · Branch, department, user, and item management screens · `frontend/src/pages/admin/UserManagement.tsx`

### Other components

- **BranchSync**: monorepo · Two-tier bank workflow system

## Connections

- BranchSync → Spring Boot: hosts · Backend runtime for business capabilities
- BranchSync → React SPA: includes · Browser client for operators and admins
- Spring Boot → Security Stack: secured by · JWT authentication and request filtering
- Auth API → Security Stack: issues tokens · Login flow relies on JWT utilities and user lookup
- Auth API → Repositories: auth lookup · Validates credentials against persisted users
- Transfer API → Transfer Service: delegates · Transfer lifecycle orchestration
- Cash API → Cash Service: delegates · Cash accounting operations
- Stock API → Stock Service: delegates · Stock accounting operations
- Admin API → Management Service: delegates · Master-data administration
- Lookup API → Management Service: reads refs · Populates branch, department, and other lookup data
- Transfer Service → Domain Model: mutates · Transfer requests and transfer state history
- Transfer Service → Repositories: persists · Loads and saves transfer and audit-related data
- Transfer Service → Audit Service: records · Writes workflow trace events
- Cash Service → Domain Model: mutates · Branch cash balances, ledger entries, adjustments
- Cash Service → Repositories: persists · Cash aggregate and ledger storage
- Stock Service → Domain Model: mutates · Branch stock balances, ledger entries, adjustments
- Stock Service → Repositories: persists · Stock aggregate and ledger storage
- Management Service → Domain Model: mutates · Branches, departments, users, roles, and item categories
- Management Service → Repositories: persists · Admin master-data persistence
- Audit Service → Domain Model: logs · AuditLog records
- Audit Service → Repositories: persists · Audit trail storage
- Repositories → MySQL Schema: maps to · JPA repositories backed by schema tables
- React SPA → Auth State: uses · Maintains session and login state
- React SPA → Protected Route: protects with · Blocks unauthenticated navigation
- React SPA → Layout Shell: renders through · Shared application shell
- React SPA → Axios Client: calls API via · Axios-based REST integration
- Auth State → Axios Client: configures · Provides JWT-aware request headers
- Axios Client → Auth API: authenticates against · Login and session token exchange
- Axios Client → Transfer API: consumes · Transfer workflow endpoints
- Axios Client → Cash API: consumes · Cash ledger endpoints
- Axios Client → Stock API: consumes · Stock ledger endpoints
- Axios Client → Admin API: consumes · Admin and master-data endpoints
- Axios Client → Lookup API: consumes · Reference-data endpoints
- Protected Route → User Pages: allows · Authenticated business views
- Protected Route → Admin Pages: allows · Admin-only views are still protected by session state