KilasTugas Specification
1. Problem & Value Proposition
- Problem: Students experience Task Paralysis/Overwhelm Freeze when receiving a thick syllabus/assignment (5–15 pages) with a long deadline, resulting in an all-nighter (D-1/D-0) cramming system.
- Core Value: "Don't ask 'when will it be finished,' ask 'what did you do today?'"
- Solution: Break down long assignment instructions into a chain of 3–8 measurable sub-tasks (25–90 minutes) distributed toward the deadline, equipped with a Pomodoro timer, calendar, and blueprint sharing.
2. System Architecture
Text
3. Tech Stack Breakdown
Frontend
- Framework: React 18 + Vite 5
- Styling: Tailwind CSS 3.4
- State & Storage: LocalStorage + IndexedDB (flashtask_offline_db)
- PWA & Offline: Service Worker, Web Push Manager, Background Sync Batch
- Timer Engine: Persistent Timestamp-based Pomodoro (Date.now() drift-free) + Web Audio API + Notifications API
- Export Formats: Google Calendar Web Intent + RFC 5545 iCalendar (.ics)
Backend
- Runtime & Web Framework: Python + FastAPI (Asynchronous ASGI)
- Validation: Pydantic v2
- Database Engine: MariaDB 10.x via aiomysql connection pool
- Parser Files: pypdf & python-docx (In-memory parser, no save to VPS disk)
- Deployment: Nginx reverse proxy to Uvicorn daemon (Systemd)
4. Core Features & Capabilities
- Tri-Engine Decomposition:
- Smart Cache (<20ms): Check similarity of similar tasks in DB; avoid AI token re-inference.
- AI Inference (<2s): Extract instructions and generate action steps via the 9Router gateway.
- Fallback Templates: 5 built-in academic templates (Lab Report, Paper, Coding, Presentation, Journal Review) when offline/limited.
- In-Memory Document Parser (/api/extract-syllabus): Upload PDF/DOCX assignment syllabi, extracted to RAM without a file trace on the server.
- Dynamic Micro-Pacing & Rebalancer (/api/tasks/{id}/rebalance): Calculate status: On Track, Behind Schedule, Overdue. Adaptively redistribute remaining subtasks if students fall behind deadlines.
- Offline-First PWA Sync (/api/tasks/sync-batch): Continue working offline with IndexedDB, automatic batch sync when online.
- Persistent Focus Engine (Pomodoro):
- Floating pill timer between pages, 25/5 minute cycle, title sync, chime sound.
- Social Task Blueprint (/p/:id):
- Public link to assignments for classmates to import in one click without logging in.
5. API Endpoints Reference
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/breakdown | Execute AI/Cache/Fallback task breakdown |
| POST | /api/extract-syllabus | Parse PDF/DOCX assignment files in-memory |
| POST | /api/tasks | Save tasks & subtasks to MariaDB |
| GET | /api/tasks/{task_id} | Get task and subtask details |
| PATCH | /api/tasks/{task_id}/subtasks/{subtask_id} | Update subtask check status |
| POST | /api/tasks/{task_id}/rebalance | Recalculate pacing if behind schedule |
| POST | /api/tasks/sync-batch | IndexedDB offline batch sync |
| GET | /api/public/{share_slug} | Get public task blueprint template |
