anurajx/credchain

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.