// System Design Documentation

Platform Architecture Overview

Current Backend — Service Topology, Domains & Request Lifecycle

01 — Client Layer
📱 MobileApp
iOS / Android
🖥 AdminWeb
Browser
HTTPS /api/learning/app
HTTPS /api/auth
02 — API Gateway
🔀 Gateway
Request Router + Rate Limiter
⚡ Redis
Rate Limit Cache
JWT Validate
Forward Request
03 — Application Services
🔐 AuthService
Authentication
🎓 LearningService
Core Business Logic
Read / Write
Read / Write
Cache / Lock
Push
Objects
04 — Infrastructure & External Services
🗄 AuthDB
PostgreSQL
🗄 LearningDB
PostgreSQL
⚡ Redis
Cache / Lock / Idempotency
🔔 FCM
Push Notifications
🗂 S3 Storage
Object Store
🍎 APNS
iOS Notifications
Application Service
Infrastructure
Client
External Service
📱 App APIs
ExamFlow
Rewards
Leaderboard
Content
Billing
⚙️ Admin APIs
Ranking
Rewards
Jobs
LearningService
CORE BUSINESS LOGIC
Central service handling all learning platform operations — exams, rankings, rewards, notifications, content delivery, and billing.
🎮 Game / Exam Flow
🏆 Ranking + Publish
🎁 Rewards + Claims
🔔 Notifications
📊 Leaderboard
📚 Content / Progress
💳 Billing / Subscriptions
⚡ Cache / Lock Layer
Redis Usage
Submit Idempotency Ranking Lock Throttling Leaderboard Cache Master Data Cache
🗄 Data Stores
LearningDB (PG)
Redis
S3 Object Store
🔌 External
FCM / APNS
⏱ Scheduling
Rank Exam @ 2AM
Admin Manual Trigger
Broadcast Optimization
📱
Mobile App
1Start attempt → API
2Receive attemptToken + question stream
3Submit response per question (choiceId, elapsedMs)
4Complete attempt → API
5Open push notification → deeplink API call
6Receive final screen data
⚙️
Learning Service
1Receive start → idempotency lock in Redis
2Create IN_PROGRESS attempt in DB
3Return attemptToken + stream questions
4Receive complete → throttle + idempotency checks
5Persist completion + PENDING result in DB
6Rank exam (2AM scheduled or admin trigger)
7Compute rank + economics + prize awards
8Publish results → send FCM notifications
🗄
Learning DB
1Write: Create IN_PROGRESS attempt
2Write: Persist response + timing per question
3Write: Persist attempt completion + PENDING result
4Write: Compute rank + economics + prize awards
5Write: Publish results
6Read: Fetch target data on deeplink action
⚡
Redis
1Start idempotency lock on attempt start
2Submit idempotency check on complete
3Throttle check on attempt complete
4Ranking lock during rank computation
5Rate-limit checks at Gateway layer
6Leaderboard + question-pool + master data cache
🔔
FCM / APNS
1Receive push payload from LearningService
2Dispatch winner/result notifications
3Route to APNS for iOS devices
4Deliver notification to client device
5Broadcast: no per-user persistence for global notifications
6Dispatch audit maintained separately
Redis Usage
Submit/start idempotency locks
Ranking lock during computation
Request throttling at API level
Leaderboard real-time cache
Question pool + master data caching
Gateway rate-limit checks
Reward Status Flow
ASSIGNED → REQUESTED → APPROVED / REJECTED → FULFILLED
CANCELLED for invalidated / withdrawn flow
Coupon Security Model
Coupon code not exposed in result metadata
Coupon resolved only at claim flow
Surfaced only to eligible learner
Resolved server-side — never in API response until claimed
Broadcast Notification Optimization
Per-user persistence avoided for global broadcasts
Dispatch audit maintained separately
Reduces DB write amplification at scale
FCM handles fan-out to devices directly
Ranking Computation
Scheduled daily at 2AM (automatic)
Admin manual trigger available outside schedule
Redis ranking lock prevents concurrent computation
Computes rank + economics + prize awards atomically
Publishes results → triggers FCM notifications
Request Security Flow
All requests carry JWT token
Gateway forwards to AuthService for introspection if needed
Redis rate-limit check at Gateway layer
Validated requests forwarded to LearningService
Idempotency enforced at service layer via Redis