# Study Planner — build brief

This file is the specification for turning a clickable prototype into a real app. AI coding agents read AGENTS.md automatically; humans should read it too.

- Prototype file: `prototype.html` in this folder (the clickable reference — keep its look, copy and behaviour).
- Prototype page: https://ideaxapp.com/app/study-planner-fi61h
- Target: Phone (390×844)
- Original idea: "A study planner for exams: I add my subjects with exam dates and topics, tick topics off, and it builds me a weekly revision plan that prioritises the soonest exam and never gives me more hours than I set."

## Summary
UPDATED: Study Planner turns a list of subjects and exam dates into a day-by-day revision plan. Students see how many topics are left per subject, tick off completed topics, and get an automatically balanced weekly schedule that prioritises the soonest exams.

## Who it is for
Secondary school and university students revising for several exams at once, used daily in the weeks before exams.

## Features (v1)
- Users can add subjects with an exam date and a list of topics
- Users can tick topics off and see remaining counts per subject
- Users can view an auto-generated weekly plan that prioritises the soonest exam
- Users can set available study hours per day
- Users can start a focus timer for a topic and log the session
- Users can see progress bars per subject and overall
- Users can reschedule a missed day with one tap

## Screens
- **Subjects** — List of subjects with exam dates and topics left
- **Subject detail** — Topic checklist and progress for one subject
- **Weekly plan** — Generated day-by-day schedule with drag-free move buttons
- **Focus timer** — Pomodoro timer bound to a topic
- **Settings** — Hours per day, rest days, notifications

## Data model
- **Subject**: id: uuid, name: string, examDate: date, colour: string
- **Topic**: id: uuid, subjectId: Subject id, title: string, done: boolean, estimatedMinutes: number
- **Session**: id: uuid, topicId: Topic id, startedAt: datetime, minutes: number

## Rules and behaviour
- Topics are scheduled soonest-exam-first, then by estimated minutes
- A day never exceeds the available hours set in Settings
- Ticking a topic removes it from future days and re-balances the plan
- Past exams move their subject to an archived section
- Empty state: no subjects → show a friendly prompt to add the first exam

## Stack
Expo (React Native) with TypeScript, expo-router, and SQLite via expo-sqlite for offline storage
A phone app used daily works best offline-first; Expo ships to iOS and Android from one codebase and matches the prototype's tab-bar layout.
Alternatives: Flutter with Drift; Responsive PWA with Vite + React and IndexedDB

## Milestones
1. Reproduce the prototype screens with real components and mock data
2. Add SQLite persistence for subjects, topics and sessions
3. Implement the scheduling algorithm with unit tests
4. Focus timer with background-safe timing
5. Notifications and settings
6. Polish, accessibility pass and app store builds

## Working agreements
- `prototype.html` is a single self-contained file with fake in-memory data. Use it as the reference for layout and interactions; do not ship its inline scripts as-is.
- Before coding, write a short numbered plan. Build milestone 1 first and stop for review.
- Keep a README with run and test instructions up to date. Add basic tests as you go.
- Accessibility floor: 16px+ text, 4.5:1 contrast, 44px touch targets, keyboard support.
- Ask only when something is genuinely ambiguous; otherwise make a sensible choice and note it in the README.

## Optional tool integrations (MCP)
If your agent supports MCP servers, these are the relevant ones (September 2026):
- Figma: official Figma MCP server (mcp.figma.com/mcp) — design context, code generation, write-to-canvas (beta).
- Webflow / Framer / Canva: vendor MCP servers or agent connectors for marketing pages and visuals.
- Images: Nano Banana 2 or GPT Image via API for placeholder-free assets.
Prefer the browser build first; add engines and design tools only when the brief calls for them.

## Kickoff prompt
This folder contains prototype.html (a clickable reference prototype) and BUILD-BRIEF.md (the spec). Read both carefully. First create CLAUDE.md capturing the conventions: Expo + TypeScript, expo-router, expo-sqlite, functional components, tests with Jest. Then write a short plan and build milestone 1: reproduce every screen in the prototype with real components and mock data, preserving its look, copy and behaviour. Add a README with run instructions and basic tests. Ask questions only if something is genuinely ambiguous.

---
Prototype and brief released under CC0 via ideaxapp.com. Brief generated with Google Gemini (gemini-3.5-flash-lite); review before relying on it.