MVP Plan: XPrivate

Overview

MVP untuk platform guru les privat yang menghubungkan murid, guru, dan backoffice (admin/owner). Fokus utama adalah memastikan les privat berjalan tercatat dengan baik melalui sistem triple-konfirmasi dan evidence upload.

Scope:

• Backoffice dashboard / console untuk admin & owner
• Auth & role system (murid, guru, admin, owner)
• Order & pembayaran (transfer manual dengan bukti upload)
• Lesson session management & triple confirmation
• Presence reporting (wajib dari guru)
• Photo evidence upload ke R2

Out of Scope (Post-MVP):

• Website publik (landing page) — tidak termasuk MVP, admin langsung mengakses backoffice
• Interface penuh untuk murid & guru (hanya profile yang wajib)
• Kalender murid untuk booking jadwal
• Google Calendar sync
• 2FA (sudah direncanakan di auth tapi tidak diimplementasikan)
• Payment gateway otomatis

---

Phase 0: Foundation

Goal: Working infrastructure dengan auth, database, API shell, web shell, dan docs shell.

0.1 Monorepo Setup

• pnpm-workspace.yaml dengan catalog dependencies
• Root package.json dengan biome, lefthook, turbo, typescript, wrangler
• turbo.json untuk build orchestration
• .gitignore standar Cloudflare + monorepo

0.2 Database Schema (packages/db)

Create Drizzle schema files di packages/db/src/schema/:

File	Tables	Notes
orders.ts	orders, payment_proofs	Order dari murid, bukti bayar di R2
lessons.ts	lesson_sessions	Jadwal les, status, guru & murid assignment
confirmations.ts	lesson_confirmations	Triple-confirmation: start/end dari guru & murid
presence.ts	presence_reports	Laporan guru setelah les selesai
evidence.ts	session_evidence	Foto bukti les di R2

better-auth tables (managed by better-auth Drizzle adapter):

• user (extended dengan role, phone, profilePictureUrl)
• session
• account
• verification

0.3 Auth Setup (packages/auth)

• Configure better-auth dengan Drizzle adapter
• Enable Google OAuth plugin
• Enable Email/Password plugin dengan scrypt hasher (node:crypto.scrypt)
• Enable Magic Link plugin via Resend
• Enable Bearer plugin untuk Authorization: Bearer <token> header auth
• Enable JWT plugin untuk /api/auth/token dan /api/auth/jwks endpoints
• Add role field ke user table via additionalFields
• Setup 4 roles: student, teacher, admin, owner

0.4 Email Setup (packages/email)

• Resend client configuration
• Magic link email template
• Notification email helpers (optional untuk MVP)

0.5 Storage Setup (packages/storage)

• R2 client configuration
• Upload helper dengan validation (image only, max 5MB)
• Public URL generator

0.6 API Entrypoint (apps/api)

• Wire better-auth handler di /api/auth/*
• Implement whoami oRPC route
• Setup OpenAPIHandler dengan proper spec generation
• Add CORS middleware untuk frontend communication
• Health check di /api/health
• R2 storage context injection

0.7 Frontend Shell (apps/web)

- SvelteKit + Vite + Tailwind + shadcn-svelte
- Configure TanStack Query for Svelte client
- Setup SvelteKit routing with route structure
- Create basic layout shell (header, nav, footer)
- Dark mode support via CSS variables

0.8 Docs Shell (apps/docs)

• VitePress setup dengan sidebar structure
• Deploy ke Cloudflare Pages
• Hot docs principle aktif

Deliverable: Dev environment berfungsi — bisa sign in (via better-auth), hit /api/health, dan docs site deploy.

---

Phase 1: Auth, Roles, & Profile

Goal: Sistem auth lengkap dengan 4 role dan halaman profile.

1.1 Auth Flows

Registration:

• Murid dan guru bisa register via Google OAuth atau Email/Password
• Default role untuk registrasi: student
• Guru yang register perlu verifikasi admin (status: pending → active)

Login Methods:

• Google OAuth
• Email/Password
• Magic Link (email OTP)

Role Assignment:

• owner: manual seed saat setup awal
• admin: hanya bisa di-invite oleh owner via backoffice
• admin mutual exclusive dengan student/teacher — admin tidak bisa jadi student/teacher

1.2 Profile Page

Halaman /profile yang wajib ada untuk semua role:

Field	Required	Notes
Nama lengkap	Ya	Dari auth atau diisi manual
Email	Ya	Dari auth, read-only
Nomor telepon	Ya	Untuk kontak les
Foto profil	Optional	Upload ke R2
Bio / tentang	Optional	Untuk guru: keahlian, pengalaman
Role	Read-only	Dari auth context

1.3 Auth Middleware & Route Guards

• publicProcedure — health
• authedProcedure — any logged-in user
• muridProcedure — role = murid
• guruProcedure — role = guru
• adminProcedure — role = admin atau owner
• ownerProcedure — role = owner only

1.4 Frontend Auth Integration

• Auth store dengan better-auth client
• getAuth() atau auth store untuk session & role
• Route guards di +page.ts/+layout.ts untuk protected routes
• Login page dengan 3 opsi: Google, Email/Password, Magic Link

Deliverable: User bisa register, login dengan 3 metode, melihat profile, dan update profile. Role system berfungsi.

---

Phase 2: Order & Pembayaran

Goal: Murid bisa membuat order les dan upload bukti pembayaran.

2.1 Order Service (apps/api/src/services/order/)

Implement service mixins:

• create-order.ts — Murid membuat order baru
• get-order.ts — Get order detail (ownership check)
• list-orders.ts — List orders untuk murid atau admin
• upload-payment-proof.ts — Upload bukti bayar ke R2, link ke order
• verify-order.ts — Admin verifikasi pembayaran (admin only)
• cancel-order.ts — Cancel order (murid/admin)

2.2 Order Schema

orders:
  id, student_id, subject, duration_hours, total_price, status, notes, created_at, updated_at

status enum: pending → paid → verified → cancelled

2.3 Pembayaran Flow

1. Murid membuat order — Pilih mata pelajaran, durasi, catatan
2. Murid upload bukti bayar — Upload foto transfer ke R2
   • Validasi: image only, max 5MB
   • Tersimpan di payment_proofs table dengan R2 URL
3. Alternatif: WhatsApp/manual — Murid bisa WA admin, admin upload bukti atas nama murid
   • payment_proofs.uploaded_by_admin_id nullable
4. Admin verifikasi — Admin review bukti bayar, ubah status ke verified
5. Admin jadwalkan les — Setelah verified, admin buat lesson_session

2.4 Frontend Pages

• /admin/orders — Backoffice list orders dengan filter status
• /admin/orders/:id — Detail order + preview bukti bayar + action verify/cancel
• Order creation flow (bisa di backoffice atau halaman murid — untuk MVP, order bisa dibuat murid atau admin)

Deliverable: Murid bisa buat order dan upload bukti bayar. Admin bisa verifikasi. Order status tracked dengan baik.

---

Phase 3: Lesson Session & Triple Confirmation

Goal: Sistem les dengan triple-konfirmasi (guru-murid-backoffice).

3.1 Lesson Session Service (apps/api/src/services/lesson/)

Implement service mixins:

• create-lesson-session.ts — Admin membuat jadwal les dari order yang verified
• get-lesson-session.ts — Get detail session
• list-lesson-sessions.ts — List sessions (murid/guru/admin)
• update-lesson-session.ts — Update jadwal (admin)
• cancel-lesson-session.ts — Cancel session (admin)

3.2 Confirmation Service (apps/api/src/services/confirmation/)

Implement service mixins:

• confirm-start.ts — Guru atau murid confirm les dimulai
• confirm-end.ts — Guru atau murid confirm les selesai
• get-confirmations.ts — List confirmations untuk session
• check-confirmation-status.ts — Cek apakah both sides sudah confirm

3.3 Lesson Session Schema

lesson_sessions:
  id, order_id, teacher_id, student_id, subject, scheduled_at, duration_hours,
  status, location, notes, created_at, updated_at

status enum: scheduled → ongoing → completed → cancelled

3.4 Confirmation Schema

lesson_confirmations:
  id, session_id, user_id, type, confirmed_at, notes, created_at

type enum: teacher_start, student_start, teacher_end, student_end

3.5 Triple Confirmation Flow

[Les Dimulai]
  Guru confirm "les dimulai"     → lesson_confirmations (type: teacher_start)
  Murid confirm "les dimulai"    → lesson_confirmations (type: student_start)
  Backoffice monitor             → Dashboard menampilkan status konfirmasi
  Jika mismatch (hanya satu yang confirm):
    → Backoffice bisa intervenes, hubungi pihak yang belum confirm
    → Admin bisa override/resolve dispute

[Les Selesai]
  Guru confirm "les selesai"     → lesson_confirmations (type: teacher_end)
  Murid confirm "les selesai"    → lesson_confirmations (type: student_end)
  Backoffice monitor             → Dashboard update status
  Jika mismatch:
    → Backoffice investigasi dan resolve

3.6 Session Status Transitions

scheduled
  ↓ teacher_start + student_start confirmed
ongoing
  ↓ teacher_end + student_end confirmed
completed (pending presence)
  ↓ presence submitted
closed (fully complete)

3.7 Frontend Pages

• /admin/lessons — List semua lesson sessions dengan status
• /admin/lessons/:id — Detail session + timeline konfirmasi
• /admin/confirmations — Dashboard monitoring konfirmasi
  • Filter: pending start, pending end, mismatch, resolved
• Guru interface (deferred post-MVP kecuali confirm actions)
• Murid interface (deferred post-MVP kecuali confirm actions)

Deliverable: Admin bisa schedule les. Guru dan murid bisa confirm start/end. Backoffice bisa monitor semua konfirmasi real-time. Mismatch terdeteksi otomatis.

---

Phase 4: Presence & Evidence

Goal: Guru wajib submit presence setelah les selesai. Foto evidence bisa di-upload.

4.1 Presence Service (apps/api/src/services/presence/)

Implement service mixins:

• submit-presence.ts — Guru submit laporan setelah les
• get-presence.ts — Get laporan untuk session
• list-presence.ts — List laporan (guru/admin)

4.2 Presence Schema

presence_reports:
  id, session_id, teacher_id, materials_covered, student_progress_notes,
  homework_assigned, next_session_recommendation, duration_actual_minutes,
  created_at, updated_at

4.3 Presence Form Fields

Field	Type	Required
Materi yang dibahas	text (multi-line)	Ya
Progress murid	text (multi-line)	Ya
PR/tugas yang diberikan	text (multi-line)	Optional
Rekomendasi pertemuan berikutnya	text (multi-line)	Optional
Durasi aktual (menit)	number	Ya

4.4 Evidence Upload Service (apps/api/src/services/evidence/)

Implement service mixins:

• upload-evidence.ts — Upload foto bukti les ke R2
• list-evidence.ts — List foto untuk session
• delete-evidence.ts — Hapus foto (admin/guru yang upload)

4.5 Evidence Schema

session_evidence:
  id, session_id, uploaded_by_user_id, file_url, file_name, file_size,
  description, created_at

4.6 Enforcement Rules

• Presence wajib: Session tidak bisa dianggap "closed" sampai presence disubmit oleh guru.
• Evidence optional tapi recommended: Guru bisa upload foto sebelum/during/after les.
• Admin review: Backoffice bisa melihat semua presence dan evidence.

4.7 Frontend Pages

• Presence submission form (untuk guru — bisa halaman sederhana untuk MVP)
• Evidence upload component dengan preview
• /admin/presence — List semua presence report
• /admin/lessons/:id/presence — View presence untuk session tertentu
• /admin/lessons/:id/evidence — View foto evidence untuk session

Deliverable: Guru bisa submit presence dengan form lengkap. Foto evidence bisa di-upload ke R2. Admin bisa review semua laporan dan evidence. Enforcement status tracking berfungsi.

---

Phase 5: Backoffice Dashboard

Goal: Dashboard komprehensif untuk admin/owner memonitor seluruh operasi.

5.1 Dashboard Overview

Cards/metrics:

• Total orders (pending / paid / verified)
• Total lesson sessions (scheduled / ongoing / completed)
• Pending confirmations (start / end)
• Sessions without presence
• Disputes yang perlu resolve

5.2 User Management

• /admin/users — List semua user dengan filter role
• Invite admin (owner only)
• View user profile
• Deactivate/activate user

5.3 Order Management

• /admin/orders — Full order CRUD
• Upload bukti bayar atas nama murid (untuk kasus WhatsApp)
• Verify/cancel orders

5.4 Lesson Monitoring

• /admin/lessons — Kalender/list view sessions
• /admin/confirmations — Real-time monitoring konfirmasi
• Resolve dispute action untuk mismatch confirmation

5.5 Presence & Evidence Review

• /admin/presence — List semua laporan
• Filter by guru, murid, date range
• View evidence photos

5.6 Owner Features

• Invite admin (/admin/users/invite)
• Owner-only routes dan actions

Deliverable: Admin/owner punya dashboard lengkap untuk memonitor dan mengelola semua aspek platform. Semua action bisa dilakukan dari backoffice.

---

Post-MVP Roadmap

P1: Murid & Guru Interface

• Halaman dashboard murid: lihat order, jadwal les, history
• Halaman dashboard guru: lihat jadwal mengajar, confirm actions, submit presence
• Notifikasi (email/in-app) untuk reminder les

P2: Kalender & Booking

• Murid bisa lihat kalender dan pesan "slot waktu"
• Guru bisa set availability
• Admin bisa manage jadwal via drag-drop kalender

P3: Google Calendar Sync

• Untuk murid: optional sync ke Google Calendar (jika login dengan Gmail)
• Untuk guru: wajib sync ke Google Calendar
• Auto-create event saat lesson session di-schedule

P4: 2FA

• TOTP 2FA untuk semua role
• Enforce untuk admin/owner

P5: Analytics

• Laporan performa guru
• Statistik kehadiran murid
• Revenue tracking

P6: Auto Payment

• Integrasi payment gateway (Xendit/Midtrans)
• Otomatisasi verifikasi pembayaran

---

Success Criteria

• [ ] Auth berfungsi: Google OAuth, Email/Password, Magic Link
• [ ] 4 role system berfungsi: murid, guru, admin, owner
• [ ] Profile page bisa di-update oleh semua user
• [ ] Murid bisa membuat order dan upload bukti bayar
• [ ] Admin bisa verifikasi order dan upload bukti atas nama murid
• [ ] Admin bisa membuat lesson session dari order verified
• [ ] Guru bisa confirm les dimulai dan selesai
• [ ] Murid bisa confirm les dimulai dan selesai
• [ ] Backoffice bisa monitor semua konfirmasi real-time
• [ ] Mismatch detection berfungsi
• [ ] Guru wajib submit presence sebelum session "closed"
• [ ] Foto evidence bisa di-upload ke R2
• [ ] Backoffice dashboard lengkap untuk admin/owner
• [ ] OpenAPI docs generated correctly
• [ ] All docs updated and deployed
• [ ] No sensitive data in code or docs

---

Timeline Summary

Phase	Duration	Deliverable
0. Foundation	Week 1	Working infra, auth, DB, API shell, web shell, docs
1. Auth & Profile	Week 2	Auth lengkap, 4 roles, profile page
2. Order & Payment	Week 3	Order CRUD, bukti bayar upload, verifikasi admin
3. Lesson & Confirmation	Week 4	Lesson sessions, triple confirmation, monitoring
4. Presence & Evidence	Week 5	Presence form, photo evidence, enforcement
5. Backoffice Dashboard	Week 6	Dashboard, user management, dispute resolution

Total: 6 weeks (bisa diparalelkan di mana dependencies memungkinkan)

---

Docs Updates Required

After each phase, update these docs:

Phase	Doc updates
0	technical/architecture.md, technical/database.md, technical/authentication.md, technical/deployment.md
1	technical/user-flow.md (auth flow), technical/authentication.md (roles)
2	technical/user-flow.md (order flow), overview/product.md
3	technical/user-flow.md (confirmation flow), overview/product.md
4	technical/user-flow.md (presence flow), overview/product.md
5	technical/user-flow.md (backoffice flow), overview/product.md

See .agents/rules/docs.md for full docs conventions.

---

Risk Mitigation

Risk	Mitigation
better-auth integration complexity	Test auth flow di local environment sebelum deploy. Backup plan: manual session management.
R2 upload limits	Validate file size client + server. Compress images sebelum upload jika perlu.
D1 transaction limitations	Design schema untuk minimize need complex transactions. Use application-level consistency checks.
Role edge cases	Strict middleware guards. Unit test setiap procedure base.
Confirmation mismatch disputes	Clear audit trail di lesson_confirmations. Admin override dengan logging.
Post-MVP scope creep	Document clearly di apps/docs/plans/mvp-plan.md. Review setiap PR terhadap MVP scope.