Build Order & Checklist

Part of: Pickatale Master Build Wiki | Version: v1.7 | Last Updated: 2026-04-18

12. Build Order

Source: (D) | Status: Confirmed

Phase 1 — Infrastructure ✅ COMPLETE

22 services live. Reader App live with finger-follow, vertical mode, accessibility panel, TTS, karaoke. Nightly bot verified 2026-04-17.

Phase 2 — Intelligence Loop ← CURRENT (INCOMPLETE)

Must build in this order:

1. CM REST API — GET /api/v1/objectives (territory, year_level, subject). X-Internal-Key auth. Unblocks everything else.
2. AI Learning Orchestrator — gap detection → story selection → adaptive levelling → assessment trigger → mastery eval → reports. Port 3121.
3. Reinforcement Engine — built inside Orchestrator. Ranks gaps by: word tap frequency, MAZE errors, low WCPM, comprehension <65%, slow pages.
4. Assessment Bot — 3–5 MCQ questions per book (GPT-4o from page texts). Score → level_recommendation. POST result to Learner Bot.
5. Comprehension Quiz UI in Reader App — post-book screen, fetches questions from Assessment Bot.
6. Placement Test in Reader App — first-login flow, sets initial FK level in Learner Profile.
7. Account Center learner_profiles schema — full SSO profile unification.

Phase 3 — Fix + Wire Siloed Services

1. Wire SendGrid (key from Sig — legal requirement).
2. Swap to Azure TTS (key from Sig — code ready).
3. Start Decodables, Voice Assessment, Talk AI services.
4. Wire Fluency Assessment → Learner Profile (push FK + CEFR after each scoring).
5. Wire Voice Assessment → Learner Profile.
6. Wire Decodables, Talk → Telemetry.
7. Build landscape reading mode in Reader App.
8. Build Miles/Tokens reward UI.
9. Teacher Portal SSO via Account Center.

Phase 4 — Real Data + ML

1. Pickatale Create API (Borja) — personalised illustrated stories.
2. First real children on platform — Learner Bot live cycles.
3. Recommendation Engine v2 — collaborative filtering.
4. ML training pipeline.

13. Claude Code Build Brief

Source: (D) + code audit | Status: Confirmed

Stack (currently deployed — confirmed)

Database Connection

Host from containers: : (see ops docs)
Root password: stored in secure env — contact server admin
Rule: docker compose down && up after .env changes (never restart — does not reload env)

Service Disk Locations (Confirmed)

Non-Negotiable Rules

1. Never hardcode secrets — all in .env files only.
2. No cross-service DB access — API contracts only (X-Internal-Key).
3. learner_id (UUID) is the universal child identifier — never integer IDs cross-service.
4. All services connect to the shared DB via internal host (see ops docs — never hardcode the address).
5. docker compose down && up (not restart) after .env changes.
6. Show live test output before marking any task done.
7. Use Context7 MCP before writing code for any 3rd-party library.
8. Voice audio MUST NOT be stored. Audio may exist only in-memory during request processing and must be deleted immediately after transcription. No logging, caching, queues, or retries may contain raw audio.
9. Raw touch data must be anonymised after session analysis.
10. Every web project must use the Pip logo as favicon — never default framework icons.

Immediate Phase 2 Tasks (in order)

**Task 1: CM REST API

File: /home/ubuntu/cm/src/routes/objectives.ts Endpoint: GET /api/v1/objectives?territory=&year_level=&subject= Auth: X-Internal-Key Returns: [{id, title, description, difficulty, vocabulary[], story_potential_score}]

Task 2: Orchestrator service New service: /home/ubuntu/orchestrator/ | Port: 3121 Flow: query Learner Bot status → query CM objectives → select story → POST to Adaptive Engine → store for Reader → trigger Assessment Bot → receive result → POST to Learner Bot quiz-result → update Learner Profile

Task 3: Assessment Bot Module or service. POST /api/v1/assess/generate (GPT-4o, 3-5 MCQ). POST /api/v1/assess/result (score, level_recommendation drop/hold/raise). Pass threshold: 65%.

Task 4: Comprehension Quiz UI File: /home/ubuntu/reader/client/src/pages/QuizPage.tsx Trigger: after book completed. Fetch from Assessment Bot. Submit via reader server proxy to Learner Bot /bot/:learner_id/quiz-result.

Task 5: Placement Test File: /home/ubuntu/reader/client/src/pages/PlacementTest.tsx Trigger: first login (reading_level is null). Short passage at median FK. Adjust up/down based on responses. PATCH Learner Profile with result.

27. Build Order (Complete — Including Identity and Billing)

Source: (D) | Status: Confirmed

Phase 1 — Identity Foundation (MUST BUILD FIRST)

These do not exist yet. Nothing else is buildable without them.

1. invites table + invite flow (flow 15.9)
2. email_log + audit_log tables (NFR-012 compliance)
3. subscriptions + entitlement_grants tables
4. checkEntitlement() middleware — called by every protected endpoint
5. Teacher Portal teacher_notifications table + PARENT_CLAIM_REQUEST flow
6. parent_claims table + claim approval flow (flow 20.1)

Phase 2 — Intelligence Loop (Section 12 — unchanged)

CM REST API → Orchestrator → Assessment Bot → Quiz UI → Placement Test → Account Center learner_profiles

Phase 3 — Billing (After Phase 1 Identity)

1. Stripe integration (checkout, webhooks, subscription lifecycle)
2. Subscription expiry handling (grace period, feature lock, bot pause)
3. Admin entitlement grant/revoke tool
4. Payment receipt emails, renewal failure emails

Phase 4 — Admin Tools (Section 24)

1. admin.readingtester.com panel
2. Impersonation (Section 24.2)
3. Merge duplicates (Section 24.6)
4. Audit log viewer (Section 24.7)

Phase 5 — Fix Siloed Services (Section 12 Phase 3)

Wire Fluency → Learner Profile. Start Decodables, Voice, Talk. Azure TTS swap. Landscape mode. Reward UI.

35. End-to-End Build Checklist

Source: (D) | Status: Confirmed as build gates

Claude Code must verify ALL items pass before each phase is considered complete.

Gate 1: Identity (Sections 28–29 prerequisite)

• POST /api/auth/register (teacher + parent)
• POST /api/auth/verify-email
• POST /api/auth/login (teacher, parent, child separate endpoints)
• POST /api/auth/logout
• POST /api/auth/forgot-password
• POST /api/auth/reset-password
• POST /api/auth/accept-invite
• GET /api/auth/session (middleware)
• audit_log table populated on every auth event
• bcrypt cost 12 (users), cost 10 (pins)
• Rate limiting on all auth endpoints

Gate 2: Billing (before any feature access)

• subscriptions table exists
• entitlement_grants table exists
• checkEntitlement() middleware called on every protected endpoint
• Stripe webhook handler live (checkout, payment_succeeded, payment_failed, subscription.deleted)
• Subscription expiry cron running every hour
• Free-tier enforcement: 50-book limit enforced server-side
• Bot stops on expiry

Gate 3: Roster (before children can read)

• POST /api/v1/classes
• POST /api/v1/classes/:id/students (single add, PIN returned via token)
• POST /api/v1/classes/:id/students/import (CSV)
• GET /api/v1/pin/:token (one-time PIN reveal, 10-min TTL)
• POST /api/v1/students/:id/reset-pin
• POST /api/v1/classes/:id/login-cards (PDF, no file:// paths)
• PATCH /api/v1/students/:id/move
• DELETE /api/v1/classes/:id (archive, cascade to students)
• Learner Profile Service called on student creation

Gate 4: Child Reading

• Child login: username + PIN → uc_session (child role)
• Placement test on first login → writes reading_level to Learner Profile
• Library: 50 books (free) / all (full tier) — server-side filter
• Telemetry fires on page_turned, word_tapped, session_ended
• Offline queue (IndexedDB + Service Worker replay)
• FK-levelled text served via Adaptive Engine
• Comprehension quiz shown after book (full tier only)
• Miles + token accumulation

Gate 5: Intelligence Loop

• Learner Bot nightly cycle at 04:00 UTC
• Teacher report generated + stored
• Parent digest generated + stored
• Intervention flags populated in Teacher Portal
• CM REST API: GET /api/v1/objectives

Gate 6: Notifications

• SendGrid API key configured (from Sig — OQ-002)
• VERIFY_EMAIL working end-to-end
• WELCOME_TEACHER / WELCOME_PARENT
• PASSWORD_RESET
• CHILD_LOCKED_PIN in-app notification
• WEEKLY_PARENT_DIGEST (Sunday 08:00 UTC cron)
• RENEWAL_FAILED

Gate 7: Admin Tools

• Admin panel access (platform_admin 2FA)
• Impersonation with orange bar + audit log
• Grant/revoke entitlement
• PIN reset for any student
• Merge duplicate students
• View audit log (filterable)