# harinisricode18/pms-pension_management_system architecture

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

- Interactive diagram: https://gitdiagram.com/harinisricode18/pms-pension_management_system
- Repository: https://github.com/harinisricode18/pms-pension_management_system

## Overview

PMS is a worker-focused micro-pension application: workers record irregular income, receive adaptive safe-savings guidance, allocate savings across retirement and emergency vaults, and track retirement readiness. The React frontend calls a FastAPI backend, whose routes coordinate domain services and MongoDB-backed helpers. Payer verification, agent cash deposits, withdrawals with possible nominee approval, notifications, projections, and health scoring are distinct capabilities. The README also describes conceptual modules whose runtime wiring is not fully shown; those links are omitted where source evidence is unavailable.

Main entry points: [`database/db_helpers.py`](https://github.com/harinisricode18/pms-pension_management_system/blob/main/database/db_helpers.py) (Data access helpers), [`app.py`](https://github.com/harinisricode18/pms-pension_management_system/blob/main/app.py) (FastAPI application), [`routes/savings_routes.py`](https://github.com/harinisricode18/pms-pension_management_system/blob/main/routes/savings_routes.py) (Income and deposits), [`frontend/src/App.jsx`](https://github.com/harinisricode18/pms-pension_management_system/blob/main/frontend/src/App.jsx) (React app routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Worker application"]
  node_frontend["React app routes<br/>[App.jsx]"]
  node_authstate["Auth state<br/>[AuthContext.jsx]"]
  node_incomeui["Income entry<br/>[IncomePage.jsx]"]
  node_dashboard["Savings dashboard<br/>[DashboardPage.jsx]"]
  node_payerui["Payer confirmation<br/>[PayerPage.jsx]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_api["API and workflows"]
  node_appserver["FastAPI application<br/>[app.py]"]
  node_routes_savings["Income and deposits<br/>[savings_routes.py]"]
  node_routes_ledger["Payer ledger routes<br/>[ledger_routes.py]"]
  node_routes_withdrawal["Withdrawal routes"]
  node_routes_agent["Cash agent routes<br/>[agent_routes.py]"]
  node_routes_health["Health score routes<br/>[health_routes.py]"]
  node_routes_projection["Projection routes"]
  node_models["API contracts<br/>[api_models.py]"]
end

subgraph group_domain["Pension capabilities"]
  node_signal["Savings signal engine"]
  node_ledger["Verified income ledger<br/>[ledger_protocol.py]"]
  node_shield["Emergency shield"]
  node_governance["Dual-key governance"]
  node_bridge["Digital cash bridge<br/>[digital_bridge.py]"]
  node_guardian["Guardian guidance<br/>[guardian_agent.py]"]
  node_health["Pension health engine"]
  node_projection["Retirement projection"]
  node_websocket["Live notifications<br/>[ws_manager.py]"]
end

subgraph group_data["Identity and persistence"]
  node_auth["JWT authentication<br/>[auth_utils.py]"]
  node_helpers["Data access helpers<br/>[db_helpers.py]"]
  node_mongo[("MongoDB collections")]
  node_schemas["Stored data schemas<br/>[schemas.py]"]
end

node_worker(("Worker"))
node_payer(("Payer"))
node_agent(("Local cash agent"))
node_nominee(("Withdrawal nominee"))
node_mongodb[("MongoDB")]

node_worker -->|"uses"| node_frontend
node_frontend -->|"provides auth"| node_authstate
node_frontend -->|"routes to"| node_incomeui
node_frontend -->|"routes to"| node_dashboard
node_frontend -->|"routes to"| node_payerui
node_incomeui -->|"calls"| node_api_client
node_dashboard -->|"calls"| node_api_client
node_payerui -->|"calls"| node_api_client
node_authstate -->|"restores session"| node_api_client
node_api_client -.->|"HTTP requests"| node_appserver
node_appserver -->|"registers routes"| node_routes_savings
node_appserver -->|"registers routes"| node_routes_ledger
node_appserver -->|"registers routes"| node_routes_withdrawal
node_appserver -->|"registers routes"| node_routes_agent
node_appserver -->|"registers routes"| node_routes_health
node_appserver -->|"registers routes"| node_routes_projection
node_routes_savings -->|"authenticates"| node_auth
node_routes_savings -->|"validates requests"| node_models
node_routes_savings -->|"recomputes target"| node_signal
node_routes_savings -->|"coordinates deposits"| node_shield
node_routes_savings -->|"reads and writes"| node_helpers
node_routes_ledger -->|"verifies payment"| node_ledger
node_routes_ledger -->|"reads and writes"| node_helpers
node_routes_withdrawal -->|"checks approval"| node_governance
node_routes_withdrawal -->|"processes withdrawal"| node_shield
node_routes_agent -->|"settles cash"| node_bridge
node_routes_agent -->|"broadcasts event"| node_websocket
node_routes_health -->|"computes score"| node_health
node_routes_projection -->|"projects retirement"| node_projection
node_signal -->|"reads income data"| node_helpers
node_ledger -->|"persists ledger"| node_helpers
node_shield -->|"updates vaults"| node_helpers
node_governance -->|"manages approvals"| node_helpers
node_bridge -->|"settles balances"| node_helpers
node_guardian -->|"reads worker data"| node_helpers
node_health -->|"scores and updates"| node_helpers
node_projection -.->|"reads savings data"| node_helpers
node_helpers -->|"uses collections"| node_mongo
node_mongo -->|"connects to"| node_mongodb
node_schemas -.->|"describes stored data"| node_mongodb
node_payer -->|"confirms payment"| node_routes_ledger
node_agent -->|"confirms cash"| node_routes_agent
node_nominee -.->|"submits approval"| node_routes_withdrawal

click node_frontend "https://github.com/harinisricode18/pms-pension_management_system/blob/main/frontend/src/App.jsx"
click node_authstate "https://github.com/harinisricode18/pms-pension_management_system/blob/main/frontend/src/context/AuthContext.jsx"
click node_incomeui "https://github.com/harinisricode18/pms-pension_management_system/blob/main/frontend/src/pages/IncomePage.jsx"
click node_dashboard "https://github.com/harinisricode18/pms-pension_management_system/blob/main/frontend/src/pages/DashboardPage.jsx"
click node_payerui "https://github.com/harinisricode18/pms-pension_management_system/blob/main/frontend/src/pages/PayerPage.jsx"
click node_api_client "https://github.com/harinisricode18/pms-pension_management_system/blob/main/frontend/src/services/api.js"
click node_appserver "https://github.com/harinisricode18/pms-pension_management_system/blob/main/app.py"
click node_routes_savings "https://github.com/harinisricode18/pms-pension_management_system/blob/main/routes/savings_routes.py"
click node_routes_ledger "https://github.com/harinisricode18/pms-pension_management_system/blob/main/routes/ledger_routes.py"
click node_routes_withdrawal "https://github.com/harinisricode18/pms-pension_management_system/blob/main/routes/withdrawal_routes.py"
click node_routes_agent "https://github.com/harinisricode18/pms-pension_management_system/blob/main/routes/agent_routes.py"
click node_routes_health "https://github.com/harinisricode18/pms-pension_management_system/blob/main/routes/health_routes.py"
click node_routes_projection "https://github.com/harinisricode18/pms-pension_management_system/blob/main/routes/projection_routes.py"
click node_models "https://github.com/harinisricode18/pms-pension_management_system/blob/main/api_models.py"
click node_signal "https://github.com/harinisricode18/pms-pension_management_system/blob/main/services/financial_signal_engine.py"
click node_ledger "https://github.com/harinisricode18/pms-pension_management_system/blob/main/services/ledger_protocol.py"
click node_shield "https://github.com/harinisricode18/pms-pension_management_system/blob/main/services/emergency_shield.py"
click node_governance "https://github.com/harinisricode18/pms-pension_management_system/blob/main/services/dual_key_governance.py"
click node_bridge "https://github.com/harinisricode18/pms-pension_management_system/blob/main/services/digital_bridge.py"
click node_guardian "https://github.com/harinisricode18/pms-pension_management_system/blob/main/services/guardian_agent.py"
click node_health "https://github.com/harinisricode18/pms-pension_management_system/blob/main/services/pension_health_engine.py"
click node_projection "https://github.com/harinisricode18/pms-pension_management_system/blob/main/services/pension_projection.py"
click node_websocket "https://github.com/harinisricode18/pms-pension_management_system/blob/main/ws_manager.py"
click node_auth "https://github.com/harinisricode18/pms-pension_management_system/blob/main/auth_utils.py"
click node_helpers "https://github.com/harinisricode18/pms-pension_management_system/blob/main/database/db_helpers.py"
click node_mongo "https://github.com/harinisricode18/pms-pension_management_system/blob/main/database/mongo_connection.py"
click node_schemas "https://github.com/harinisricode18/pms-pension_management_system/blob/main/models/schemas.py"

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_frontend,node_authstate,node_incomeui,node_dashboard,node_payerui,node_api_client toneBlue
class node_appserver,node_routes_savings,node_routes_ledger,node_routes_withdrawal,node_routes_agent,node_routes_health,node_routes_projection,node_models,node_mongodb toneAmber
class node_signal,node_ledger,node_shield,node_governance,node_bridge,node_guardian,node_health,node_projection,node_websocket toneMint
class node_auth,node_helpers,node_mongo,node_schemas,node_worker toneRose
class node_payer,node_agent,node_nominee toneIndigo
```

## Components

### Worker application

- [React app routes](https://github.com/harinisricode18/pms-pension_management_system/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Auth state](https://github.com/harinisricode18/pms-pension_management_system/blob/main/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`
- [Income entry](https://github.com/harinisricode18/pms-pension_management_system/blob/main/frontend/src/pages/IncomePage.jsx): `frontend/src/pages/IncomePage.jsx`
- [Savings dashboard](https://github.com/harinisricode18/pms-pension_management_system/blob/main/frontend/src/pages/DashboardPage.jsx): `frontend/src/pages/DashboardPage.jsx`
- [Payer confirmation](https://github.com/harinisricode18/pms-pension_management_system/blob/main/frontend/src/pages/PayerPage.jsx): `frontend/src/pages/PayerPage.jsx`
- [API client](https://github.com/harinisricode18/pms-pension_management_system/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`

### API and workflows

- [FastAPI application](https://github.com/harinisricode18/pms-pension_management_system/blob/main/app.py): `app.py`
- [Income and deposits](https://github.com/harinisricode18/pms-pension_management_system/blob/main/routes/savings_routes.py): `routes/savings_routes.py`
- [Payer ledger routes](https://github.com/harinisricode18/pms-pension_management_system/blob/main/routes/ledger_routes.py): `routes/ledger_routes.py`
- [Withdrawal routes](https://github.com/harinisricode18/pms-pension_management_system/blob/main/routes/withdrawal_routes.py): `routes/withdrawal_routes.py`
- [Cash agent routes](https://github.com/harinisricode18/pms-pension_management_system/blob/main/routes/agent_routes.py): `routes/agent_routes.py`
- [Health score routes](https://github.com/harinisricode18/pms-pension_management_system/blob/main/routes/health_routes.py): `routes/health_routes.py`
- [Projection routes](https://github.com/harinisricode18/pms-pension_management_system/blob/main/routes/projection_routes.py): `routes/projection_routes.py`
- [API contracts](https://github.com/harinisricode18/pms-pension_management_system/blob/main/api_models.py): `api_models.py`

### Pension capabilities

- [Savings signal engine](https://github.com/harinisricode18/pms-pension_management_system/blob/main/services/financial_signal_engine.py): `services/financial_signal_engine.py`
- [Verified income ledger](https://github.com/harinisricode18/pms-pension_management_system/blob/main/services/ledger_protocol.py): `services/ledger_protocol.py`
- [Emergency shield](https://github.com/harinisricode18/pms-pension_management_system/blob/main/services/emergency_shield.py): `services/emergency_shield.py`
- [Dual-key governance](https://github.com/harinisricode18/pms-pension_management_system/blob/main/services/dual_key_governance.py): `services/dual_key_governance.py`
- [Digital cash bridge](https://github.com/harinisricode18/pms-pension_management_system/blob/main/services/digital_bridge.py): `services/digital_bridge.py`
- [Guardian guidance](https://github.com/harinisricode18/pms-pension_management_system/blob/main/services/guardian_agent.py): `services/guardian_agent.py`
- [Pension health engine](https://github.com/harinisricode18/pms-pension_management_system/blob/main/services/pension_health_engine.py): `services/pension_health_engine.py`
- [Retirement projection](https://github.com/harinisricode18/pms-pension_management_system/blob/main/services/pension_projection.py): `services/pension_projection.py`
- [Live notifications](https://github.com/harinisricode18/pms-pension_management_system/blob/main/ws_manager.py): `ws_manager.py`

### Identity and persistence

- [JWT authentication](https://github.com/harinisricode18/pms-pension_management_system/blob/main/auth_utils.py): `auth_utils.py`
- [Data access helpers](https://github.com/harinisricode18/pms-pension_management_system/blob/main/database/db_helpers.py): `database/db_helpers.py`
- [MongoDB collections](https://github.com/harinisricode18/pms-pension_management_system/blob/main/database/mongo_connection.py): `database/mongo_connection.py`
- [Stored data schemas](https://github.com/harinisricode18/pms-pension_management_system/blob/main/models/schemas.py): `models/schemas.py`

### Other components

- **Worker**
- **Payer**
- **Local cash agent**
- **Withdrawal nominee**
- **MongoDB**

## Connections

- Worker → React app routes: uses
- React app routes → Auth state: provides auth (evidence: `frontend/src/App.jsx`)
- React app routes → Income entry: routes to (evidence: `frontend/src/App.jsx`)
- React app routes → Savings dashboard: routes to (evidence: `frontend/src/App.jsx`)
- React app routes → Payer confirmation: routes to (evidence: `frontend/src/App.jsx`)
- Income entry → API client: calls (evidence: `frontend/src/pages/IncomePage.jsx`)
- Savings dashboard → API client: calls (evidence: `frontend/src/pages/DashboardPage.jsx`)
- Payer confirmation → API client: calls (evidence: `frontend/src/pages/PayerPage.jsx`)
- Auth state → API client: restores session (evidence: `frontend/src/context/AuthContext.jsx`)
- API client → FastAPI application: HTTP requests
- FastAPI application → Income and deposits: registers routes (evidence: `app.py`)
- FastAPI application → Payer ledger routes: registers routes (evidence: `app.py`)
- FastAPI application → Withdrawal routes: registers routes (evidence: `app.py`)
- FastAPI application → Cash agent routes: registers routes (evidence: `app.py`)
- FastAPI application → Health score routes: registers routes (evidence: `app.py`)
- FastAPI application → Projection routes: registers routes (evidence: `app.py`)
- Income and deposits → JWT authentication: authenticates (evidence: `routes/savings_routes.py`)
- Income and deposits → API contracts: validates requests (evidence: `routes/savings_routes.py`)
- Income and deposits → Savings signal engine: recomputes target (evidence: `routes/savings_routes.py`)
- Income and deposits → Emergency shield: coordinates deposits (evidence: `routes/savings_routes.py`)
- Income and deposits → Data access helpers: reads and writes (evidence: `routes/savings_routes.py`)
- Payer ledger routes → Verified income ledger: verifies payment (evidence: `routes/ledger_routes.py`)
- Payer ledger routes → Data access helpers: reads and writes (evidence: `routes/ledger_routes.py`)
- Withdrawal routes → Dual-key governance: checks approval (evidence: `routes/withdrawal_routes.py`)
- Withdrawal routes → Emergency shield: processes withdrawal (evidence: `routes/withdrawal_routes.py`)
- Cash agent routes → Digital cash bridge: settles cash (evidence: `routes/agent_routes.py`)
- Cash agent routes → Live notifications: broadcasts event (evidence: `routes/agent_routes.py`)
- Health score routes → Pension health engine: computes score (evidence: `routes/health_routes.py`)
- Projection routes → Retirement projection: projects retirement (evidence: `routes/projection_routes.py`)
- Savings signal engine → Data access helpers: reads income data (evidence: `services/financial_signal_engine.py`)
- Verified income ledger → Data access helpers: persists ledger (evidence: `services/ledger_protocol.py`)
- Emergency shield → Data access helpers: updates vaults (evidence: `services/emergency_shield.py`)
- Dual-key governance → Data access helpers: manages approvals (evidence: `services/dual_key_governance.py`)
- Digital cash bridge → Data access helpers: settles balances (evidence: `services/digital_bridge.py`)
- Guardian guidance → Data access helpers: reads worker data (evidence: `services/guardian_agent.py`)
- Pension health engine → Data access helpers: scores and updates (evidence: `services/pension_health_engine.py`)
- Retirement projection → Data access helpers: reads savings data
- Data access helpers → MongoDB collections: uses collections (evidence: `database/db_helpers.py`)
- MongoDB collections → MongoDB: connects to (evidence: `database/mongo_connection.py`)
- Stored data schemas → MongoDB: describes stored data
- Payer → Payer ledger routes: confirms payment (evidence: `routes/ledger_routes.py`)
- Local cash agent → Cash agent routes: confirms cash (evidence: `routes/agent_routes.py`)
- Withdrawal nominee → Withdrawal routes: submits approval