LMS-BGN/docs/brainstorming-session-results-2025-11-12.md

# Brainstorming Session Results — Backend untuk LMS-BGN (2025-11-12)

## Konteks & Tujuan
- Kondisi saat ini: frontend Next.js 14 (app router) sudah MVP; alur learner dasar berjalan.
- Tujuan sesi: merumuskan pendekatan backend yang cepat, aman, dan selaras dengan brownfield frontend untuk mendukung kursus, ujian, sertifikat, analytics, dan reward.
- Prinsip: quick-flow (iteratif), minim gesekan integrasi, kontrak API jelas, dapat berevolusi ke arsitektur lebih kuat.

## Fokus Brainstorm (ringkas)
- User Pain Points: data progres dan hasil ujian belum persist; sertifikat & email perlu backend; admin butuh laporan.
- Fitur Backend: CRUD kursus/modul/lesson, pengerjaan kuis/ujian, skor & ringkasan, generasi sertifikat, email kirim ulang, analytics dasar, export.
- Pendekatan Teknis: 
  - Tahap A (cepat): Next.js Route Handlers (`src/app/api/*`) dengan ORM (Prisma) dan DB lokal (SQLite/MySQL Laragon).
  - Tahap B (mantap): Service backend terpisah (NestJS + PostgreSQL) + OpenAPI/JSON:API; migrasi bertahap.
- UX Operasional: API stabil untuk learner/admin; admin aman; observabilitas minimal.
- Nilai Bisnis: mempercepat penerbitan sertifikat dan pelaporan training; menjaga kualitas dapur.
- Diferensiasi: alur desktop yang nyaman, sertifikat otomatis, insight progress; evolusi ke reward.
- Risiko Teknis: skema data berubah, performa query, auth/session, email deliverability.
- Sukses: jalur utama persist (enroll → belajar → ujian → sertifikat), admin melihat ringkas progres, email kirim ulang sukses.

## Opsi Arsitektur & Pertimbangan
1) Next.js API Route Handlers (Tahap A)
- Pro: integrasi paling cepat dengan frontend; deployment satu artefak; reuse Typescript tipe; bisa mulai dengan SQLite.
- Kontra: keterbatasan pemisahan concern; scaling terbatas bila beban tinggi; coupling dengan web tier.
- Cocok untuk: MVP backend ringan, validasi kontrak, dan fitur sertifikat/email.

2) Backend Terpisah (NestJS/Express/Fastify) (Tahap B)
- Pro: arsitektur bersih; kontrol penuh atas middleware, auth, rate limit; scaling & observabilitas lebih baik.
- Kontra: biaya setup & dev lebih tinggi; perlu orkestrasi build/deploy.
- Cocok untuk: fase produksi, multi-tenant, beban tinggi, integrasi eksternal.

3) Serverless / BaaS (Supabase/Hasura/Firebase)
- Pro: time-to-market cepat; auth & storage siap; SQL/GraphQL out-of-the-box.
- Kontra: vendor lock-in; kompleksitas domain ujian/sertifikat; kebijakan compliance.
- Cocok untuk: spike cepat, atau komponen spesifik (auth/upload), bukan keseluruhan domain.

## Rekomendasi Jalur Quick-Flow
- Mulai Tahap A: Next.js API Route Handlers + Prisma.
- DB: **SQLite** untuk kecepatan lokal; opsi **MySQL Laragon** bila butuh concurrency; target migrasi **PostgreSQL** saat Tahap B.
- Email: Nodemailer dengan ENV (`SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASS`, `SMTP_SECURE`).
- Auth: sesi sederhana (cookie) di Tahap A; siapkan desain JWT/OAuth untuk Tahap B.
- Kontrak: tulis OpenAPI core endpoints; gunakan tipe shared (ts) agar konsisten FE/BE.

## Model Data (awal)
- `User`: id, name, email, role (learner/admin), createdAt.
- `Course`: id, title, description, prerequisites?, createdAt.
- `Module`: id, courseId, title, order, contentMeta.
- `Lesson`: id, moduleId, type (video/text/pdf), url/meta.
- `Quiz`: id, moduleId, questions[], scoring.
- `ExamSession`: id, courseId, userId, startedAt, finishedAt, score, status.
- `Certificate`: id, userId, courseId, issuedAt, status, url.
- `Progress`: userId, courseId, moduleId, percent, timeSpent, updatedAt.
- `Assignment`: id, courseId/moduleId, title, dueDate.

## Kontrak API (draft ringkas)
- Auth: `POST /api/auth/login`, `POST /api/auth/logout` (Tahap A sederhana).
- Course: `GET /api/courses`, `GET /api/courses/:id`, `POST /api/courses` (admin), `PUT/PATCH /api/courses/:id`.
- Module/Lesson: `GET /api/courses/:id/modules`, `GET /api/modules/:id/lessons`.
- Progress: `GET /api/progress/:courseId`, `POST /api/progress` (update modul: percent/timeSpent/complete).
- Quiz: `POST /api/quiz/:id/submit` → hasil & feedback.
- Exam: `POST /api/exams/:courseId/start`, `POST /api/exams/:sessionId/finish` → skor & summary.
- Certificate: `POST /api/certificates/:courseId/issue`, `POST /api/certificates/:id/resend-email`.
- Analytics: `GET /api/admin/analytics/overview`, `GET /api/admin/export/csv`.

## Email & Sertifikat (detail)
- Generator PDF: library (mis. `pdf-lib`/`pdfkit`) menghasilkan file ke storage (`/public/certificates` sementara).
- Resend email: gunakan Nodemailer; log sederhana (`email_logs`) untuk audit.

## Observabilitas & Keamanan (awal)
- Logging: minimal `pino`/console; audit event key (exam start/finish, certificate issued, email sent).
- Rate limit: middleware ringan untuk endpoint sensitif.
- Privacy: data peserta terbatas; tidak expose PII di log; ENV aman.

## Roadmap Implementasi Backend
- Sprint 1 (paralel FE): Progress API + Course/Module read, Quiz submit (demo), Email resend sertifikat.
- Sprint 2: ExamSession penuh + generate certificate + admin CRUD minimal.
- Sprint 3: Analytics overview + export CSV + harden auth + performa query.
- Sprint 4: Polishing, observabilitas, migrasi awal ke service backend (jika diperlukan).

## Risiko & Mitigasi
- Skema berubah: kontrak OpenAPI dan migration plan; gunakan Prisma migration.
- Performa: index tepat, batasi payload, caching ringan.
- Auth: mulai sederhana, desain untuk upgrade; audit akses admin.
- Email deliverability: konfigurasi SPF/DKIM di kemudian hari; fallback unduh PDF.

## Next Steps (Dokumentasi & Gate — tanpa implementasi)
1. Dokumentasikan skeleton OpenAPI minimal untuk endpoint inti (tanpa implementasi kode).
2. Ratifikasi model data awal di Tech Spec (status: rencana), tanpa commit skema.
3. Susun rencana ENV (`.env.local`) sebagai placeholder, tanpa kredensial nyata.
4. Petakan integrasi FE: jelaskan bagaimana `useProgressTracking` akan menggunakan kontrak API (tanpa menulis handler).
5. Definisikan Acceptance Gate untuk mulai backend: PRD & Tech Spec sign-off, skema data final, kesiapan DB & SMTP, alokasi waktu dev.

---
Catatan koreksi (2025-11-12): Dokumen ini berfungsi sebagai referensi ideasi non-implementasi. Semua langkah berorientasi dokumentasi/gate; eksekusi backend akan dimulai setelah gate terpenuhi dan disetujui.

---
Catatan: Sesi ini mengacu pada konteks brownfield (frontend sudah MVP) dan berorientasi quick-flow. Dokumen ini bukan spesifikasi final; gunakan bersama Tech Spec untuk eksekusi.