eKYC 3.0 — Backend Architecture

1 Tech Stack & Overview

The backend is a single ASP.NET Core 8.0 Web API application following Clean Architecture principles. It exposes ~150 REST endpoints organized by journey stage (0-15), admin portal, and WarRoom dashboard.

2 Component Diagram

The big picture: how requests flow from a Flutter/web client through the ASP.NET API into services, providers, and the database.

3 Clean Architecture Layers

Five projects arranged according to Clean Architecture. Dependencies flow inward: Api depends on Application and Infrastructure; both depend on Domain; Shared is a leaf with no dependencies.

4 Request Pipeline

Every HTTP request flows through this same sequence of middleware + filters before reaching a controller action.

5 Component Sequence Diagrams

5.1 Controller → Service → DbContext → Db

The generic backend call pattern every endpoint follows.

5.2 Service → ProviderChainExecutor → External API (with fallback)

6 Provider Chain Pattern

Every external integration (PAN, Bank, Face Match, eSign, Liveness, etc.) uses the same pattern: multiple providers, one interface, DB-driven config, automatic fallback.

How it works

1. ProviderChainExecutor<T> reads enabled providers from provider_configurations table ordered by priority
2. For each provider: checks circuit breaker state (skip if open)
3. If provider's mock_mode = true in DB, returns mock response and logs audit
4. Executes the operation with provider-specific timeout
5. On success: logs success to ApiAuditLog, updates health metrics, returns result
6. On failure: records failure in circuit breaker, logs to audit, falls through to next provider
7. If all providers exhausted: throws AllProvidersFailedException

7 Mock Mode Strategy

Mock mode is the development safety valve. With a single flag in appsettings.Development.json, all external provider calls bypass real APIs and return pre-defined mock responses.

Services that read GlobalMockEnabled

• BankAutoVerifyService - Decentro mobile-to-bank returns fake HDFC savings
• PanVerificationService - PAN returns mock success with fake name
• AadhaarVerificationService - DigiLocker returns mock redirect URL
• BankVerificationService - RPD returns mock redirect URL
• LivenessService - Returns mock success with high score
• SignatureService - Returns mock validation pass
• DocumentGenerationService - Returns mock PDF URL
• EsignService - Returns mock eSign redirect URL
• AccountCreationService - Returns mock clientId
• FundTransferService - Returns test Razorpay key
• FraudCheckService - C-SAFE always passes
• BackgroundCheckService - Zintlr / CSafe all skip

SMS and Email OTPs are separately controlled by Sms.Mode: FIXED_OTP and Email.Mode: FIXED_OTP with FixedOtp: "1234".

8 Database Schema Overview

PostgreSQL 14+ database named ekyc3 with a single schema ekyc. 75 tables total managed via EF Core 8 + EFCore.NamingConventions (automatic snake_case).

Table categories

Sync tables from data lake

Several reference master tables are expected to be populated by syncing from the existing MOSL data lake / legacy DB, not manually maintained. The full list and sync strategy is documented in the BRD Analysis folder:

• Sync Tables Master List - 22 tables requiring data sync from back-office / SEBI / RBI
• DB Actions Checklist - all schema setup steps before go-live

Typical sync tables: client_master, branch_master, subbroker_master, employee_pan_master, franchise_pan_whitelist (daily sync); negative_list (from SEBI), bank_ifsc_masters (from RBI). See Database page for details.

9 Hangfire & Background Jobs

Hangfire 1.8 provides durable background job processing backed by PostgreSQL. Dashboard available at /hangfire during development.

builder.Services.AddHangfire(config =>
    config
        .SetDataCompatibilityLevel(CompatibilityLevel.Version_180)
        .UseSimpleAssemblyNameTypeSerializer()
        .UseRecommendedSerializerSettings()
        .UsePostgreSqlStorage(opts =>
            opts.UseNpgsqlConnection(
                builder.Configuration.GetConnectionString("EkycDb"))));

builder.Services.AddHangfireServer();

Background workers

• ActivityLogWriterService (HostedService) - reads from async JourneyActivityChannel, batches writes to journey_activity_logs
• Hangfire jobs for: downstream event publishing to Kafka, payment status polling, CS journey expiry, objection correction deadline enforcement