# MathQuest K-8 K-8 math practice app with adaptive-feeling quiz practice, saved progress, parent-assigned tests, report cards, and ten learning suggestions. ## Masterplan - Help K-8 students practice math one question at a time with immediate correctness feedback and coaching for mistakes. - Give families a clear “progress number” plus a stock-style trend chart so growth is easy to understand. - Let parents assign tests anytime by choosing topic, grade band, difficulty, due date, and question count. - Provide separate report-card views for daily practice progress and parent-assigned tests. - Keep the app usable as a generated demo: sample data appears first, then persisted family work loads from GenMB KV. ## Tech Stack & Architecture - **Frontend:** React + TypeScript, Vite, React Router `HashRouter`, Zustand-style app store in `src/store/useMathStore.ts`. - **Styling:** Tailwind CSS v4 through `@tailwindcss/vite`; global design tokens and utility classes live in `src/styles/main.css`. - **Icons:** `lucide-react`. - **Persistence:** GenMB built-in KV SDK injected in `index.html` as `window.genmb.kv`; typed wrapper in `src/lib/kv.ts`. - **Routing:** `src/App.tsx` defines nested routes under `src/components/Layout.tsx`: - `/` → `src/pages/Dashboard.tsx` - `/progress` → `src/pages/Progress.tsx` - `/parent` → `src/pages/Parent.tsx` - `/reports` → `src/pages/Reports.tsx` - `/suggestions` → `src/pages/Suggestions.tsx` - `*` → `src/pages/NotFound.tsx` - **Providers:** `src/main.tsx` wraps `` in `src/mainProviders.tsx`, currently only `ToastProvider`. - **State pattern:** Pages read/write shared student data through `useMathStore`. UI-local state stays in pages for selected answer, form fields, loading flags, dialogs, etc. - **SEO:** Each page should call `useSeo(title, description)` from `src/hooks/useSeo.ts`. Non-obvious gotchas: - The app uses **hash routing**, so nav targets are regular route paths but URLs resolve as `#/progress`, etc. - `Layout` calls `loadAll()` on mount. Demo/sample data is shown until persisted KV values replace it. - Theme is not in the global store; dark mode is stored separately in `localStorage` under `mathquest-theme`. - `ProgressChart` expects attempts sorted by timestamp internally and displays only the latest 8 attempts. - KV is browser-global. Any code calling `kv` assumes `window.genmb.kv` exists from `index.html`. ## File Structure ```text index.html App shell, metadata, root div, injected GenMB KV SDK. vite.config.ts Vite config with React and Tailwind plugins. package.json App dependencies/scripts. src/main.tsx React entrypoint; imports global CSS and providers. src/mainProviders.tsx App-level providers; currently ToastProvider only. src/App.tsx HashRouter route table. src/styles/main.css Tailwind import, CSS variables, light/dark theme tokens, safe-area helpers. src/types/index.ts Shared domain types: student profile, question, attempts, assignments, etc. src/store/useMathStore.ts Central persisted math state and actions. src/lib/kv.ts Typed wrapper around window.genmb.kv. src/lib/sampleData.ts Demo profile, questions, attempts, assignments, and 10 suggestions. src/lib/utils.ts cn(), formatDate(), percent(). src/hooks/useSeo.ts Per-page document title/meta description helper. src/components/Layout.tsx Header, desktop nav, mobile bottom nav, footer, theme toggle, store load. src/components/BottomNav.tsx Fixed mobile 5-item navigation. src/components/ProgressChart.tsx SVG stock-style accuracy trend chart. src/components/ui/Button.tsx Shared button variants with loading state. src/components/ui/Card.tsx Shared card with interactive/selected states. src/components/ui/Dialog.tsx Accessible modal with focus trap and Escape close. src/components/ui/EmptyState.tsx Reusable empty-state panel. src/components/ui/Input.tsx Labeled input with error text. src/components/ui/Skeleton.tsx Loading placeholder. src/components/ui/Toast.tsx Toast context/provider and useToast hook. src/pages/Dashboard.tsx Learn/practice home, quick stats, current question, assignment shortcut. src/pages/Progress.tsx Numeric progress, weekly goal/streak, chart, topic/skill progress. src/pages/Parent.tsx Parent assignment form and assigned/completed tests. src/pages/Reports.tsx Practice and test report cards. src/pages/Suggestions.tsx Ten learning suggestions linking into app sections. src/pages/NotFound.tsx Unknown-route fallback. ``` ## Key Features ### Practice dashboard Implemented in `src/pages/Dashboard.tsx`. Requirements: - Show hero intro for K-8 math practice. - Show student stats from `useMathStore`: name, XP, streak, weekly goal, attempts, assignments. - Cycle through fixed question bank from `src/lib/sampleData.ts` (`questions`). - Student selects one multiple-choice answer. - On answer: - Call `recordPractice(...)`. - Save a `PracticeAttempt`. - Show success toast for correct answers. - Show coaching toast for mistakes. - Keep selection visible until “next question”. - Show latest mistake coaching so the app “teaches what you messed up.” - Support open parent assignment shortcut via `completeAssignment(...)`, which creates a simulated score from recent attempts. Question model from `src/types/index.ts`/`sampleData.ts`: ```ts MathQuestion { id; gradeBand: 'K-2' | '3-5' | '6-8'; topic; difficulty: 'gentle' | 'steady' | 'challenge'; skill; prompt; choices: string[]; answer; coaching; } ``` ### Progress section Implemented in `src/pages/Progress.tsx` and `src/components/ProgressChart.tsx`. Requirements: - Display numeric mastery/accuracy progress as the “number thing.” - Display stock-style progress line using recent attempts. - Track weekly goal, XP, streak, correct/incorrect count, topic mix, and skills needing review. - Chart computes cumulative accuracy across the latest 8 chronological attempts. - Empty/loading states should not crash if no attempts exist; chart shows latest `0%`. ### Parent-assigned tests Implemented in `src/pages/Parent.tsx`. Requirements: - Parent can assign a test whenever they want. - Parent chooses: - title - topic - grade band - difficulty - due date - question count - Assignment is persisted through `useMathStore.addAssignment`. - Assignments have status: - `assigned` - `completed` - Completed assignments include `score` and `completedAt`. - Dashboard can complete the first open assignment as a “quick check.” Assignment model: ```ts TestAssignment { id; title; topic; difficulty; gradeBand; dueDate; // yyyy-mm-dd questionCount; status: 'assigned' | 'completed'; score?: number; createdAt; completedAt?: number; } ``` ### Report cards Implemented in `src/pages/Reports.tsx`. Requirements: - Show practice report card based on `PracticeAttempt[]`. - Show test report card based on completed `TestAssignment[]`. - Families should be able to compare everyday practice performance vs parent-assigned test performance. - Include topic/skill breakdowns where possible. - Use saved data from `useMathStore`, with sample data as initial/demo fallback. Practice attempt model: ```ts PracticeAttempt { id; topic; skill; question; answerGiven; correctAnswer; correct; difficulty; gradeBand; coaching; createdAt; } ``` ### Suggestions Implemented in `src/pages/Suggestions.tsx`; source content in `src/lib/sampleData.ts`. Requirements: - Show exactly 10 learning suggestions. - Each suggestion has an id, title, explanatory text, and target route. - Suggestions are practical app actions, not generic tips: practice missed skills, use progress number, view chart, assign tests, compare reports, etc. ### Persistence and external integration There is no custom backend. The only external API surface is GenMB KV through `src/lib/kv.ts`: ```ts kv.get(key): Promise kv.set(key, value): Promise kv.delete(key): Promise<{ deleted: boolean }> kv.list(prefix): Promise<{ data: { key; value }[]; total: number }> kv.increment(key, by?): Promise ``` `useMathStore.ts` owns which keys are read/written. When adding persisted state, add the type in `src/types/index.ts`, the default/sample value in `src/lib/sampleData.ts` if needed, and load/save actions in `useMathStore.ts`. ## Design Guidelines - Visual style: friendly educational dashboard; rounded cards, soft shadows, bright accent colors, clear badges. - The logo is a π symbol in a primary-colored rounded square in `Layout`. - Colors are driven by CSS variables in `src/styles/main.css` and referenced through Tailwind tokens: - `bg-background`, `text-foreground` - `bg-card`, `text-card-foreground` - `bg-primary`, `text-primary` - `bg-accent`, `text-accent-foreground` - `text-muted-foreground` - `text-destructive`, `text-success`, `text-info` - Dark mode is implemented by toggling `.dark` on `document.documentElement`. - Typography uses Tailwind defaults with bold, tight headings (`tracking-tight`) and readable card text. - Responsive behavior: - Desktop/tablet uses header nav in `Layout`. - Mobile hides header nav and uses fixed `BottomNav`. - `main-safe` and `pb-safe` account for mobile safe-area/bottom nav spacing. - Cards and hero sections use responsive grid classes like `lg:grid-cols-*`. ## App Flow ### Student practice flow 1. User opens `/`. 2. `Layout` loads persisted KV data via `useMathStore.loadAll()`. 3. Dashboard shows sample or saved profile and current question. 4. Student selects an answer. 5. App saves attempt and updates XP/streak/progress. 6. Toast gives either success or mistake coaching. 7. Student clicks next question to continue. Edge cases: - If saving fails, Dashboard shows an error toast and clears the selected answer. - If there are no attempts, accuracy/progress defaults to `0` instead of dividing by zero. - Questions are local sample questions and repeat by modulo index. ### Parent assignment flow 1. Parent opens `/parent`. 2. Parent fills assignment fields. 3. Form validates required/valid values in the page. 4. `addAssignment` persists the assignment. 5. Assigned tests appear in parent area and first open assignment appears on Dashboard. 6. Student completes quick check from Dashboard. 7. `completeAssignment(id, score)` marks assignment completed for report cards. Edge cases: - Due dates are stored as date strings, formatted with `formatDate`. - Completing an assignment requires a matching id; UI should handle no open assignment. ### Progress/report flow 1. User opens `/progress` for current mastery number and stock-style chart. 2. User opens `/reports` for practice and test report cards. 3. Both pages derive their metrics from shared attempts/assignments in `useMathStore`. ### Navigation flow - All pages live under `Layout`, so header, footer, theme toggle, and mobile nav persist. - Unknown routes render `NotFound`. - Links should use React Router `Link`, not raw ``, for internal navigation. ## Conventions - **Components:** Use PascalCase filenames/components (`ProgressChart.tsx`, `Button.tsx`). - **Pages:** Add routeable views under `src/pages`. - **Shared UI:** Put reusable primitives in `src/components/ui`. - **Domain state:** Keep student/profile/attempt/assignment mutations in `src/store/useMathStore.ts`; do not write KV directly from pages unless there is a strong reason. - **Types:** Add or update shared domain interfaces in `src/types/index.ts`. - **Styling:** Prefer Tailwind utility classes and existing design tokens. Use `cn()` from `src/lib/utils.ts` for conditional classes. - **Toasts:** Use `useToast()` for user-visible save/load feedback. Loading toasts must be updated/dismissed; non-loading toasts auto-dismiss. - **Dates:** Use `formatDate()` for display. For assignment due dates, keep storage as `yyyy-mm-dd`. - **Buttons/inputs/cards:** Use existing UI components for consistent focus rings, disabled states, and dark-mode styling. - **Accessibility:** Preserve labels on inputs, `aria-label` on icon buttons, focus-trap behavior in `Dialog`, and semantic page headings. To add a new page: 1. Create `src/pages/NewPage.tsx`. 2. Call `useSeo(...)` inside the page. 3. Add route in `src/App.tsx`. 4. Add nav item in `src/components/Layout.tsx` only if it belongs in the main five-section navigation. 5. Use store selectors from `useMathStore` instead of passing large state through props. To add a new persisted feature: 1. Define types in `src/types/index.ts`. 2. Add default/demo data in `src/lib/sampleData.ts` if the UI needs non-empty first-run content. 3. Extend `src/store/useMathStore.ts` with state, `loadAll()` hydration, and action methods. 4. Persist through `src/lib/kv.ts`. 5. Surface save failures through `ToastProvider` rather than silent console errors. ## Platform (GenMB) This app is built and hosted on GenMB. **Runtime:** Browser sandbox (iframe) or Cloud Run. No Node.js server — all code runs client-side unless `backend/` exists. **Dependencies:** CDN-only (esm.sh, cdn.tailwindcss.com, unpkg). Use ES module imports with full CDN URLs. No `npm install` at runtime. **Entry point:** `index.html` must include all CDN script tags. Tailwind via CDN with inline config. **Built-in services (relative API paths only, never hardcode domains):** - `/api/ai/completion` — AI proxy | `/api/data/{appId}/*` — PostgreSQL (DataConnect SDK) - `/api/storage/{appId}/*` — File uploads (GCS) | `/api/auth/google/*` — Google OAuth - `/api/contact/submit` — Contact form | SDKs: `window.genmb.db`, `.storage`, `.auth` **File structure:** `index.html` (entry), `src/` (source), `styles/` (CSS), `backend/` (optional FastAPI), `CLAUDE.md` (this file). **Cannot:** Install npm packages at runtime, access filesystem, make direct server-side calls from frontend, modify infra.