Overview & Architecture

Version: v1.7 | Last Updated: 2026-04-18

1. Scope

This wiki defines the complete Pickatale learning platform — every service, data model, API contract, compliance rule, and build gate. It is the single source of truth for Claude Code agents.

Rule: If it is not in this wiki, it does not exist. Do not infer, assume, or default.

2. Product Overview

Source: (D) Sig Dug | Status: Confirmed

Pickatale is a children's reading platform (ages 4–11) built on an invisible adaptive learning loop:

1. Curriculum Mapper (CM) defines what a child should learn per territory/year
2. Reader App delivers books the child wants to read
3. Telemetry captures behavioral signals (page times, word taps, quiz scores)
4. Learner Bot detects gaps, generates reports, recommends next content
5. Adaptive Content Engine re-levels any story to a child's exact FK grade
6. Teacher Portal shows curriculum progress, flags struggling readers
7. Parent Portal delivers warm digests: "Sofia had a great reading day!"

The child just reads stories they love. The platform handles the rest invisibly.

Platform Pillars

Key URLs

3. System Architecture Map

Source: Code audit 2026-04-18 | Status: Confirmed

┌─────────────────────────────────────────────────────┐
│                    CADDY (HTTPS)                    │
│           reverse proxy for all services            │
└──────────────────────┬──────────────────────────────┘
                       │
        ┌──────────────┼──────────────────┐
        │              │                  │
   [Reader App]  [Teacher Portal]  [Account Center]
   port 3125      port 3116           port 3126
   React+tRPC     Next.js+Express      Node+Express
        │              │                  │
        │         [Parent Portal]    [Subscriptions]
        │          port 3118          Stripe Webhooks
        │
   [Telemetry]──────→[Learner Bot]──────→[Teacher Portal]
   port 3110           port 3120           (enrichment)
        │                  │
        ↓                  ↓
      [LRS]        [Adaptive Engine]
   port 3111         port 3119
                    (FK leveling)
                         │
                  [Content Service]
                   port 3112

All services share: MySQL 8 (shared Docker instance, internal access only)
All services read identity: Account Center session API
All child identity: UUID learner_id from Teacher Portal students table

Inter-Service Communication Rule (Non-Negotiable)

• ✅ Services communicate via REST API with X-Internal-Key header
• ❌ Services NEVER connect to each other's database directly
• Build the endpoint in Service B first, then wire Service A to call it

4. State Definitions

Source: Code audit | Status: Confirmed

User States (users.state)

Student States (students.state)

Subscription States

Reading Session States

5. Build Order

Source: (D) Sig Dug | Status: Confirmed

Phase 1 — Identity & Auth (Account Center)

1. users table + registration + email verification
2. Login + session (uc_session cookie)
3. Forgot password + reset
4. School creation
5. Membership (teacher → school)

Phase 2 — Roster & Reading

6. Class creation (Teacher Portal)
7. Student add/bulk-import + PIN generation
8. Child login (Reader App)
9. Book open → reading session → telemetry
10. Session end → miles/tokens update

Phase 3 — Intelligence Loop

11. Placement test
12. Quiz → Learner Bot feedback
13. Telemetry → Bot (vocab gaps + session summary)
14. Nightly bot run → teacher report
15. Parent Portal digest

Phase 4 — Billing & Compliance

16. Stripe integration + subscription lifecycle
17. Entitlement enforcement across all services
18. GDPR export + deletion
19. Admin APIs + impersonation

6. Open Questions

End-to-End System Flow (Authoritative)

This is the single canonical flow from school onboarding to reporting. Claude Code must be able to implement every step from this section alone. For detailed contracts, follow the page references in each step.

Phase 1: School Onboarding

1. school_admin registers at teacher.readingtester.com → POST /api/auth/register (Account Center) → creates users row (role=school_admin, state=pending_verification) + schools row → sends EMAIL_VERIFICATION email
2. school_admin verifies email → GET /api/auth/verify?token=... → users.state=active → DPA acceptance screen shown
3. school_admin accepts DPA → POST /api/schools/dpa → INSERT school_dpa_agreements (school_id, user_id, accepted_at, ip_address) → redirect to dashboard
4. school_admin invites teacher → POST /api/schools/invite (email, role=teacher) → INSERT invites (token, email, school_id, role, expires_at=48h) → sends TEACHER_INVITE email
5. teacher accepts invite → clicks link → POST /api/auth/accept-invite (token, password) → INSERT users (role=teacher, school_id) → INSERT subscriptions (state=trialing, trial_ends_at=now()+14d) → redirect to teacher portal

Authoritative detail: Page 11 (Sign-Up Flows), Page 03 (Identity)

Phase 2: Class & Student Setup

1. teacher creates class → POST /api/classes (name, year_level, school_id) → INSERT classes (id, teacher_id, school_id, license_id from teacher_licenses) → return class_id
2. teacher imports students (CSV) → POST /api/students/import (class_id, rows[]) → for each row: INSERT students (username=auto-generated, pin=4-digit-random, school_id, teacher_id, class_id, learner_id=UUID) → INSERT class_memberships (student_id, class_id) → return login cards (username + PIN + QR)
3. teacher prints login cards → GET /api/classes/:id/login-cards → renders card HTML with username, 4-digit PIN, QR code linking to app.readingtester.com?user=username. PIN shown once only — not retrievable after dismissal.

Authoritative detail: Page 05 (Roster), Page 11 (Sign-Up Flows Flow D)

Phase 3: Child First Login

1. child enters username + PIN at app.readingtester.com → POST /api/auth/child-login (username, pin) → verify students table → INSERT device_sessions (learner_id, device_id, policy=shared, created_at) → return session JWT
2. placement test shown → child reads 3 calibration passages → POST /api/placement (session_id, responses[]) → calculate FK grade → UPDATE students (placement_results JSON, reading_level DECIMAL) → child lands on library
3. library renders → GET /api/recommendations?learner_id=... → Learner Bot returns personalised book list → fallback: Content Service catalog filtered by child's FK level

Authoritative detail: Page 11 (Sign-Up Flows Flow E), Page 06 (Reading & Telemetry Section 7.1)

Phase 4: Reading Session

1. child opens book → Reader App → POST /api/telemetry/events (event_type=book_opened, learner_id, session_id=new UUID, book_id, client_ts) → Telemetry stores in events table (deduplicated by event_id)
2. child reads pages → each page turn: POST /api/telemetry/events (event_type=page_turned, page_number, time_on_page_ms) → stored offline if no connection, replayed via Service Worker on reconnect
3. child taps word → POST /api/telemetry/events (event_type=word_tapped, word) → definition popup shown from Content Service
4. child completes book → POST /api/sessions/end (session_id, client_ts) → Reader App calculates miles (words_read / 100) → PATCH /api/progress/:learner_id (books_read+1, total_miles+N) → Telemetry fires two parallel calls (5s timeout each): POST /learner-bot/api/v1/telemetry/vocab-taps AND POST /learner-bot/api/v1/telemetry/session-summary
5. Service Worker guarantees delivery: events POST offline → IndexedDB queue → auto-replay on reconnect via BackgroundSync. Server deduplicates on event_id (UUID, 7-day retention).

Authoritative detail: Page 06 (Reading & Telemetry), Section 6 (Events)

Phase 5: Learning Loop (Nightly)

1. 04:00 UTC — Learner Bot cron fires → for each active learner: fetch telemetry (90-day window), load RAG memories (vocab_gaps, reading_patterns, curriculum_state), run gap analysis
2. bot generates teacher report → POST /api/v1/bot/:learner_id/report → stores in bot_reports → Teacher Portal dashboard updated
3. bot detects struggling reader → avg quiz score < 65% on 2+ quizzes → INSERT intervention_queue (learner_id, reason, teacher_id) → Teacher Portal attention list updated
4. bot recommends next book → UPDATE bot_memories (type=recommendation, content_id, reason) → Reader App next-session library shows "Picked for You" card
5. on failure: INSERT failed_runs (learner_id, error, attempted_at) → 05:00 UTC re-run cron retries failed learners. 3 retries with exponential backoff (1s, 4s, 16s). After 3 failures → alert_log.

Authoritative detail: Page 06 Section 7 (Telemetry → Bot), Learner Bot service (port 3120)

Phase 6: Entitlement Enforcement

1. every feature-gated API call → service calls checkEntitlement({user_id, school_id, student_id}) → checks in-process cache (60s TTL) → if miss: GET /api/billing/entitlement (Account Center, X-Internal-Key, 2s timeout)
2. entitlement resolution order: (1) entitlement_grants table (gifted/admin grants) → if found, tier=full. (2) subscriptions table: trialing+valid → full; active+valid → full; past_due+grace → full; else → free. (3) default → free.
3. timeout fallback: if Account Center >2s → tier=free (fail-safe). INSERT audit_log (action=entitlement_check_failed). Child can still read 50 free books. Learner Bot paused. Reports not generated.
4. subscription expires: hourly cron → subscriptions WHERE state=past_due AND grace_ends_at < now() → UPDATE state=expired → UPDATE students.entitlement_tier=free → INSERT audit_log → send SCHOOL_SUBSCRIPTION_EXPIRED email
5. parent linked (optional): teacher invites parent → parent accepts → INSERT parent_links (parent_id, student_id, school_id, teacher_id, approved_at) → parent can view progress at parents.readingtester.com (read-only). Parent NEVER creates a new child record.

Authoritative detail: Page 04 Section 29.3–29.7 (Billing)

End of authoritative E2E flow. Every step above maps to a specific page and section. If a build question arises that is not answered by following these steps to their referenced sections, it is a spec gap — do not invent behavior.