02 — High-Level Design (HLD)
Dokumen ini menjelaskan arsitektur sistem ELJoy secara keseluruhan — komponen utama, bagaimana mereka saling terhubung, dan alur data dari user sampai AI.
Arsitektur Sistem
┌──────────────────┐
│ User Devices │
│ (Web / Mobile) │
└────────┬─────────┘
│ HTTPS
▼
┌────────────────────────┐
│ Cloudflare (CDN + │
│ WAF + DDoS Shield) │
└────────────┬───────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────────┐ ┌──────────────┐
│ Static CDN │ │ API Server │ │ WebSocket / │
│ (R2/Assets) │ │ (Hono.js) │ │ SSE Server │
└──────────────┘ └────────┬─────────┘ └──────┬───────┘
│ │
┌───────────────┼────────────────────┤
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ PostgreSQL │ │ Redis │ │ AI Services │
│ (Data Store) │ │ (Cache/Queue)│ │ (LLM/STT/ │
│ │ │ │ │ TTS) │
└──────────────┘ └──────────────┘ └──────────────┘
Komponen Utama
1. API Server (Hono.js)
Jantung dari seluruh sistem. Menerima semua request dari frontend, memproses logika bisnis, dan mengorkestrasi komunikasi ke database, cache, dan AI services.
┌─────────────────────────────────────────────────────┐
│ API SERVER │
│ │
│ ┌───────────┐ ┌───────────┐ ┌──────────────┐ │
│ │ Middleware │ │ Routes / │ │ Services │ │
│ │ Stack │ │ Controllers│ │ (Business │ │
│ │ │ │ │ │ Logic) │ │
│ │ • CORS │ │ • /auth │ │ │ │
│ │ • Auth │ │ • /assess │ │ • UserSvc │ │
│ │ • Logger │ │ • /learn │ │ • AssessSvc │ │
│ │ • RateLimit│ │ • /chat │ │ • LearnSvc │ │
│ │ • Validate│ │ • /content│ │ • ChatSvc │ │
│ │ │ │ • /member │ │ • ContentSvc │ │
│ │ │ │ • /admin │ │ • MemberSvc │ │
│ └───────────┘ └───────────┘ │ • AISvc │ │
│ └──────────────┘ │
│ │
│ ┌──────────────────────────────────────────────┐ │
│ │ Data Access Layer │ │
│ │ Drizzle ORM → PostgreSQL │ │
│ │ ioredis → Redis │ │
│ │ S3 Client → Cloudflare R2 │ │
│ └──────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘
2. Database Layer
PostgreSQL (Primary Data Store)
├── User & Auth tables → Akun, session, OAuth
├── Assessment tables → Hasil assessment, learner profile
├── Learning Journey tables → Blueprint, objectives, missions
├── Content tables → Domain, topic, speaking content
├── Conversation tables → Session, messages, evaluations
├── Membership tables → Subscriptions, payments, invoices
└── Admin tables → Audit log, system config
Redis (Cache & Real-time)
├── Session cache → Login session (TTL 7d)
├── API rate limits → Per-user/per-IP counters
├── AI context cache → Conversation context (TTL 30m)
├── Job queue → BullMQ jobs
└── Pub/Sub → Real-time notifications
3. AI Services Layer
┌───────────────────────────────────────────────┐
│ AI ORCHESTRATOR │
│ (Vercel AI SDK + Custom) │
│ │
│ ┌─────────────────┐ ┌───────────────────┐ │
│ │ LLM Provider │ │ Voice Provider │ │
│ │ │ │ │ │
│ │ OpenAI GPT-4o │ │ Deepgram Nova-2 │ │
│ │ (Companion AI) │ │ (Speech-to-Text) │ │
│ │ │ │ │ │
│ │ Gemini Flash │ │ OpenAI TTS │ │
│ │ (Assessment) │ │ (Text-to-Speech) │ │
│ └─────────────────┘ └───────────────────┘ │
│ │
│ ┌──────────────────────────────────────────┐ │
│ │ Prompt Template Engine │ │
│ │ • System prompts per mode/context │ │
│ │ • User context injection │ │
│ │ • Guardrails & safety filters │ │
│ └──────────────────────────────────────────┘ │
└───────────────────────────────────────────────┘
Alur Data Utama
Alur 1: User Registrasi & Login
User Frontend API Server Database
│ │ │ │
│ ── Klik Register ──►│ │ │
│ │ ── POST /auth/register ──► │
│ │ │ ── Insert user ──►│
│ │ │ ◄── User created ──│
│ │ │ ── Create session ►│
│ │ ◄── Set cookie + user data ── │
│ ◄── Redirect ke onboarding ── │ │
Alur 2: Assessment (Ice Breaker)
User Frontend API Server AI Service Database
│ │ │ │ │
│ ─ Tap Mic ──►│ │ │ │
│ │ ── Record Audio ──│ │ │
│ ─ Bicara ───►│ │ │ │
│ │ ── POST /assess/ │ │ │
│ │ ice-breaker ───► │ │
│ │ │ ── STT ────────►│ │
│ │ │ ◄── Transcript ─│ │
│ │ │ ── Evaluate ───►│ │
│ │ │ ◄── Scores ─────│ │
│ │ │ ── Save result ─────────────────►│
│ │ ◄── SSE Stream ───│ │ │
│ │ (feedback) │ │ │
│ ◄── Tampilkan│ │ │ │
│ hasil │ │ │ │
Alur 3: Speaking Practice Session (Conversation Mode)
User Frontend API Server AI Service Redis DB
│ │ │ │ │ │
│ ─ Tap Mic ──►│ │ │ │ │
│ ─ Bicara ───►│ │ │ │ │
│ │ ── Audio ─────►│ │ │ │
│ │ │ ── STT ───────►│ │ │
│ │ │ ◄── Text ──────│ │ │
│ │ │ │ │ │
│ │ │ ── Get context ─────────────►│ │
│ │ │ ◄── Prev messages ───────────│ │
│ │ │ │ │ │
│ │ │ ── Stream LLM ►│ │ │
│ │ ◄── SSE ───────│ ◄── Tokens ────│ │ │
│ ◄── Word by │ │ │ │ │
│ word ─────│ │ │ │ │
│ │ │ ── TTS ───────►│ │ │
│ │ ◄── Audio chunk│ ◄── Audio ─────│ │ │
│ ◄── Play ────│ │ │ │ │
│ suara AI │ │ │ │ │
│ │ │ ── Save msg ───────────────────────────►│
│ │ │ ── Cache ctx ──────────────►│ │
Alur 4: Membership & Payment
User Frontend API Server Payment Gateway DB
│ │ │ │ │
│ ─ Pilih plan►│ │ │ │
│ │ ── POST /membership/subscribe ────► │
│ │ │ ── Create order ────────────────►│
│ │ │ ── Create payment ►│ │
│ │ ◄── Payment URL ── │ │
│ ◄── Redirect │ │ │ │
│ ke payment│ │ │ │
│ ── Bayar ───►│ │ │ │
│ │ │ ◄── Webhook: paid ─│ │
│ │ │ ── Activate sub ────────────────►│
│ │ ◄── Sub active│ │ │
│ ◄── Member! ─│ │ │ │
Modul-Modul Sistem
Sistem dibagi menjadi 7 modul utama yang masing-masing bisa dikembangkan secara independen:
┌─────────────────────────────────────────────────────────────┐
│ ELJOY BACKEND │
├─────────┬──────────┬──────────┬──────────┬─────────────────┤
│ AUTH │ ASSESS │ LEARN │ CHAT │ CONTENT │
│ MODULE │ MODULE │ MODULE │ MODULE │ MODULE │
│ │ │ │ │ │
│ • Regist│ • Ice │ • Blue- │ • Voice │ • Domain/Topic │
│ • Login │ Breaker│ print │ Session│ • Speaking │
│ • OAuth │ • Univer-│ • Object-│ • SSE │ Content │
│ • Session│ sal │ ives │ Stream │ • CEFR Mapping │
│ • Profile│ • Adapt-│ • Mission│ • AI │ • Media Upload │
│ │ ive │ • Progress│ Eval │ │
├─────────┴──────────┴──────────┴──────────┴─────────────────┤
│ MEMBERSHIP MODULE │ ADMIN MODULE │
│ │ │
│ • Subscription plans │ • Dashboard │
│ • Payment integration │ • User management │
│ • Invoice & billing │ • Content CMS │
│ • Usage tracking │ • Analytics & reports │
└──────────────────────────────┴───────────────────────────────┘
Strategi Komunikasi
| Komunikasi | Protokol | Penggunaan |
|---|---|---|
| Frontend ↔ API | REST + JSON | Semua CRUD operations (user, content, membership) |
| Frontend ← API (Streaming) | SSE (Server-Sent Events) | AI response streaming, real-time feedback |
| API → AI Services | HTTPS | LLM API calls, STT/TTS API calls |
| API → Database | TCP (PostgreSQL wire protocol) | Query & mutation data via Drizzle ORM |
| API → Redis | TCP (Redis protocol) | Cache, session, queue operations |
| API → Storage | HTTPS (S3 protocol) | Upload/download file audio & media |
| Payment Gateway → API | Webhook (HTTPS POST) | Notifikasi pembayaran berhasil/gagal |
Prinsip Arsitektur
-
Modular Monolith — Mulai sebagai satu aplikasi server yang terstruktur modular, bukan microservices. Lebih sederhana untuk tim kecil, tapi struktur kodenya siap dipecah kalau perlu.
-
API-First — Semua fitur diakses melalui API. Tidak ada server-side rendering. Frontend dan backend benar-benar terpisah.
-
Streaming by Default — Semua respons AI menggunakan SSE streaming agar user tidak menunggu. Kata demi kata langsung muncul.
-
Stateless Server — Server tidak menyimpan state di memory. Semua state ada di database atau Redis. Ini memungkinkan horizontal scaling.
-
Fail Gracefully — Kalau AI service down, user tetap bisa browsing konten dan melihat progress. Kalau payment gateway down, order tetap tersimpan dan diproses saat up.
-
Cost-Conscious — Pilih teknologi yang biaya operasionalnya rendah di awal (free tier friendly), tapi bisa scale saat bisnis bertumbuh.