5. Architecture
This section is the engineering view of the platform. It translates the product modules and the integrations into a deployable, scaleable, audit-ready shape — with concrete artefacts (DDL, sequence diagrams, API contracts, worked data) rather than abstractions alone.
What’s in this section
Section titled “What’s in this section”| Page | Purpose |
|---|---|
| 5.1 High-level architecture | Layers, deployments, multi-AZ shape, request flows |
| 5.2 Services and modules | Modular monolith vs microservices; module boundaries; extraction triggers |
| 5.3 Core data model | Conceptual entity catalogue with relations |
| 5.4 Events and async | Event bus, idempotency, retries, DLQ, event sourcing |
| 5.5 Workflow and rules engines | Workflow engine choice + rule engine choice with rationale |
| 5.6 Data platform and warehouse | OLTP vs OLAP split, ETL, dbt, BI, feature store |
| 5.7 Security, IAM, audit | SSO, RBAC, secrets, PII vault, audit log integrity, IT-MD alignment |
| 5.8 Sequence diagrams | Mermaid sequence diagrams for the 8 core flows |
| 5.9 Schema reference | First-cut PostgreSQL DDL per module |
| 5.10 API catalogue | 40+ key APIs with payloads and conventions |
| 5.11 Worked data example | One synthetic borrower’s data at every stage |
| 5.12 Development conventions | Repo structure, Spring Boot skeleton, testing, CI/CD, code review |
Principles
Section titled “Principles”-
Module boundaries follow product boundaries. Each major product module from Section 3 is a logical service / package with a defined public API. Cross-module access happens via API, not direct database joins.
-
Sync read paths, async write fan-out. A sanction event triggers documentation, disbursement queue, reporting, analytics; these are async, not chained synchronous. Loose coupling buys reliability.
-
Idempotency everywhere. Every state-affecting external API call carries an idempotency key; every consumer dedupes. Retry-safe by default.
-
PII minimisation by tokenisation. Sensitive PII (PAN, Aadhaar, mobile, bank account) is tokenised at the boundary; clear text lives in the PII vault and is accessed only by services with explicit need. The main DB carries tokens only.
-
Event sourcing for accounting-affecting flows. Every loan-affecting event is an immutable record in
loan_event. Current state (current_outstanding,current_classification) is a materialised projection. History is the ground truth; current state is derived. -
Multi-AZ from day one; multi-region by year 2. RBI IT MD expects geographic separation between primary and DR. Mumbai primary, Hyderabad DR.
-
Java / Spring Boot bias. Engineering team strength; mature fintech ecosystem. See Section 14 for stack specifics.
-
Buy primitives, build orchestration and domain. KYC / BSA / AA / GST / eSign / NACH are bought; underwriting / co-lending / reconciliation / portfolio analytics are built.
How the architecture decisions cascade
Section titled “How the architecture decisions cascade”The choice tree, in dependency order:
- Modular monolith first (5.2) → drives the package structure (5.12) and the schema layout per module (5.9).
- Sync REST + async events (5.4) → drives API patterns (5.10) and event topic taxonomy.
- Workflow engine for long-running orchestration (5.5) → drives sequence-diagram patterns for sanction-to-disbursement, settlement, restructuring (5.8).
- OLTP / OLAP split (5.6) → CDC out of PostgreSQL; warehouse drives reporting and analytics.
- PII tokenisation + audit hash chain (5.7) → required from day one; expensive to retrofit.
Reading order
Section titled “Reading order”- Backend engineer joining the team: 5.2 → 5.12 → 5.9 → 5.10 → 5.11 → 5.8.
- Architect / lead: 5.1 → 5.2 → 5.4 → 5.5 → 5.7.
- Data engineer: 5.6 → 5.3 → 5.9.
- InfoSec / compliance: 5.7 → 2.13 IT MD → 2.14 Outsourcing MD.
- Cloud / SRE: 14.4 Infrastructure → 5.7 → 5.6.
What’s intentionally not here
Section titled “What’s intentionally not here”- Frontend architecture for the borrower portal, partner portal, admin console, field-agent app. These are mostly conventional React / React Native applications; their architecture is uncomplicated by the platform’s standards and lives in their own repos.
- Frontend design system / component library — relevant but separate concern.
- Marketing site, growth dashboards, content tooling — out of platform scope.
- Finance / treasury system — typically a separate ERP / accounting tool (Zoho / Tally / NetSuite) integrated rather than built in-platform.