StudyFlow adalah platform belajar pribadi untuk mahasiswa yang mengintegrasikan pengelolaan semester, mata kuliah, tugas, catatan, serta materi PDF dengan bantuan AI. Mahasiswa dapat mengunggah dokumen kuliah, merangkum isinya, dan berlatih melalui flashcard serta kuis interaktif yang merujuk langsung ke halaman sumber.
| Milestone | Deskripsi | Status |
|---|---|---|
| Milestone 1 — Foundation | Fondasi monorepo, Next.js, Express, PostgreSQL, Redis, Worker BullMQ, CI, Health/Readiness, Theme Switcher | Selesai |
| Milestone 2 — Authentication & Shell UI | Registrasi, login, JWT/refresh cookie, profil pengguna, rotasi token atomik, Next.js BFF proxy, sidebar responsif | Selesai |
| Milestone 3 — Semester & Course Management | Pengelolaan semester aktif/arsip, multi-tenant composite isolation, daftar & detail mata kuliah, onboarding dashboard | Selesai |
| Milestone 4 — Assignments, Notes & Dashboard | Manajemen tugas kuliah, deadline timezone-aware, editor catatan Markdown, ringkasan dashboard semester aktif | Selesai |
| Milestone 5 — Storage & Document Worker | Upload PDF langsung ke storage privat, antrean BullMQ & transactional outbox, ekstraksi teks per halaman, kuota storage & upload | Selesai |
| Milestone 6 — AI Summaries | Ringkasan materi AI dengan Gemini API free tier, kutipan nomor halaman interaktif, mitigasi prompt injection, kuota harian atomik | Selesai |
| Milestone 7 — Flashcards & Quizzes | Generasi latihan interaktif, penyimpanan jawaban sebelum submit, penilaian & skor di backend, soft-delete turunan saat materi dihapus | Selesai |
| Milestone 8 — MVP Release Prep | Tahap 1: Verifikasi MVP lokal, E2E suite, evaluasi AI, demo seed, deployment guide, dan checklist rilis | Selesai (Tahap 1) |
Repository ini dikelola menggunakan npm workspaces:
study-flow/
├── apps/
│ ├── web/ # Frontend: Next.js 15 (App Router), Tailwind CSS v4, shadcn/ui, Lucide
│ ├── admin/ # Frontend: Next.js 15 Panel Administrator StudyFlow (Port 3002)
│ ├── api/ # Backend: Express REST API, Zod validation, Health/Readiness
│ └── worker/ # Worker: Proses background BullMQ untuk pengolahan dokumen dan AI
├── packages/
│ ├── shared/ # Zod schemas, kontrak data publik, dan konstanta bersama
│ ├── database/ # Prisma schema, migrations, dan singleton PrismaClient untuk server
│ └── config/ # Konfigurasi TypeScript bersama (tsconfig bases)
├── docs/
│ ├── architecture.md # Arsitektur sistem dan batas tanggung jawab
│ └── product_requirements_document.md # PRD resmi proyek
├── .github/workflows/ci.yml # GitHub Actions CI workflow
├── docker-compose.yml # Layanan lokal PostgreSQL 16 & Redis 7
└── package.json # Root workspace scripts dan dependensi
- Node.js: Versi
>= 22.0.0(disarankan Node 22 LTS). - npm: Versi
>= 10.0.0. - Docker & Docker Compose: Untuk menjalankan PostgreSQL dan Redis lokal (opsional bila sudah memiliki instance lokal).
- Sistem Operasi: Kompatibel dengan Windows (PowerShell), macOS, dan Linux.
Salin file template .env.example ke file .env yang sesuai:
# Buat file .env lokal dari template
Copy-Item .env.example .env
Copy-Item apps/api/.env.example apps/api/.env
Copy-Item apps/worker/.env.example apps/worker/.env
Copy-Item apps/web/.env.example apps/web/.env.local
Copy-Item packages/database/.env.example packages/database/.envDATABASE_URL:postgresql://studyflow_user:studyflow_dev_password@localhost:5433/studyflow_dev?schema=publicREDIS_URL:redis://localhost:6379PORT:4000(Port backend API)NEXT_PUBLIC_API_URL:http://localhost:4000(URL API untuk browser)
Jalankan container PostgreSQL dan Redis menggunakan Docker Compose:
docker compose up -dUntuk memeriksa status container:
docker compose psContainer dilengkapi healthcheck otomatis:
- PostgreSQL StudyFlow siap di port
5433(port default 5433 digunakan agar tidak bentrok dengan instalasi PostgreSQL lokal bawaan di port 5432) - Redis siap di port
6379
Untuk menghentikan:
docker compose down-
Pasang seluruh dependensi monorepo:
npm install
-
Generate Prisma Client:
npm run db:generate
-
Jalankan Migrasi Database (Development):
npm run db:migrate:dev
Perintah ini akan menerapkan skema migrasi
UserdanRefreshSessionke basis data PostgreSQL tanpa menghapus atau mereset data yang ada. -
Build shared packages:
npm run build:shared
Perintah ini akan menjalankan frontend Next.js, backend Express, dan BullMQ worker secara serentak:
npm run dev- Frontend Web (port
3000):npm run dev:web
- Admin Dashboard Web (port
3002):npm run dev:admin
- Backend API (port
4000):npm run dev:api
- Worker BullMQ:
npm run dev:worker
Untuk memberikan role ADMIN pada pengguna yang sudah terdaftar:
npm run promote:admin -- [email protected]Atau tanpa konfirmasi interaktif (misalnya untuk automasi):
npm run promote:admin -- [email protected] --yesJalankan quality gates dan rangkaian test yang tersedia:
-
Typecheck: Memeriksa tipe TypeScript di semua workspace:
npm run typecheck
-
Lint: Memeriksa kualitas kode:
npm run lint
-
Unit & Integration Tests (API & Worker):
npm run test -
Pengujian Khusus Backend Auth (Vitest):
npm run test --workspace=@studyflow/apiCatatan: Pengujian otomatis API menggunakan database terpisah
studyflow_testsecara otomatis untuk menjaga integritas data development. -
Pengujian Integrasi End-to-End BFF Auth (Next.js -> Express):
npm run test:bff
Menguji pendaftaran, login, cookie HttpOnly, proteksi rute privat
/dashboarddan/settings, pembaruan profil, perubahan password dengan pencabutan sesi instan, dan logout melalui proxy Next.js. -
Pengujian Browser Playwright End-to-End (E2E):
# 1. Bangun bundle Next.js untuk E2E ke direktori .next-e2e: npm run build:e2e # 2. Verifikasi kepatuhan isolasi konfigurasi E2E: npm run test:e2e:config # 3. Jalankan test E2E Chromium: npm run test:e2e
Menjalankan flow kritis MVP secara hermetis. Catatan Isolasi Ketat: E2E Playwright mewajibkan konfigurasi test eksplisit (
DATABASE_URL_TESTberakhiran_test, danREDIS_URL_TESTmenggunakan database terpisah misalnya DB 15). Fallback keDATABASE_URLatauREDIS_URLdevelopment telah dihapus; jika konfigurasi test tidak tersedia atau menunjuk target tidak aman, setup E2E menolak eksekusi seketika sebelum migrasi, seed, atau server dimulai. URL test yang divalidasi hanya diteruskan ke proses anak API dan Worker, bukan ke frontend Next.js. -
Verifikasi Docker Image Multi-Stage (Clean Build):
docker build -f apps/api/Dockerfile -t studyflow-api:latest . docker build -f apps/worker/Dockerfile -t studyflow-worker:latest . docker build -f apps/web/Dockerfile -t studyflow-web:latest .
-
Evaluasi Performa Ekstraksi & Kualitas AI:
npm run eval:ai
Menjalankan evaluasi dataset representatif berbasis dokumen akademik nyata dan failure fixtures menggunakan runner resmi terpadu (
scripts/run-ai-evaluation.ts) dengan sumber kebenaran data didocs/ai_evaluation/manifest.json.Sistem memisahkan 3 lapisan evaluasi secara akuntabel sesuai PRD Bagian 15.2:
- Lapisan 1 (Validasi Dokumen & Ekstraksi): Ekstraksi teks PDF nyata per halaman via
pdfjs-dist, validasi magic bytes, serta pembuktian penolakan deterministik berkas negatif (PDF scan tanpa teks, berkas rusak, PDF terenkripsi dengan proteksi kata sandi nyata, dan dokumen melebihi batas 100 halaman). - Lapisan 2 (Integrasi & Validitas Struktur Output AI): Validasi keluaran model terhadap skema Zod publik aplikasi (
SummaryStructuredOutputSchema,FlashcardSetStructuredOutputSchema,QuizStructuredOutputSchema), pengecekan batasan referensi halaman (1 <= pageReference <= totalPages), validitas opsi kuis (tepat 4 opsi unik, indeks0..3), dan kejelasan penjelasan. - Lapisan 3 (Kualitas Faktual & Review Manual): Evaluasi kebenaran faktual klaim ringkasan, kartu flashcard, dan kunci jawaban kuis terhadap teks sumber asli. Pada mode Mock, seluruh kriteria Lapisan 3 ditandai strictly
NOT_EVALUATEDdan tidak menggelembungkan metrik kelulusan sistem.
Opsi CLI Runner Resmi:
# Mode mock standar (mengevaluasi seluruh dataset manifest) npm run eval:ai # Membatasi jumlah dokumen valid (misal 5 dokumen) npx tsx scripts/run-ai-evaluation.ts --limit=5 # Hanya menguji berkas kegagalan/negatif npx tsx scripts/run-ai-evaluation.ts --negative-only # Menjalankan pengujian live provider dengan pengawasan kuota ketat npx tsx scripts/run-ai-evaluation.ts --provider=gemini --limit=2 --max-calls=6
Laporan komprehensif disimpan secara otomatis di
docs/ai_evaluation/evaluation_report.mdbeserta log audit JSON didocs/ai_evaluation/results-<timestamp>.json. - Lapisan 1 (Validasi Dokumen & Ekstraksi): Ekstraksi teks PDF nyata per halaman via
-
Demo Data Seeding:
npm run seed:demo
Menyiapkan akun demo (
[email protected]) dengan data perkuliahan realistis secara aman dan idempotent tanpa menghapus atau mengganggu data pengguna lain. -
Build: Membangun seluruh paket dan aplikasi:
npm run build
Sistem autentikasi StudyFlow menggunakan arsitektur single-origin BFF (Backend-for-Frontend):
- Browser berinteraksi dengan rute
/api/auth/*pada origin Next.js (http://localhost:3000). - Token disimpan aman dalam cookie HttpOnly (
studyflow_access_token[15m],studyflow_refresh_token[7d]). - Token refresh disimpan dalam basis data hanya sebagai hash SHA-256 dan dirotasi secara atomik pada setiap request refresh (dengan deteksi replay otomatis).
- Pergantian password menaikkan versi token pengguna (
tokenVersion) sehingga seluruh access token dan sesi lama langsung tidak berlaku di server. - Kontrak lengkap OpenAPI 3.1.0 tersedia di
docs/api.openapi.json.
Smoke test internal disediakan untuk memverifikasi antrean dan konsumsi job BullMQ tanpa memerlukan panggilan model AI:
- Pastikan Redis dan proses worker aktif:
npm run dev:worker
- Pada terminal terpisah, kirimkan smoke job:
Script akan memvalidasi payload, mengirim job ke antrean
npm run worker:smoke
studyflow-smoke-queue, dan menunggu hasil penyelesaian dari worker.
Backend Express menyediakan dua endpoint pemantauan:
GET http://localhost:4000/health: Memastikan proses API hidup dan merespons. Mengembalikan status200 OKdengan metadata uptime dan environment.GET http://localhost:4000/ready: Memeriksa konektivitas nyata ke PostgreSQL dan Redis dengan mekanisme timeout 2 detik. Mengembalikan200 OKbila kedua layanan siap, atau503 Service Unavailablebila dependensi belum siap (tanpa membocorkan kredensial).
- Port 5432 atau 6379 sudah terpakai:
Jika Anda telah memiliki instance PostgreSQL atau Redis lokal yang sedang berjalan di mesin Anda, Anda dapat menggunakannya langsung dengan menyesuaikan
DATABASE_URLdanREDIS_URLdi.env, atau ubah port mapping padadocker-compose.yml. - Prisma Client belum ter-generate:
Jalankan
npm run db:generate. - Paket
@studyflow/sharedtidak ditemukan saat build: Pastikan menjalankannpm run build:sharedsebelum membangun aplikasi web atau worker.
StudyFlow menggunakan Supabase Storage dengan bucket privat untuk menyimpan materi perkuliahan dalam format PDF berbasis teks.
- Inisiasi (
POST /api/materials/initiate-upload):- Browser meminta URL upload terotorisasi melalui BFF -> Express API.
- Server memverifikasi kepemilikan mata kuliah, kuota storage pengguna (maks 200 MB), kuota upload harian (maks 10 file/hari, reset 00:00 UTC), dan status arsip.
- Server mereservasi kuota, membuat entri
MaterialberstatusUPLOADING, dan menerbitkan signed upload URL dari Supabase Storage.
- Transfer Langsung ke Storage:
- Browser mengunggah payload file PDF langsung ke Supabase Storage via signed URL tanpa membebani throughput memory BFF Next.js.
- Finalisasi (
POST /api/materials/finalize-upload):- Browser memberi tahu server bahwa upload selesai.
- Server memverifikasi keberadaan file di storage, mengunci status menjadi
QUEUED, membuatProcessingJob, dan mencatatOutboxEvent. - Dispatcher outbox meneruskan pekerjaan ke antrean BullMQ (
studyflow-document-processing).
- Ekstraksi Teks oleh Worker (
apps/worker):- Worker mengambil pekerjaan, memverifikasi integritas PDF (magic bytes
%PDF-), batas maksimal 100 halaman, dan batas maksimal 20 MB. - Teks diekstrak per halaman (1-indexed) menggunakan
pdfjs-distdengan mempertahankan provenance nomor halaman untuk fitur AI mendatang. - Dokumen tanpa lapisan teks (scanned image) ditolak dengan kode
SCANNED_PDF_NO_TEXT(OCR tidak didukung pada versi ini). - Setelah seluruh halaman tersimpan di database, status diubah menjadi
READYdan kuota storage dikomit secara atomik.
- Worker mengambil pekerjaan, memverifikasi integritas PDF (magic bytes
StudyFlow mendukung 4 driver storage yang dapat dipilih secara eksplisit melalui environment variable STORAGE_DRIVER:
| Driver | Deskripsi | Lingkungan Penggunaan |
|---|---|---|
local (Default Dev) |
Menyimpan file pada filesystem lokal (.storage/materials/). Mendukung transfer berkas lintas proses antara Express API dan Worker background tanpa akun pihak ketiga. |
Local Development |
supabase |
Menggunakan Supabase Storage dengan bucket privat melalui @supabase/storage-js. Memerlukan SUPABASE_URL dan SUPABASE_SERVICE_ROLE_KEY. |
Production / Staging |
memory |
In-memory Mock Storage untuk pengujian otomatis terisolasi yang cepat. | Unit & Integration Test (vitest) |
none |
Menonaktifkan storage dengan aman. Endpoint upload/download mengembalikan 503 STORAGE_UNAVAILABLE tanpa mengganggu fitur perkuliahan, tugas, dan catatan. |
Maintenance / Storage Off |
Catatan Keamanan Produksi: Pada lingkungan
production, sistem tidak akan pernah secara diam-diam beralih ke mock in-memory jika kredensial Supabase hilang. Sistem akan mengembalikan statusSTORAGE_UNAVAILABLEyang aman bagi pengguna.
Bila ingin menghubungkan ke instance Supabase nyata:
- Masuk ke dashboard Supabase dan buka proyek Anda.
- Buka menu Storage -> pilih New Bucket:
- Bucket Name:
studyflow-materials(wajib persis sesuai nilaiSUPABASE_STORAGE_BUCKET). - Public bucket: Disabled / Off (Wajib Privat). Jangan pernah mengaktifkan public bucket untuk dokumen pengguna.
- Allowed MIME types:
application/pdf. - Maximum file size limit: 20 MB (20,971,520 bytes).
- Bucket Name:
- Masuk ke menu Project Settings -> API:
- Salin Project URL ke
SUPABASE_URL. - Salin service_role secret key (bukan
anonpublic key!) keSUPABASE_SERVICE_ROLE_KEY.
- Salin Project URL ke
- Tambahkan konfigurasi ke file environment:
- Backend API:
apps/api/.env - Worker Background:
apps/worker/.env
STORAGE_DRIVER="supabase" SUPABASE_URL="https://your-project.supabase.co" SUPABASE_SERVICE_ROLE_KEY="your-service-role-secret-key" SUPABASE_STORAGE_BUCKET="studyflow-materials"
- Backend API:
- Restart Proses:
Restart kedua proses server agar membaca variabel lingkungan baru:
- Restart API: Hentikan dan jalankan kembali
npm run dev:api. - Restart Worker: Hentikan dan jalankan kembali
npm run dev:worker.
- Restart API: Hentikan dan jalankan kembali
Peringatan Keamanan: Kredensial service_role memiliki hak akses administratif penuh. Jangan pernah memberi prefix NEXT_PUBLIC_, mengunggahnya ke Git, mencetak nilainya dalam log, atau membagikannya ke browser!
StudyFlow mengintegrasikan model Large Language Model (LLM) untuk menghasilkan ringkasan akademis terstruktur secara otomatis dari materi PDF yang telah diekstrak. Fitur ini dirancang khusus menggunakan free tier tanpa billing.
- Provider: Google AI Studio Gemini API (
gemini-3.5-flash-lite— model aktif proyek ini; pertahankan konfigurasi & secret yang bekerja). - Free Tier: Pengguna wajib memastikan bahwa project Google AI Studio miliknya berada pada Free Tier tanpa mengaktifkan billing / pay-as-you-go. Jangan menambahkan kartu kredit atau mengaktifkan penagihan pada Google Cloud Console. Batas kuota gratis (seperti rate limit per menit dan kuota harian) sepenuhnya diatur oleh kebijakan resmi Google AI Studio untuk wilayah dan akun terkait.
- Tanpa Fallback Berbayar: Sistem StudyFlow dirancang tanpa mekanisme fallback otomatis ke model atau provider berbayar. Jika kuota provider habis (
429), sistem menampilkan pesan error informatif yang aman dan tidak melakukan retry tanpa henti. - Kebijakan Penggunaan Data: Pada Google AI Studio free tier, prompt dan konten teks dapat ditinjau oleh Google sesuai kebijakan privasi AI Studio. Oleh karena itu, pengujian disarankan menggunakan sampel materi edukasi non-sensitif.
- Model Adapter:
gemini: Provider riil menggunakan Google AI Studio API. Wajib menyertakanGEMINI_API_KEY. Jika API key belum dikonfigurasi, sistem mengembalikan status503 AI_PROVIDER_UNCONFIGUREDsecara aman dan tidak beralih ke mock.mock: Mock adapter deterministik berbahasa Indonesia yang hanya aktif jika dipilih secara eksplisit (AI_PROVIDER="mock") untuk pengujian otomatis hermetis.none: Mode penonaktifan eksplisit yang mengembalikan status503 AI_PROVIDER_UNAVAILABLEtanpa mengganggu fitur perkuliahan lainnya.
- Dukungan Dokumen Panjang & Chunking: Dokumen dibagi ke dalam chunk terstruktur (maksimal 40.000 karakter per bagian, batas maksimal 3 chunk + 1 sintesis penggabungan). Dokumen yang melebihi 100 halaman atau 300.000 karakter ditolak di awal (
DOCUMENT_TOO_LARGE) sebelum memanggil provider AI untuk mencegah ringkasan parsial yang menyesatkan.
- Batas Harian Pengguna: Maksimal 20 ringkasan per pengguna per hari, direset otomatis pada pukul 00:00 UTC.
- Batas Konkurensi: Maksimal 2 proses generasi AI aktif bersamaan per pengguna.
- Reservasi Atomik: Kuota harian dan slot konkurensi direservasi secara atomik di PostgreSQL dalam transaksi sebelum pekerjaan didispatch.
- Idempotensi: Klik ganda atau pengiriman ulang saat pekerjaan berstatus
QUEUEDatauPROCESSINGtidak akan menduplikasi pekerjaan maupun menghabiskan kuota ganda.
- Pertahanan Prompt Injection: Seluruh teks halaman PDF diperlakukan sebagai masukan tidak tepercaya (untrusted input). Sistem prompt memerintahkan model untuk mengabaikan instruksi apa pun yang tertanam di dalam isi dokumen.
- Validasi Terstruktur Zod: Keluaran model divalidasi ketat menggunakan schema JSON (
title,overview,keyConcepts,sections,keyTerms). Seluruh kutipan nomor halaman dibatasi pada rentang valid1..totalPages. - Preservasi Regenerasi: Jika pengguna meminta regenerasi dan pemanggilan AI gagal (misal timeout atau rate limit), ringkasan sukses sebelumnya tetap dipertahankan utuh sehingga pengguna tidak kehilangan materi belajar.
- Asinkron Melalui BullMQ: Pemrosesan LLM berjalan di antrean background worker
studyflow-ai-generationdengan timeout 45 detik viaAbortSignal.timeoutdan retry terbatas hanya untuk transient error.
- Dapatkan API Key gratis di Google AI Studio (pastikan akun gratis tanpa billing diaktifkan).
- Tambahkan konfigurasi ke file
apps/api/.envdanapps/worker/.env:AI_PROVIDER="gemini" GEMINI_API_KEY="AIzaSy..." GEMINI_MODEL="gemini-3.5-flash-lite"
- Restart proses backend API dan Worker background:
npm run dev:apinpm run dev:worker
- Buka halaman detail materi
/materials/[id]pada browser:- Pilih tab "Ringkasan AI".
- Klik "Buat Ringkasan AI Sekarang".
- Klik nomor halaman referensi (misal
[Hal 2]) pada konsep atau bagian untuk langsung berpindah ke tampilan PDF pada halaman tersebut!