v1
⌘K

System Architecture

Dhanam Finance is an enterprise-grade NBFC (Non-Banking Financial Company) investment management platform. This document provides a comprehensive overview of the system architecture.

📌 Tech Stack
Backend: Fastify + Node.js + TypeScript
Database: MongoDB with TimeSeries collections
Cache: Redis (sessions, rate limiting)
Dashboard: Next.js 14 + Tailwind CSS
Mobile App: Flutter + Dart

High-Level Architecture

graph TB subgraph "Client Layer" A["📱 Mobile App
(Flutter)"] B["💻 Admin Dashboard
(Next.js)"] end subgraph "API Layer" C["🔧 Backend Server
(Fastify)"] D["🔐 Auth Middleware
(JWT + RBAC)"] E["📡 WebSocket
(Real-time)"] end subgraph "Data Layer" F[("🗄️ MongoDB
Primary DB")] G[("⚡ Redis
Sessions/Cache")] end subgraph "External Services" H["📧 Email Service"] I["📱 SMS Gateway"] J["🔔 Push Notifications"] end A --> C B --> C C --> D C --> E D --> F D --> G C --> H C --> I C --> J style A fill:#10b981,color:#fff style B fill:#3b82f6,color:#fff style C fill:#8b5cf6,color:#fff style F fill:#f59e0b,color:#fff style G fill:#ef4444,color:#fff

Backend Architecture

The backend is built on Fastify, a high-performance Node.js framework. It follows a modular architecture with clear separation of concerns.

Module Structure

graph LR subgraph "API Modules" A["/auth"] --> B["Login/TFA/Logout"] C["/admin"] --> D["Users/Roles/Settings"] E["/customers"] --> F["Customer CRUD"] G["/ncd-series"] --> H["Series Management"] I["/ncd-investment"] --> J["Investments"] K["/approvals"] --> L["Approval Workflows"] M["/mobile"] --> N["Customer APIs"] O["/dashboard"] --> P["Chat/Tickets"] end

Backend Folder Structure

nbfc_backend/
├── src/
│   ├── server.ts           # Fastify server setup
│   ├── plugins/            # Fastify plugins
│   │   ├── db.ts           # MongoDB connection
│   │   ├── redis.ts        # Redis connection
│   │   ├── auth-middleware.ts  # JWT verification
│   │   └── websocket.ts    # WebSocket for real-time
│   ├── modules/            # API modules
│   │   ├── auth/           # Authentication
│   │   ├── admin/          # Admin operations
│   │   ├── customers/      # Customer management
│   │   ├── dashboard/      # Dashboard APIs
│   │   └── mobile/         # Mobile app APIs
│   ├── services/           # Business logic services
│   │   ├── smsService.ts
│   │   ├── emailService.ts
│   │   ├── notificationService.ts
│   │   └── audit-logger.ts
│   └── utils/              # Utility functions
└── docs/                   # API documentation

Data Flow

Investment Creation Flow

sequenceDiagram participant D as Dashboard participant A as API Server participant DB as MongoDB participant R as Redis D->>A: POST /admin/ncd-investment A->>A: Validate JWT Token A->>A: Check Permission (ncd-investment:create) A->>DB: Verify Customer Exists A->>DB: Create NCD Investment A->>DB: Create Audit Log A->>R: Clear Cache A->>D: Return Investment Details

Mobile OTP Login Flow

sequenceDiagram participant M as Mobile App participant A as API Server participant SMS as SMS Gateway participant DB as MongoDB participant R as Redis M->>A: POST /mobile/auth/send-otp A->>DB: Check Customer Exists A->>A: Generate OTP (6 digits) A->>R: Store OTP (5 min TTL) A->>SMS: Send OTP SMS SMS->>M: SMS Delivered M->>A: POST /mobile/auth/verify-otp A->>R: Verify OTP A->>A: Generate JWT Token A->>R: Create Session A->>M: Return Token + Profile

Security Architecture

Layer Technology Purpose
Authentication JWT (JSON Web Tokens) Stateless authentication for API requests
Two-Factor Auth TOTP (Google Authenticator) Additional security for admin users
Authorization RBAC (Role-Based Access Control) Granular permission management
Session Management Redis Track active sessions, enable logout
IP Restriction Custom Middleware Whitelist office IPs for admin access
Audit Logging MongoDB TimeSeries Track all security-critical actions

Frontend Architecture

Admin Dashboard (Next.js)

nbfc_frontend/
├── app/                    # Next.js App Router
│   ├── (auth)/             # Auth pages (login)
│   └── (main)/             # Main dashboard pages
│       ├── dashboard/      # Overview
│       ├── customers/      # Customer management
│       ├── ncd-series/     # NCD series
│       ├── allotment/      # Folio allotment
│       ├── approvals/      # Approval workflows
│       ├── transfer/       # Investment transfers
│       └── ...
├── components/             # React components
│   ├── ui/                 # Shadcn UI components
│   ├── customers/          # Customer-specific
│   └── ncd/                # NCD-specific
├── lib/                    # API utilities
└── store/                  # Redux/Zustand stores

Mobile App (Flutter)

dhanam_flutter/
└── lib/
    ├── main.dart           # App entry point
    ├── models/             # Data models
    ├── providers/          # State management (Provider)
    ├── screens/            # UI screens
    │   ├── home_screen.dart
    │   ├── login_screen.dart
    │   ├── investments_screen.dart
    │   ├── profile_screen.dart
    │   └── ...
    ├── services/           # API & business logic
    │   ├── api_service.dart
    │   └── notification_service.dart
    └── widgets/            # Reusable widgets

Deployment Architecture

graph TB subgraph "Production Environment" LB["🌐 Load Balancer
(Nginx)"] subgraph "Application Servers" AS1["Backend Server 1"] AS2["Backend Server 2"] end subgraph "Frontend" FE["Next.js
(SSR/Static)"] end subgraph "Database Layer" MDB["MongoDB
(Replica Set)"] RD["Redis
(Cluster)"] end end LB --> AS1 LB --> AS2 LB --> FE AS1 --> MDB AS2 --> MDB AS1 --> RD AS2 --> RD
✅ Production Ready
The architecture supports horizontal scaling, high availability, and enterprise-grade security requirements.

Next Steps