# mathalama/superapp architecture

> Architecture diagram of the GitHub repository mathalama/superapp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mathalama/superapp
- Repository: https://github.com/mathalama/superapp

## Overview

SuperApp is a fintech identity platform with web and mobile clients, authentication, user profiles, and an AI-assisted KYC workflow. The primary KYC path is document and selfie capture, submission through the web API, KYC orchestration, ML verification, and a result shown in the dashboard. Identity, profile, and notification services provide supporting capabilities; events connect identity/KYC activity to notifications. The README documents service-level integrations, while sampled source confirms selected UI, ML, auth, and storage behavior; links within unsampled service internals are therefore limited.

Main entry points: [`services/api-gateway/src/main/java/dev/mathalama/apigateway/ApiGatewayApplication.java`](https://github.com/mathalama/superapp/blob/dev/services/api-gateway/src/main/java/dev/mathalama/apigateway/ApiGatewayApplication.java) (API Gateway), [`services/kyc-service/src/main/java/dev/mathalama/kycservice/application/usecase/KycUseCaseImpl.java`](https://github.com/mathalama/superapp/blob/dev/services/kyc-service/src/main/java/dev/mathalama/kycservice/application/usecase/KycUseCaseImpl.java) (KYC Orchestrator), [`services/kyc-ml-service/app/main.py`](https://github.com/mathalama/superapp/blob/dev/services/kyc-ml-service/app/main.py) (KYC ML API), [`services/identity-service/src/main/java/dev/mathalama/identityservice/infrastructure/security/handler/OAuth2SuccessHandler.java`](https://github.com/mathalama/superapp/blob/dev/services/identity-service/src/main/java/dev/mathalama/identityservice/infrastructure/security/handler/OAuth2SuccessHandler.java) (OAuth Success Handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client Applications"]
  node_web_app["KYC Web App<br/>[App.tsx]"]
  node_web_api["Web API Client<br/>[api.ts]"]
  node_mobile_app["Android Client<br/>[MainActivity.kt]"]
end

subgraph group_edge["API Edge"]
  node_gateway["API Gateway"]
  node_jwt_relay["JWT Relay"]
end

subgraph group_identity["Identity and Profiles"]
  node_identity_api["Identity Controllers"]
  node_identity_usecases["Identity Use Cases"]
  node_oauth_handler["OAuth Success Handler"]
  node_identity_store[("Identity Database")]
  node_token_store[("Token and Session Cache")]
  node_user_api["Profile Controller"]
  node_profile_usecase["Profile Use Case"]
  node_profile_store[("Profile Database")]
  node_avatar_storage[("Avatar Object Storage")]
end

subgraph group_verification["KYC Verification"]
  node_kyc_ui["KYC Capture and Results<br/>[DocumentWizard.tsx]"]
  node_kyc_api["KYC Controller<br/>[KycController.java]"]
  node_kyc_usecase["KYC Orchestrator"]
  node_kyc_store[("KYC Database")]
  node_document_storage[("KYC Document Storage")]
  node_ml_client["ML Inference Client"]
  node_ml_api["KYC ML API<br/>[main.py]"]
  node_ml_ocr["OCR and MRZ<br/>[ocr_mrz_reader.py]"]
  node_ml_liveness["Liveness Detection"]
  node_ml_face["Face Matching<br/>[face_matcher.py]"]
end

subgraph group_events["Events and Notifications"]
  node_kafka["Kafka Broker"]
  node_notification_consumer["Notification Consumers"]
  node_idempotency[("Event Deduplication")]
  node_email_service["Email Dispatcher<br/>[EmailService.java]"]
end

node_end_user(("Platform User"))
node_smtp(("SMTP Provider"))

node_end_user -->|"uses"| node_web_app
node_end_user -->|"uses"| node_mobile_app
node_web_app -->|"renders"| node_kyc_ui
node_web_app -->|"submits KYC"| node_web_api
node_web_api -->|"sends requests"| node_gateway
node_mobile_app -.->|"API access"| node_gateway
node_gateway -->|"filters requests"| node_jwt_relay
node_gateway -->|"routes requests"| node_identity_api
node_gateway -->|"routes requests"| node_user_api
node_gateway -->|"routes requests"| node_kyc_api
node_identity_api -->|"invokes"| node_identity_usecases
node_identity_usecases -->|"reads and writes"| node_identity_store
node_identity_api -->|"manages tokens"| node_token_store
node_oauth_handler -->|"reads and writes"| node_identity_store
node_oauth_handler -->|"creates exchange code"| node_token_store
node_oauth_handler -->|"publishes events"| node_kafka
node_user_api -->|"invokes"| node_profile_usecase
node_profile_usecase -->|"reads and writes"| node_profile_store
node_profile_usecase -->|"stores avatars"| node_avatar_storage
node_kyc_ui -->|"captures and submits"| node_web_api
node_kyc_api -->|"invokes"| node_kyc_usecase
node_kyc_usecase -->|"stores documents"| node_document_storage
node_kyc_usecase -->|"requests inference"| node_ml_client
node_ml_client -->|"posts images"| node_ml_api
node_kyc_usecase -->|"reads and writes"| node_kyc_store
node_kyc_usecase -->|"publishes KYC events"| node_kafka
node_ml_api -->|"extracts document data"| node_ml_ocr
node_ml_api -->|"evaluates selfie"| node_ml_liveness
node_ml_api -->|"compares faces"| node_ml_face
node_kafka -->|"delivers events"| node_notification_consumer
node_notification_consumer -->|"deduplicates"| node_idempotency
node_notification_consumer -->|"dispatches email"| node_email_service
node_email_service -->|"sends mail"| node_smtp

click node_web_app "https://github.com/mathalama/superapp/blob/dev/web/kyc/src/App.tsx"
click node_web_api "https://github.com/mathalama/superapp/blob/dev/web/kyc/src/services/api.ts"
click node_mobile_app "https://github.com/mathalama/superapp/blob/dev/mobile/android/app/src/main/kotlin/dev/mathalama/app/MainActivity.kt"
click node_gateway "https://github.com/mathalama/superapp/blob/dev/services/api-gateway/src/main/java/dev/mathalama/apigateway/ApiGatewayApplication.java"
click node_jwt_relay "https://github.com/mathalama/superapp/blob/dev/services/api-gateway/src/main/java/dev/mathalama/apigateway/filter/JwtRelayFilter.java"
click node_identity_api "https://github.com/mathalama/superapp/blob/dev/services/identity-service/src/main/java/dev/mathalama/identityservice/presentation/controller/AuthController.java"
click node_identity_usecases "https://github.com/mathalama/superapp/blob/dev/services/identity-service/src/main/java/dev/mathalama/identityservice/application/usecase/AuthUseCaseImpl.java"
click node_oauth_handler "https://github.com/mathalama/superapp/blob/dev/services/identity-service/src/main/java/dev/mathalama/identityservice/infrastructure/security/handler/OAuth2SuccessHandler.java"
click node_identity_store "https://github.com/mathalama/superapp/blob/dev/services/identity-service/src/main/java/dev/mathalama/identityservice/infrastructure/persistence/adapter/UserRepositoryAdapter.java"
click node_token_store "https://github.com/mathalama/superapp/blob/dev/services/identity-service/src/main/java/dev/mathalama/identityservice/infrastructure/cache/RedisTokenStore.java"
click node_user_api "https://github.com/mathalama/superapp/blob/dev/services/user-service/src/main/java/dev/mathalama/userservice/presentation/controller/UserProfileController.java"
click node_profile_usecase "https://github.com/mathalama/superapp/blob/dev/services/user-service/src/main/java/dev/mathalama/userservice/application/usecase/UserProfileUseCaseImpl.java"
click node_profile_store "https://github.com/mathalama/superapp/blob/dev/services/user-service/src/main/java/dev/mathalama/userservice/infrastructure/persistence/adapter/UserProfileRepositoryAdapter.java"
click node_avatar_storage "https://github.com/mathalama/superapp/blob/dev/services/user-service/src/main/java/dev/mathalama/userservice/infrastructure/storage/S3AvatarStorageAdapter.java"
click node_kyc_ui "https://github.com/mathalama/superapp/blob/dev/web/kyc/src/components/DocumentWizard.tsx"
click node_kyc_api "https://github.com/mathalama/superapp/blob/dev/services/kyc-service/src/main/java/dev/mathalama/kycservice/presentation/controller/KycController.java"
click node_kyc_usecase "https://github.com/mathalama/superapp/blob/dev/services/kyc-service/src/main/java/dev/mathalama/kycservice/application/usecase/KycUseCaseImpl.java"
click node_kyc_store "https://github.com/mathalama/superapp/blob/dev/services/kyc-service/src/main/java/dev/mathalama/kycservice/infrastructure/persistence/adapter/KycRepositoryAdapter.java"
click node_document_storage "https://github.com/mathalama/superapp/blob/dev/services/kyc-service/src/main/java/dev/mathalama/kycservice/infrastructure/storage/S3KycStorageAdapter.java"
click node_ml_client "https://github.com/mathalama/superapp/blob/dev/services/kyc-service/src/main/java/dev/mathalama/kycservice/infrastructure/client/MlInferenceClientAdapter.java"
click node_ml_api "https://github.com/mathalama/superapp/blob/dev/services/kyc-ml-service/app/main.py"
click node_ml_ocr "https://github.com/mathalama/superapp/blob/dev/services/kyc-ml-service/app/pipeline/ocr_mrz_reader.py"
click node_ml_liveness "https://github.com/mathalama/superapp/blob/dev/services/kyc-ml-service/app/pipeline/liveness_detector.py"
click node_ml_face "https://github.com/mathalama/superapp/blob/dev/services/kyc-ml-service/app/pipeline/face_matcher.py"
click node_notification_consumer "https://github.com/mathalama/superapp/blob/dev/services/notification-service/src/main/java/dev/mathalama/notificationservice/consumer/UserEventConsumer.java"
click node_idempotency "https://github.com/mathalama/superapp/blob/dev/services/notification-service/src/main/java/dev/mathalama/notificationservice/service/IdempotencyService.java"
click node_email_service "https://github.com/mathalama/superapp/blob/dev/services/notification-service/src/main/java/dev/mathalama/notificationservice/service/EmailService.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web_app,node_web_api,node_mobile_app,node_end_user toneBlue
class node_gateway,node_jwt_relay toneAmber
class node_identity_api,node_identity_usecases,node_oauth_handler,node_identity_store,node_token_store,node_user_api,node_profile_usecase,node_profile_store,node_avatar_storage toneMint
class node_kyc_ui,node_kyc_api,node_kyc_usecase,node_kyc_store,node_document_storage,node_ml_client,node_ml_api,node_ml_ocr,node_ml_liveness,node_ml_face toneRose
class node_kafka,node_notification_consumer,node_idempotency,node_email_service,node_smtp toneIndigo
```

## Components

### Client Applications

- [KYC Web App](https://github.com/mathalama/superapp/blob/dev/web/kyc/src/App.tsx): `web/kyc/src/App.tsx`
- [Web API Client](https://github.com/mathalama/superapp/blob/dev/web/kyc/src/services/api.ts): `web/kyc/src/services/api.ts`
- [Android Client](https://github.com/mathalama/superapp/blob/dev/mobile/android/app/src/main/kotlin/dev/mathalama/app/MainActivity.kt): `mobile/android/app/src/main/kotlin/dev/mathalama/app/MainActivity.kt`

### API Edge

- [API Gateway](https://github.com/mathalama/superapp/blob/dev/services/api-gateway/src/main/java/dev/mathalama/apigateway/ApiGatewayApplication.java): `services/api-gateway/src/main/java/dev/mathalama/apigateway/ApiGatewayApplication.java`
- [JWT Relay](https://github.com/mathalama/superapp/blob/dev/services/api-gateway/src/main/java/dev/mathalama/apigateway/filter/JwtRelayFilter.java): `services/api-gateway/src/main/java/dev/mathalama/apigateway/filter/JwtRelayFilter.java`

### Identity and Profiles

- [Identity Controllers](https://github.com/mathalama/superapp/blob/dev/services/identity-service/src/main/java/dev/mathalama/identityservice/presentation/controller/AuthController.java): `services/identity-service/src/main/java/dev/mathalama/identityservice/presentation/controller/AuthController.java`
- [Identity Use Cases](https://github.com/mathalama/superapp/blob/dev/services/identity-service/src/main/java/dev/mathalama/identityservice/application/usecase/AuthUseCaseImpl.java): `services/identity-service/src/main/java/dev/mathalama/identityservice/application/usecase/AuthUseCaseImpl.java`
- [OAuth Success Handler](https://github.com/mathalama/superapp/blob/dev/services/identity-service/src/main/java/dev/mathalama/identityservice/infrastructure/security/handler/OAuth2SuccessHandler.java): `services/identity-service/src/main/java/dev/mathalama/identityservice/infrastructure/security/handler/OAuth2SuccessHandler.java`
- [Identity Database](https://github.com/mathalama/superapp/blob/dev/services/identity-service/src/main/java/dev/mathalama/identityservice/infrastructure/persistence/adapter/UserRepositoryAdapter.java): `services/identity-service/src/main/java/dev/mathalama/identityservice/infrastructure/persistence/adapter/UserRepositoryAdapter.java`
- [Token and Session Cache](https://github.com/mathalama/superapp/blob/dev/services/identity-service/src/main/java/dev/mathalama/identityservice/infrastructure/cache/RedisTokenStore.java): `services/identity-service/src/main/java/dev/mathalama/identityservice/infrastructure/cache/RedisTokenStore.java`
- [Profile Controller](https://github.com/mathalama/superapp/blob/dev/services/user-service/src/main/java/dev/mathalama/userservice/presentation/controller/UserProfileController.java): `services/user-service/src/main/java/dev/mathalama/userservice/presentation/controller/UserProfileController.java`
- [Profile Use Case](https://github.com/mathalama/superapp/blob/dev/services/user-service/src/main/java/dev/mathalama/userservice/application/usecase/UserProfileUseCaseImpl.java): `services/user-service/src/main/java/dev/mathalama/userservice/application/usecase/UserProfileUseCaseImpl.java`
- [Profile Database](https://github.com/mathalama/superapp/blob/dev/services/user-service/src/main/java/dev/mathalama/userservice/infrastructure/persistence/adapter/UserProfileRepositoryAdapter.java): `services/user-service/src/main/java/dev/mathalama/userservice/infrastructure/persistence/adapter/UserProfileRepositoryAdapter.java`
- [Avatar Object Storage](https://github.com/mathalama/superapp/blob/dev/services/user-service/src/main/java/dev/mathalama/userservice/infrastructure/storage/S3AvatarStorageAdapter.java): `services/user-service/src/main/java/dev/mathalama/userservice/infrastructure/storage/S3AvatarStorageAdapter.java`

### KYC Verification

- [KYC Capture and Results](https://github.com/mathalama/superapp/blob/dev/web/kyc/src/components/DocumentWizard.tsx): `web/kyc/src/components/DocumentWizard.tsx`
- [KYC Controller](https://github.com/mathalama/superapp/blob/dev/services/kyc-service/src/main/java/dev/mathalama/kycservice/presentation/controller/KycController.java): `services/kyc-service/src/main/java/dev/mathalama/kycservice/presentation/controller/KycController.java`
- [KYC Orchestrator](https://github.com/mathalama/superapp/blob/dev/services/kyc-service/src/main/java/dev/mathalama/kycservice/application/usecase/KycUseCaseImpl.java): `services/kyc-service/src/main/java/dev/mathalama/kycservice/application/usecase/KycUseCaseImpl.java`
- [KYC Database](https://github.com/mathalama/superapp/blob/dev/services/kyc-service/src/main/java/dev/mathalama/kycservice/infrastructure/persistence/adapter/KycRepositoryAdapter.java): `services/kyc-service/src/main/java/dev/mathalama/kycservice/infrastructure/persistence/adapter/KycRepositoryAdapter.java`
- [KYC Document Storage](https://github.com/mathalama/superapp/blob/dev/services/kyc-service/src/main/java/dev/mathalama/kycservice/infrastructure/storage/S3KycStorageAdapter.java): `services/kyc-service/src/main/java/dev/mathalama/kycservice/infrastructure/storage/S3KycStorageAdapter.java`
- [ML Inference Client](https://github.com/mathalama/superapp/blob/dev/services/kyc-service/src/main/java/dev/mathalama/kycservice/infrastructure/client/MlInferenceClientAdapter.java): `services/kyc-service/src/main/java/dev/mathalama/kycservice/infrastructure/client/MlInferenceClientAdapter.java`
- [KYC ML API](https://github.com/mathalama/superapp/blob/dev/services/kyc-ml-service/app/main.py): `services/kyc-ml-service/app/main.py`
- [OCR and MRZ](https://github.com/mathalama/superapp/blob/dev/services/kyc-ml-service/app/pipeline/ocr_mrz_reader.py): `services/kyc-ml-service/app/pipeline/ocr_mrz_reader.py`
- [Liveness Detection](https://github.com/mathalama/superapp/blob/dev/services/kyc-ml-service/app/pipeline/liveness_detector.py): `services/kyc-ml-service/app/pipeline/liveness_detector.py`
- [Face Matching](https://github.com/mathalama/superapp/blob/dev/services/kyc-ml-service/app/pipeline/face_matcher.py): `services/kyc-ml-service/app/pipeline/face_matcher.py`

### Events and Notifications

- **Kafka Broker**
- [Notification Consumers](https://github.com/mathalama/superapp/blob/dev/services/notification-service/src/main/java/dev/mathalama/notificationservice/consumer/UserEventConsumer.java): `services/notification-service/src/main/java/dev/mathalama/notificationservice/consumer/UserEventConsumer.java`
- [Event Deduplication](https://github.com/mathalama/superapp/blob/dev/services/notification-service/src/main/java/dev/mathalama/notificationservice/service/IdempotencyService.java): `services/notification-service/src/main/java/dev/mathalama/notificationservice/service/IdempotencyService.java`
- [Email Dispatcher](https://github.com/mathalama/superapp/blob/dev/services/notification-service/src/main/java/dev/mathalama/notificationservice/service/EmailService.java): `services/notification-service/src/main/java/dev/mathalama/notificationservice/service/EmailService.java`

### Other components

- **Platform User**
- **SMTP Provider**

## Connections

- Platform User → KYC Web App: uses
- Platform User → Android Client: uses
- KYC Web App → KYC Capture and Results: renders
- KYC Web App → Web API Client: submits KYC
- Web API Client → API Gateway: sends requests
- Android Client → API Gateway: API access
- API Gateway → JWT Relay: filters requests
- API Gateway → Identity Controllers: routes requests
- API Gateway → Profile Controller: routes requests
- API Gateway → KYC Controller: routes requests
- Identity Controllers → Identity Use Cases: invokes
- Identity Use Cases → Identity Database: reads and writes
- Identity Controllers → Token and Session Cache: manages tokens
- OAuth Success Handler → Identity Database: reads and writes
- OAuth Success Handler → Token and Session Cache: creates exchange code
- OAuth Success Handler → Kafka Broker: publishes events
- Profile Controller → Profile Use Case: invokes
- Profile Use Case → Profile Database: reads and writes
- Profile Use Case → Avatar Object Storage: stores avatars
- KYC Capture and Results → Web API Client: captures and submits
- KYC Controller → KYC Orchestrator: invokes
- KYC Orchestrator → KYC Document Storage: stores documents
- KYC Orchestrator → ML Inference Client: requests inference
- ML Inference Client → KYC ML API: posts images
- KYC Orchestrator → KYC Database: reads and writes
- KYC Orchestrator → Kafka Broker: publishes KYC events
- KYC ML API → OCR and MRZ: extracts document data
- KYC ML API → Liveness Detection: evaluates selfie
- KYC ML API → Face Matching: compares faces
- Kafka Broker → Notification Consumers: delivers events
- Notification Consumers → Event Deduplication: deduplicates
- Notification Consumers → Email Dispatcher: dispatches email
- Email Dispatcher → SMTP Provider: sends mail