eKYC 3.0 — Frontend Architecture

1 Overview & Tech Stack

The eKYC 3.0 frontend is a Flutter application built once in Dart and compiled natively to Android, iOS, and Web. It provides a 16-stage digital onboarding journey for opening Demat accounts.

2 Component Diagram - Full System View

How all components in the eKYC frontend connect with each other and with external services. Boxes represent components, lines represent dependencies/interactions.

3 Component Sequence Diagrams

These diagrams show architectural component interactions - how the layers and classes talk to each other, independent of any specific business flow. Use these to understand the wiring of the app.

3.1 - API Call Pipeline (how any screen talks to the backend)

Every network call in the app follows this same pattern, regardless of stage or method. This diagram shows the internal component chain from a Screen to the backend and back.

3.2 - Reactive State Update Loop (Flutter widget + state)

How a user event triggers a UI rebuild. This is the mental model for vanilla setState - no external state library involved.

3.3 - Wrapper Widget Composition Chain

How cross-cutting concerns (back button, session timeout, loading) are layered as wrapper widgets without inheritance or mixins.

3.4 - Singleton Storage Access (cross-component shared state)

How multiple services/screens share the same session data via the StorageService singleton.

3.5 - Build-Time Config Resolution

How the compile-time environment flag flows through components. No runtime lookups, no config files - everything is a Dart constant.

4 Layered Architecture

The app follows a clean layered architecture with strict unidirectional data flow. Each layer has a single responsibility and depends only on layers below it.

5 Code-Level Architecture Patterns

The codebase deliberately uses simple, well-known patterns that any Flutter developer can pick up. No heavyweight frameworks.

6 State Management - Why Vanilla setState?

The new app uses plain setState instead of BLoC, Provider, Riverpod, or any state management library. Here's why and how it's structured.

Why no BLoC?

7 Network Layer

Single ApiService class wraps the http package with auth, error handling, session tracking, and a typed result wrapper.

Generic _post helper (simplified)

Future<ApiResponse<T>> _post<T>(
  String url,
  Map<String, dynamic> body, {
  required T Function(Map<String, dynamic>) fromJson,
}) async {
  // 1. Auto-inject leadId from storage
  body['leadId'] ??= _storage.leadId;

  try {
    final response = await http.post(
      Uri.parse(url),
      headers: _headers,                  // JWT + X-Session-Id auto-added
      body: jsonEncode(body),
    ).timeout(ApiConfig.apiTimeout);

    await _storage.updateActivity();    // session timer reset

    final json = jsonDecode(response.body);
    if (response.statusCode == 200 && json['success'] == true) {
      return ApiResponse.ok(fromJson(json['data']));
    }
    return ApiResponse.fail(json['message'], json['errorCode']);
  } on SocketException {
    return ApiResponse.fail('No internet connection');
  } catch (e) {
    return ApiResponse.fail('Something went wrong');
  }
}

8 Navigation & Routing

Static named routes via MaterialApp.routes. No GoRouter, no navigator 2.0. Stage progression uses pushReplacementNamed to prevent back-stack accumulation.

class AppRoutes {
  static const stage0Arrival = '/';
  static const stage1Registration = '/registration';
  static const stage2Otp = '/otp';
  // ... 16 routes total

  static const stageRoutes = {
    0: stage0Arrival,
    1: stage1Registration,
    // ...
  };
}

// Forward only - no back stack
Navigator.pushReplacementNamed(
  context,
  AppRoutes.stage7Liveness,
);

// Resume from any stage on app launch
final route = AppRoutes
  .stageRoutes[currentStage]
  ?? AppRoutes.stage1Registration;

9 Widget Composition

Cross-cutting concerns are wrapper widgets that compose around screen content. No mixins, no inheritance hierarchies.

Composition pattern

return BackButtonHandler(
  child: SessionTimer(
    child: Scaffold(
      appBar: AppBar(title: const Text('Bank Verification')),
      body: LoadingOverlay(
        isLoading: _isLoading,
        message: 'Verifying...',
        child: Column(
          children: [
            const JourneyProgressBar(currentStage: 6),
            _buildBody(),
          ],
        ),
      ),
    ),
  ),
);

10 Environment & Build Config

Build-time environment selection via --dart-define. No runtime config files, no environment switchers in the UI.

// lib/config/api_config.dart
class ApiConfig {
  static const _env = String.fromEnvironment('ENV', defaultValue: 'dev');

  static String get baseUrl {
    switch (_env) {
      case 'prod': return 'https://ekyc.motilaloswal.com';
      case 'uat':  return 'https://ekycuat.motilaloswaluat.com';
      default:    return 'http://localhost:5000';
    }
  }

  static bool get isDev => _env == 'dev';
  static bool get isProd => _env == 'prod';
}

11 Platform Build Pipeline

Single Dart codebase → Flutter compiler → native binaries for each platform.

12 Mock Mode Strategy

The frontend is completely unaware of mock mode. All mock behavior is driven by the backend's GlobalMockEnabled flag. The frontend only detects mock URLs in responses and bypasses external launches.

13 Annexures: Platform Build Details

Platform-specific build configurations, commands, permissions, and plugin integration details. Click to expand each section.

# Debug APK
flutter build apk --debug

# Release APK (split per ABI)
flutter build apk --release \
  --split-per-abi \
  --dart-define=ENV=prod

# App Bundle for Play Store
flutter build appbundle --release \
  --dart-define=ENV=prod \
  --obfuscate \
  --split-debug-info=build/symbols

// android/app/build.gradle.kts
android {
    namespace = "com.motilaloswal.ekyc"
    compileSdk = 34

    defaultConfig {
        applicationId = "com.motilaloswal.ekyc"
        minSdk = 21
        targetSdk = 34
        versionCode = flutter.versionCode
        versionName = flutter.versionName
    }

    buildTypes {
        release {
            signingConfig = signingConfigs.getByName("release")
            isMinifyEnabled = true
            isShrinkResources = true
        }
    }
}

dependencies {
    implementation("androidx.core:core-ktx:1.12.0")
    implementation("androidx.appcompat:appcompat:1.6.1")
}

# Debug build (simulator)
flutter build ios --debug --simulator

# Release IPA for TestFlight
flutter build ipa --release \
  --dart-define=ENV=prod \
  --export-options-plist=ios/ExportOptions.plist

# Open in Xcode for signing
open ios/Runner.xcworkspace

<key>NSCameraUsageDescription</key>
<string>Required for selfie capture and document upload</string>

<key>NSLocationWhenInUseUsageDescription</key>
<string>Required to verify your location during onboarding</string>

<key>NSPhotoLibraryUsageDescription</key>
<string>Required to upload PAN, Aadhaar, and bank proof documents</string>

# ios/Podfile (auto-managed)
platform :ios, '12.0'

target 'Runner' do
  use_frameworks!
  use_modular_headers!

  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
end

14 Appendix: Functional Flow Sequences

The diagrams in this section show specific business flows (registration, OTP, payment, etc.) rather than architectural interactions. Click to expand.