drawit/CLAUDE.md

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.