How mathalama/superapp works
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: ApiGatewayApplication.java API Gateway · KycUseCaseImpl.java KYC Orchestrator · main.py KYC ML API · OAuth2SuccessHandler.java OAuth Success Handler
Components 30
Client Applications
- KYC Web App
web/kyc/src/App.tsx - Web API Client
web/kyc/src/services/api.ts - Android Client
mobile/android/app/src/main/kotlin/dev/mathalama/app/MainActivity.kt
API Edge
- API Gateway
services/api-gateway/src/main/java/dev/mathalama/apigateway/ApiGatewayApplication.java - JWT Relay
services/api-gateway/src/main/java/dev/mathalama/apigateway/filter/JwtRelayFilter.java
Identity and Profiles
- Identity Controllers
services/identity-service/src/main/java/dev/mathalama/identityservice/presentation/controller/AuthController.java - Identity Use Cases
services/identity-service/src/main/java/dev/mathalama/identityservice/application/usecase/AuthUseCaseImpl.java - OAuth Success Handler
services/identity-service/src/main/java/dev/mathalama/identityservice/infrastructure/security/handler/OAuth2SuccessHandler.java - Identity Database
services/identity-service/src/main/java/dev/mathalama/identityservice/infrastructure/persistence/adapter/UserRepositoryAdapter.java - Token and Session Cache
services/identity-service/src/main/java/dev/mathalama/identityservice/infrastructure/cache/RedisTokenStore.java - Profile Controller
services/user-service/src/main/java/dev/mathalama/userservice/presentation/controller/UserProfileController.java - Profile Use Case
services/user-service/src/main/java/dev/mathalama/userservice/application/usecase/UserProfileUseCaseImpl.java - Profile Database
services/user-service/src/main/java/dev/mathalama/userservice/infrastructure/persistence/adapter/UserProfileRepositoryAdapter.java - Avatar Object Storage
services/user-service/src/main/java/dev/mathalama/userservice/infrastructure/storage/S3AvatarStorageAdapter.java
KYC Verification
- KYC Capture and Results
web/kyc/src/components/DocumentWizard.tsx - KYC Controller
services/kyc-service/src/main/java/dev/mathalama/kycservice/presentation/controller/KycController.java - KYC Orchestrator
services/kyc-service/src/main/java/dev/mathalama/kycservice/application/usecase/KycUseCaseImpl.java - KYC Database
services/kyc-service/src/main/java/dev/mathalama/kycservice/infrastructure/persistence/adapter/KycRepositoryAdapter.java - KYC Document Storage
services/kyc-service/src/main/java/dev/mathalama/kycservice/infrastructure/storage/S3KycStorageAdapter.java - ML Inference Client
services/kyc-service/src/main/java/dev/mathalama/kycservice/infrastructure/client/MlInferenceClientAdapter.java - KYC ML API
services/kyc-ml-service/app/main.py - OCR and MRZ
services/kyc-ml-service/app/pipeline/ocr_mrz_reader.py - Liveness Detection
services/kyc-ml-service/app/pipeline/liveness_detector.py - Face Matching
services/kyc-ml-service/app/pipeline/face_matcher.py
Events and Notifications
- Kafka Broker
- Notification Consumers
services/notification-service/src/main/java/dev/mathalama/notificationservice/consumer/UserEventConsumer.java - Event Deduplication
services/notification-service/src/main/java/dev/mathalama/notificationservice/service/IdempotencyService.java - Email Dispatcher
services/notification-service/src/main/java/dev/mathalama/notificationservice/service/EmailService.java
Other components
- Platform User
- SMTP Provider
Connections 33
- 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