# CLAUDE.md — DrawIt

Guidance for Claude (and humans) working in this repo.

## What DrawIt is

A free, open-source, **privacy-first** web app that teaches kids to draw — mobile/iPad-first.
**Non-negotiable principle: no data collection.** No analytics, no trackers, no third-party calls.
All data stays in the operator's self-hosted SQLite. Any feature must preserve this.

## Stack

Next.js 15 (App Router) + TypeScript · `better-sqlite3` (WAL) · custom cookie-session auth (scrypt) ·
`nodemailer` SMTP · `pdf-lib` (award certificates) · hand-written mobile-first CSS (no UI framework).
Path alias `@/*` → `./src/*` (needs `baseUrl` in tsconfig for the Windows/Next build).

## How the curriculum works (read before touching lessons)

- **Levels:** Early Beginner → Beginner → Learner → Advanced Learner → Superb (`LEVELS` in
  `src/lib/curriculum.ts`).
- **Subjects & phases:** each subject is a set of `Lesson` entries, one per phase.
  - Early Beginner = 3 phases: **Outline → Details → Color it!** (per-subject badge on Details).
  - Beginner = 4 phases: **Construct → Outline → Color → Light** (per-**pack** badge).
- **Runners:** trace phases use per-step `lines: string[]` (SVG elements) revealed one at a time by
  `LineDraw` inside `TraceRunner`; color/light phases use `baseSvg` rasterized by `ColoringRunner`.
- **Curriculum files:** static lessons live in `src/lib/curriculum.ts` and the generated
  `curriculum.beginner.ts`, `curriculum.eb2.ts`, `curriculum.animals.ts`. Art is produced by Python
  generators in the scratch outputs dir (cairosvg-rendered montages verify it before wiring).
- **Grouping/gating:** `getGroupedSubjects` + `EARLY_BEGINNER_GROUPS` (EB themed groups);
  `src/lib/gating.ts` (Beginner unlocks after 5 EB lessons; pack completion). Per-subject vs per-pack
  badges via `badgeDefs()`.

## Build / verify

`npm run build` and `npm run typecheck` are the source of truth — **run them locally**. Note: the
Cowork sandbox cannot reliably run them (typescript is a devDep often absent; native `better-sqlite3`
won't compile; shell file reads of the mount can truncate). Verify edits via the file tools and the
cairosvg art montages; do a real build on a normal machine before shipping.

## Design & research docs (`docs/`)

Read the relevant doc before building a feature it covers:

- `docs/RESEARCH-drawing-platforms-and-techniques.md` — competitor scan + drawing pedagogy; maps
  techniques to the five levels.
- `docs/RESEARCH-beginner-level.md` — the Beginner level spec (4 phases, 3 packs, unlock gate,
  per-pack badges). **Built.**
- `docs/RESEARCH-early-beginner-expansion.md` — the Early Beginner expansion (Simple Shapes, Fun
  Things, Clothes, Faces, ~19 animals; themed groups). **Built.**
- **`docs/DESIGN-create-ai-lessons.md` — the "Create" feature + Creator role: type a subject →
  ComfyUI generates coloring-book line art → DrawIt turns it into a lesson. Covers the Creator role,
  ComfyUI API integration, the image→level pipeline, mandatory kids-safety/moderation, data model,
  API routes, and phased rollout. Design only (not built). Read this before implementing Create.**

Operational/setup docs also live in `docs/` (BUILDING, DOCKER, SYSTEMD, REVERSE_PROXIES, AUTO_STARTING).

## Conventions

- Preserve the privacy principle in every change.
- First registered account is forced `admin` + active; everyone else defaults `learner` + `pending`
  until email confirmation. Roles: `admin | learner | creator` (creator = learner + the Create ability).
- Adding a lesson subject = append `Lesson` entries (+ art); routes/runners are generic and handle the
  rest. Keep sublevels unique within a level (`subjectIndex*10 + phase` for static lessons).
- Images (drawings, avatars, created line art) are stored as data URLs in SQLite for privacy.