Pickatale Wiki › Pickatale Master Build Wiki

Pickatale Master Build Wiki

Version: v2.0 | Last Updated: 2026-04-19

This is the single source of truth for the Pickatale learning platform. Every service, data model, API contract, compliance rule, and build gate is defined here.

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

Modules

Module Contents
Overview & Architecture Scope, product vision, architecture map, state definitions, build phases, open questions
Data Model & Schema Field tables for all services, full CREATE TABLE DDL for every core table, source-of-truth rules per data domain
API Contracts All REST endpoints per service, request/response shapes, API consistency rules (auth, errors, pagination, idempotency, rate limits)
Identity & Auth User types, lifecycle states, registration/login/logout flows, permissions matrix, full 9-part flow contracts
Billing & Entitlement Teacher-license billing (Stripe, in-platform). Enterprise/school entitlements are externally managed and ingested via entitlement_grants — not via Stripe. Entitlement execution model (middleware, caching, fallback).
Roster & Classroom Class/student management, parent-teacher-child relationship, tenant isolation model, transfer rules
Reading & Telemetry Reader App features, telemetry pipeline, Learner Bot integration, event system, job/queue architecture
Notifications & Edge Cases All notification triggers with templates, edge cases, failure handling
Admin & Compliance Admin API endpoints, impersonation safeguards, audit log schema, GDPR data subject flows (export/delete/audit), deployment model
Acceptance Criteria All GIVEN/WHEN/THEN acceptance criteria (AC-01 through AC-13) with failure paths
Build Order & Checklist Phase-by-phase build order, Claude Code brief, end-to-end build checklist
Sign-Up Flows & Roles School-first onboarding flows for all roles, Account Center as SSO hub, ownership model. Consent handled by school DPA — no platform consent gate.
⚠️ Authority & Build Rules Single source of truth for conflicting decisions. Defines checkEntitlement() ownership, tenant isolation rules, billing split, and build guard compliance checks. All decisions final.
🧪 QA Test Cases 61 test cases across 14 systems — GIVEN/WHEN/THEN format with FAIL PATHs and smoke checklist. Maps to AC-01–AC-13.
👨‍👩‍👧 Parent Linking Contract Canonical implementation contract for Claude Code. Token-initiated, email-verified, magic-link parent account creation and child linking. Full API contracts, data model, threat model, legal basis by market, abuse workflow, alerting rules, security hardening.
🧠 Learner Bot RAG System Intelligence layer architecture for the per-child Learner Bot — graph schema, 5-stage pipeline, multi-tenancy model, GDPR/COPPA privacy rules, open design decisions.

Quick Reference

Service Ports

Reader App       3125    app.readingtester.com
Teacher Portal   3116    teacher.readingtester.com
Parent Portal    3118    parents.readingtester.com
Account Center   3126    account.readingtester.com
Curriculum Mapper 3117   cm.readingtester.com
Adaptive Engine  3119    adapt.readingtester.com
Learner Bot      3120    (internal)
Telemetry        3110    (internal)
LRS              3111    (internal)
Content Service  3112    (internal)
Analytics        3114    (internal)

Critical Rules (Never Violate)

  1. No direct DB access between services — API calls only, X-Internal-Key header
  2. learner_id is always the child's UUID — never integer IDs across services
  3. checkEntitlement({ user_id, school_id, student_id }) in every gated handler — never trust client-side hints. Authoritative contract: Page 04 (Billing), Section 29.3. That is the only definition. Do not duplicate it.
  4. Tenant isolation — filter by school_id when present; otherwise filter by teacher_id (solo-teacher workspace). Never access another tenant's data except as platform_admin.
  5. No secrets in code — .env only, never in Docker image
  6. Audit log every child data access — SOC2 requirement, non-negotiable
  7. Voice audio rule: 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.