# anurajx/credchain architecture

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

- Interactive diagram: https://gitdiagram.com/anurajx/credchain
- Repository: https://github.com/anurajx/credchain

## Overview

1. **Overall shape**
   CredChain India is a two-tier identity platform: a React/Vite frontend for citizen and officer workflows, and a Node/Express backend that owns identity logic, verification, persistence, and event logging. The core architectural idea is a **UVID-centered identity record** with **off-chain PII storage** and a separate **immutable audit/event layer**.

2. **Client application**
   The `frontend/` folder is a single-page application in TypeScript with multiple role-specific screens: citizen login, registration success, user profile, BLO/admin portal, audit trail, fuzzy detection, emergency access, scanner, map/heatmap views, and media pages. The UI also includes an India map component and geospatial datasets (`india.geojson`, `india-states.json`, `india-simplified.geojson`) for regional visualization.

3. **Frontend state and service boundary**
   The frontend appears to keep business logic thin and delegate core decisions to the backend. `src/config/api.ts` is the main integration boundary for API calls, while `ThemeContext.tsx` manages presentation-only state. `generateIdCard.ts` suggests the client can render or export an identity card once backend data is available.

4. **Backend API and orchestration**
   `backend/server.js` is the central application entry point. This layer likely exposes registration, verification, credential-management, audit, and monitoring endpoints. It is the main orchestration boundary between user actions, MongoDB persistence, identifier generation, and the blockchain-like event ledger.

5. **Identity data model**
   The backend models indicate the main domain entities: `citizen`, `voter`, `BLO`, and `confidence`. These likely represent the core registry record, credential-linked records, officer/BLO workflow data, and duplicate-check or trust scores. UVID is the primary cross-system key used to join all records.

6. **Identifier generation**
   `backend/UVID/generator.js` and `backend/EPIC/generator.js` show that identity numbers are generated in dedicated modules rather than inline. UVID is the system’s durable anchor, while EPIC generation appears to support voter/credential-related issuance or linkage. This is the point where “new citizen identity” is minted before downstream logging.

7. **Verification and duplicate detection**
   The repo contains explicit support for fuzzy matching and confidence scoring, reflected in the `confidence` model and the `fuzzyDetection` frontend page. The README describes name/DOB similarity checks, so the architecture includes a verification step where submitted identity requests are screened for likely duplicates before activation.

8. **Off-chain persistence**
   The backend is built around MongoDB-style persistence, evidenced by the seed scripts and `testMongo.js`. This is the system of record for citizen profiles, linked credentials, and workflow state. The README’s privacy model implies sensitive fields live here off-chain, likely encrypted or at least separated from the audit layer.

9. **Audit ledger / blockchain layer**
   The `backend/Blockchain/` folder contains `Blockchain.js`, `SolanaBlock.js`, and `block.js`, which indicates a custom ledger implementation rather than a full smart-contract stack inside the repo. Architecturally, this layer records lifecycle events such as creation, update, and deletion with hashes, timestamps, actor metadata, and credential type. The README frames this as an immutable audit trail, so the diagram should show a separate write-only integrity log.

10. **Important boundary: mock vs. real chain**
   Although the README references Polygon Mumbai and ethers.js, the file tree does not show a Solidity contract or chain deployment artifacts. For an accurate diagram, treat the current repository as having a **backend-managed blockchain abstraction/mock ledger** with possible future or external chain integration, not a fully self-contained on-chain system.

11. **Operational flows**
   The dominant data flow is:
   citizen submits registration or credential request → frontend calls backend API → backend validates and performs fuzzy checks → off-chain record is stored in MongoDB → UVID is assigned or reused → an immutable event is appended to the blockchain layer → frontend displays status, profile, or audit trail.  
   Officer review follows the same pattern but adds a human approval step before the record is activated.

12. **Monitoring and integrity checks**
   The `auditTrail`, `emergencyAccess`, `fuzzyDetection`, and `scanner` pages suggest auxiliary controls around detection and review. The system compares off-chain record state against the logged event history to detect tampering, and it can flag abnormal update behavior as suspicious. This is a monitoring layer sitting above both the database and the ledger.

13. **Messaging and external services**
   `backend/services/smsService.js` indicates at least one external operational integration for notification or OTP-style messaging. No other strong external dependencies are visible in the tree, so SMS is the only clearly material service boundary besides the database and any blockchain/network endpoint.

14. **Bootstrapping and demo data**
   `seed.js`, `seedVoters.js`, and the `ML_Models/model.ipynb` notebook point to local bootstrapping and experimentation tooling rather than production infrastructure. These files support populating sample identity data and experimenting with similarity or detection logic used by the fuzzy-check workflow.

15. **How to draw the architecture**
   The cleanest diagram is: **React SPA** on one side, **Express backend** in the middle, and two back-end persistence targets on the other side: **MongoDB/off-chain identity store** and **immutable ledger layer**. Show UVID as the shared key flowing through registration, verification, credential linking, and audit lookup, with sensitive data staying off-chain and only hashes/metadata entering the ledger.

Main entry points: [`backend/server.js`](https://github.com/anurajx/credchain/blob/main/backend/server.js) (API server), [`frontend/src/App.tsx`](https://github.com/anurajx/credchain/blob/main/frontend/src/App.tsx) (React app), [`frontend/src/pages/citizenLogin.tsx`](https://github.com/anurajx/credchain/blob/main/frontend/src/pages/citizenLogin.tsx) (Citizen views), [`frontend/src/pages/indiaMapPage.tsx`](https://github.com/anurajx/credchain/blob/main/frontend/src/pages/indiaMapPage.tsx) (Geo dashboards)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend SPA"]
  node_frontend_app["React app<br/>Vite SPA<br/>[App.tsx]"]
  node_frontend_pages_citizen["Citizen views<br/>UI pages<br/>[citizenLogin.tsx]"]
  node_frontend_pages_officer["Officer views<br/>UI pages<br/>[bloPortal.tsx]"]
  node_frontend_pages_geo["Geo dashboards<br/>UI views<br/>[indiaMapPage.tsx]"]
  node_frontend_api["API client<br/>HTTP boundary<br/>[api.ts]"]
  node_frontend_theme(("Theme state<br/>UI context<br/>[ThemeContext.tsx]"))
  node_frontend_idcard["ID card render<br/>UI utility<br/>[generateIdCard.ts]"]
  node_frontend_map["India map<br/>Map component<br/>[IndiaMap.tsx]"]
  node_geo_data["Geo data<br/>Static datasets<br/>[india.geojson]"]
end

subgraph group_backend["Backend API"]
  node_backend_server["API server<br/>Express app<br/>[server.js]"]
  node_backend_uvid["UVID minting<br/>Identifier service<br/>[generator.js]"]
  node_backend_epic["EPIC minting<br/>Identifier service<br/>[generator.js]"]
  node_backend_models[("Identity models<br/>Mongo models<br/>[citizen.js]")]
  node_backend_sms["SMS service<br/>External integration<br/>[smsService.js]"]
end

subgraph group_storage["State & Ledgers"]
  node_ledger{{"Ledger layer<br/>Immutable log<br/>[Blockchain.js]"}}
  node_ledger_block["Block records<br/>Ledger record<br/>[block.js]"]
  node_offchain_db[("Off-chain store<br/>MongoDB data<br/>[testMongo.js]")]
  node_seed_data["Seed data<br/>Bootstrap scripts<br/>[seed.js]"]
end

node_frontend_app -->|"routes to"| node_frontend_pages_citizen
node_frontend_app -->|"routes to"| node_frontend_pages_officer
node_frontend_app -->|"routes to"| node_frontend_pages_geo
node_frontend_app -->|"uses"| node_frontend_theme
node_frontend_pages_geo -->|"renders"| node_frontend_map
node_frontend_map -->|"loads"| node_geo_data
node_frontend_pages_citizen -->|"exports"| node_frontend_idcard
node_frontend_app -->|"calls"| node_frontend_api
node_frontend_api -->|"requests"| node_backend_server
node_backend_server -->|"mints"| node_backend_uvid
node_backend_server -->|"issues"| node_backend_epic
node_backend_server -->|"reads/writes"| node_backend_models
node_backend_server -->|"persists"| node_offchain_db
node_backend_server -->|"appends"| node_ledger
node_ledger -->|"stores"| node_ledger_block
node_backend_server -->|"notifies"| node_backend_sms
node_seed_data -.->|"populates"| node_offchain_db
node_backend_server -.->|"supports"| node_seed_data

click node_frontend_app "https://github.com/anurajx/credchain/blob/main/frontend/src/App.tsx"
click node_frontend_pages_citizen "https://github.com/anurajx/credchain/blob/main/frontend/src/pages/citizenLogin.tsx"
click node_frontend_pages_officer "https://github.com/anurajx/credchain/blob/main/frontend/src/pages/bloPortal.tsx"
click node_frontend_pages_geo "https://github.com/anurajx/credchain/blob/main/frontend/src/pages/indiaMapPage.tsx"
click node_frontend_api "https://github.com/anurajx/credchain/blob/main/frontend/src/config/api.ts"
click node_frontend_theme "https://github.com/anurajx/credchain/blob/main/frontend/src/contexts/ThemeContext.tsx"
click node_frontend_idcard "https://github.com/anurajx/credchain/blob/main/frontend/src/utils/generateIdCard.ts"
click node_frontend_map "https://github.com/anurajx/credchain/blob/main/frontend/src/components/IndiaMap.tsx"
click node_backend_server "https://github.com/anurajx/credchain/blob/main/backend/server.js"
click node_backend_uvid "https://github.com/anurajx/credchain/blob/main/backend/UVID/generator.js"
click node_backend_epic "https://github.com/anurajx/credchain/blob/main/backend/EPIC/generator.js"
click node_backend_models "https://github.com/anurajx/credchain/blob/main/backend/models/citizen.js"
click node_backend_sms "https://github.com/anurajx/credchain/blob/main/backend/services/smsService.js"
click node_ledger "https://github.com/anurajx/credchain/blob/main/backend/Blockchain/Blockchain.js"
click node_ledger_block "https://github.com/anurajx/credchain/blob/main/backend/Blockchain/block.js"
click node_offchain_db "https://github.com/anurajx/credchain/blob/main/backend/testMongo.js"
click node_seed_data "https://github.com/anurajx/credchain/blob/main/backend/seed.js"
click node_geo_data "https://github.com/anurajx/credchain/blob/main/frontend/public/india.geojson"

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_app,node_frontend_pages_citizen,node_frontend_pages_officer,node_frontend_pages_geo,node_frontend_api,node_frontend_theme,node_frontend_idcard,node_frontend_map,node_geo_data toneBlue
class node_backend_server,node_backend_uvid,node_backend_epic,node_backend_models,node_backend_sms toneAmber
class node_ledger,node_ledger_block,node_offchain_db,node_seed_data toneMint
```

## Components

### Frontend SPA

React/Vite client for citizen and officer workflows

- [React app](https://github.com/anurajx/credchain/blob/main/frontend/src/App.tsx): Vite SPA · Single-page client entry and routing shell · `frontend/src/App.tsx`
- [Citizen views](https://github.com/anurajx/credchain/blob/main/frontend/src/pages/citizenLogin.tsx): UI pages · Login, profile, registration success, card, and service screens · `frontend/src/pages/citizenLogin.tsx`
- [Officer views](https://github.com/anurajx/credchain/blob/main/frontend/src/pages/bloPortal.tsx): UI pages · Administrative, BLO portal, emergency access, scanner, and audit screens · `frontend/src/pages/bloPortal.tsx`
- [Geo dashboards](https://github.com/anurajx/credchain/blob/main/frontend/src/pages/indiaMapPage.tsx): UI views · Map, heatmap, and regional visualization pages · `frontend/src/pages/indiaMapPage.tsx`
- [API client](https://github.com/anurajx/credchain/blob/main/frontend/src/config/api.ts): HTTP boundary · Main frontend integration layer for backend calls · `frontend/src/config/api.ts`
- [Theme state](https://github.com/anurajx/credchain/blob/main/frontend/src/contexts/ThemeContext.tsx): UI context · Presentation-only application state · `frontend/src/contexts/ThemeContext.tsx`
- [ID card render](https://github.com/anurajx/credchain/blob/main/frontend/src/utils/generateIdCard.ts): UI utility · Client-side identity card generation and export · `frontend/src/utils/generateIdCard.ts`
- [India map](https://github.com/anurajx/credchain/blob/main/frontend/src/components/IndiaMap.tsx): Map component · Reusable geospatial visualization component · `frontend/src/components/IndiaMap.tsx`
- [Geo data](https://github.com/anurajx/credchain/blob/main/frontend/public/india.geojson): Static datasets · India boundary and state files used by map views · `frontend/public/india.geojson`

### Backend API

Express orchestration, identity logic, persistence, and audit logging

- [API server](https://github.com/anurajx/credchain/blob/main/backend/server.js): Express app · Central backend entry point and request orchestration · `backend/server.js`
- [UVID minting](https://github.com/anurajx/credchain/blob/main/backend/UVID/generator.js): Identifier service · Dedicated unique identity generation logic · `backend/UVID/generator.js`
- [EPIC minting](https://github.com/anurajx/credchain/blob/main/backend/EPIC/generator.js): Identifier service · Credential-linked identifier generation support · `backend/EPIC/generator.js`
- [Identity models](https://github.com/anurajx/credchain/blob/main/backend/models/citizen.js): Mongo models · Citizen, voter, BLO, and confidence domain records · `backend/models/citizen.js`
- [SMS service](https://github.com/anurajx/credchain/blob/main/backend/services/smsService.js): External integration · Notification or OTP-style messaging boundary · `backend/services/smsService.js`

### State & Ledgers

Primary data stores and integrity layers

- [Ledger layer](https://github.com/anurajx/credchain/blob/main/backend/Blockchain/Blockchain.js): Immutable log · Blockchain-style audit/event store for identity lifecycle changes · `backend/Blockchain/Blockchain.js`
- [Block records](https://github.com/anurajx/credchain/blob/main/backend/Blockchain/block.js): Ledger record · Event blocks with hashes, timestamps, actor metadata, and credential type · `backend/Blockchain/block.js`
- [Off-chain store](https://github.com/anurajx/credchain/blob/main/backend/testMongo.js): MongoDB data · System of record for sensitive identity profiles and workflow state · `backend/testMongo.js`
- [Seed data](https://github.com/anurajx/credchain/blob/main/backend/seed.js): Bootstrap scripts · Sample identity and voter population scripts · `backend/seed.js`

## Connections

- React app → Citizen views: routes to · Primary citizen workflow screens
- React app → Officer views: routes to · Officer and admin workflows
- React app → Geo dashboards: routes to · Map and regional analytics screens
- React app → Theme state: uses · Shared presentation state
- Geo dashboards → India map: renders · Uses reusable map component
- India map → Geo data: loads · Regional visualization datasets
- Citizen views → ID card render: exports · Identity card generation after data load
- React app → API client: calls · Client-to-backend boundary
- API client → API server: requests · API traffic for registration, verification, and audit
- API server → UVID minting: mints · Assigns durable identity keys
- API server → EPIC minting: issues · Credential or voter-linked identifiers
- API server → Identity models: reads/writes · Persisted identity and workflow records
- API server → Off-chain store: persists · Sensitive off-chain system of record
- API server → Ledger layer: appends · Immutable lifecycle events and hashes
- Ledger layer → Block records: stores · Ledger entries and block structure
- API server → SMS service: notifies · External messaging integration
- Seed data → Off-chain store: populates · Bootstrap identity records
- API server → Seed data: supports · Local initialization and demo data flows