📖 Pickatale Platform Wiki
Everything you need to understand what we're building, why we're building it, and how it all fits together — from the reading science to the code.
Welcome to Pickatale
Pickatale is an AI-powered reading platform for children aged 4–11. We make every child a reader — not by drilling them, but by putting the right story in front of the right child at the right moment.
"Read for joy." Every child reads stories they love, while the platform invisibly builds their skills, vocabulary, and curriculum mastery in the background.
What makes us different
Quick navigation
Use the sidebar to explore any section. Start here if you're new:
- 🌟 Vision & Mission — the why behind everything
- 🎓 Educational Foundation — the research that grounds our product decisions
- 🏗️ Architecture — how all the services connect
- 🤖 Learner Bot — the core AI product
🌟Vision & Mission
Sig Dug (founder) built Pickatale on a simple but powerful belief: children learn to read by reading things they love — not by grinding through worksheets.
The Invisible Learning Loop
The child just reads stories they love. The platform handles everything else — detecting gaps, generating the right content, testing mastery, and reporting to teachers with full reasoning.
How the loop works
Invisible
Learning
Loop
curriculum
detects gaps
story
levels text
reads
bot evaluates
Key principle
Reinforcement is invisible to the child. They pick a story about dinosaurs because they love dinosaurs. The system has already woven in the vocabulary targets, text structures, and comprehension challenges their curriculum requires — at exactly their reading level.
Market position
Who we serve
- B2B: Schools, school districts, ministries of education, publishers
- B2C: Families who want to support their child's reading at home
Library
~3,000 books from Oxford University Press, Arcturus, Cricket and others. Growing to 9,000+ through the Pickatale catalog API. Covers ages 4–11, multiple languages, all Flesch-Kincaid levels.
Competitive advantages
- Per-child AI agent (Learner Bot) — not just recommender algorithms
- Cross-nation analytics — unique dataset spanning multiple national curricula
- Full curriculum mapping (CM) — not just "reading stage" levels
- Adaptive content that re-levels and translates existing books, not just suggests new ones
- Modular, licensable components — each service can be sold independently
"The child never works on a 'skill'. They read a book. We know it's the right book. That's the whole product."
🎓Educational Foundation
Every product decision at Pickatale is grounded in reading science and child development research. This page summarises the key findings that drive our design choices.
We don't guess. When we say "warm cream reading background" or "TTS helps struggling readers", it's because the research says so. This section is the evidence base.
1. Reading surface & typography
Background color
The reading surface must be calm. Vibrant design belongs in the library and rewards — not on the page the child is reading.
- Light mode (dark text on light background) improves visual acuity, reading speed, and comprehension across all ages.
- Warm backgrounds (peach, cream, warm white) further improve readability vs cool white — CMU research confirms shorter reading times.
- Dark mode drops comprehension by ~14% when contrast is poor or fonts are thin on pure black (halation effect).
- Cool saturated backgrounds (blue, green, purple) reduce readability — confirmed in multiple studies.
Sources: BOIA.org, tenacity.io, CMU research, UXMatters, teachertoolkit.co.uk
Reading surface: warm cream (#FFF9F8 or similar). Dark mode for reading = pedagogically wrong. Vibrant gradients stay in the library UI, not on reading pages.
Typography for children
| Rule | Value |
|---|---|
| Minimum body font size | 20px (never below 14pt) |
| Font style | Sans-serif, single-storey 'a' and 'g' (double-storey confuses early readers) |
| Line spacing | 1.5×–1.75× font size |
| Line width | 50–75 characters max |
| Letter spacing | 0.12× font size minimum (reduces crowding, helps dyslexic readers) |
| Recommended fonts | Sassoon Primary, Andika, Nunito (rounded, child-friendly) |
2. Finger-follow reading
Children drag a finger across text while reading. The platform highlights the word they're touching and counts those words toward their Miles total.
- Establishes left-to-right directionality and one-to-one word correspondence
- Creates multi-sensory learning (visual + tactile + kinesthetic) — strengthens memory pathways (University of Sydney, 2021)
- Maria Montessori advocated this technique from the early 1900s
- Develops phonemic awareness — children segment words into sounds more easily while tracking
- Beneficial for dyslexic readers — addresses visual processing challenges
- Finger position = proxy for attention focus — enables rich diagnostic telemetry
Sources: reading.com, thereadingspecialists.org, University of Sydney 2021, CEUR-WS.org
3. TTS with word highlighting ("karaoke reading")
The platform reads aloud while highlighting each word in sync — like karaoke. The child can follow along or read silently.
- TTS + synchronized highlighting = higher comprehension vs silent reading (phonics.org, ReadingRockets)
- Reduces cognitive load of decoding → frees attention for comprehension
- Improves reading rate, prosody, and syntactic consciousness (ResearchGate 2024)
- Less intimidating than reading aloud → motivates struggling readers
- Significant improvements in oral reading fluency among less fluent readers
Sources: phonics.org, readingrockets.org, ATIA.org, proquest.com, ODU research
Keep TTS word highlighting. Especially valuable for younger and struggling readers. Speed must be adjustable (default 0.75× for children). Always optional — child controls it.
4. Speedread (RSVP)
One word at a time, at configurable WPM — rapid serial visual presentation. Optional feature, off by default.
- Ages 8+ only — young children lack the working memory to process words fast enough for comprehension
- Max 10 minutes — visual fatigue sets in quickly
- Not the default — opt-in for motivated older readers
- Effective for fluent readers who want to increase their reading rate, not for building comprehension
5. Miles & motivation
Children earn Miles for words read (100 words = 1 Mile). Miles unlock more books. Tokens are earned per 10 Miles.
- Effort recognition (Miles) = pedagogically sound — rewards sustained engagement, not performance
- Tokens must unlock books, not prizes — extrinsic rewards for reading can undermine intrinsic motivation if they signal "reading is a means to an end"
- No leaderboards — competition creates anxiety in struggling readers
- No token loss — punitive mechanics harm motivation in young children
Sources: Self-Determination Theory (Deci & Ryan), reading motivation research
📖Reading Science
Understanding how children learn to read — and why it's hard — is foundational to every design decision we make.
The Simple View of Reading
Reading comprehension = Word Recognition × Language Comprehension. Both must be non-zero. A child who can decode perfectly but has no vocabulary won't understand what they read. A child with rich vocabulary but poor decoding can't access the text.
Pickatale addresses both:
- Word recognition: Finger-follow, TTS with karaoke, phonics-aligned decodables
- Language comprehension: Vocabulary taps, comprehension quizzes, curriculum-mapped content
Flesch-Kincaid (FK) levels
We use Flesch-Kincaid Grade Level as our primary text complexity measure. FK is computed from average sentence length and average syllables per word.
| FK Grade | Age | Example text complexity |
|---|---|---|
| 1.0 – 2.0 | 6–7 | Short sentences, 1–2 syllable words. "The cat sat." |
| 2.0 – 3.0 | 7–8 | Simple paragraphs, common vocabulary. |
| 3.0 – 4.5 | 8–10 | Multi-sentence paragraphs, domain vocabulary beginning to appear. |
| 4.5 – 6.0 | 10–12 | Complex sentences, technical vocabulary, inference required. |
Zone of Proximal Development (ZPD) offset
The Adaptive Content Engine applies a +0.5 FK offset when serving leveled text. A child placed at FK 3.5 receives text leveled at FK 4.0. This ensures the child is always reading in their ZPD — slightly challenged, but not overwhelmed. Vygotsky (1978).
CEFR language levels
For English as an Additional Language (EAL) contexts, we map against CEFR:
| CEFR | Description | FK approx. |
|---|---|---|
| A1 | Beginner | 1.0–2.0 |
| A2 | Elementary | 2.0–3.5 |
| B1 | Intermediate | 3.5–5.5 |
| B2 | Upper intermediate | 5.5–8.0 |
Vocabulary development
The vocabulary gap is one of the strongest predictors of reading comprehension. Children who tap a word in the reader get an immediate popup definition. Those taps are stored as vocabulary gap data and fed to the Learner Bot — enabling the bot to target books that reinforce the specific words the child is struggling with.
Research-backed vocabulary targets per short non-fiction book:
- Ages 5–7: 3–5 target words (introduced before first encounter, with picture support)
- Ages 8–11: 4–7 target words (context-rich definitions, reused across pages)
📊Assessment & Leveling
Pickatale uses a multi-signal approach to understand each child's reading level — then continuously updates it as they read and take quizzes.
Placement assessment
When a child first joins, they complete a short placement assessment that establishes their baseline FK level. This becomes their fk_level in the database and drives all content serving decisions.
Continuous reassessment
Every quiz result updates the child's profile. The Learner Bot evaluates:
- Score > 80%: The child is likely ready to move up ("raise" signal)
- Score 65–80%: Stay at current level, serve more of the same
- Score < 65%: Consider moving down, flag for teacher attention
80% is the standard mastery threshold from Bloom's Mastery Learning (1968). A child scoring 80%+ on a curriculum objective is considered to have mastered it. Below 65% after 2+ quizzes triggers teacher attention.
Quiz design
Quizzes are generated by the Adaptive Assessment Bot specifically for each book and FK level. They test:
- Literal recall: What happened? Who did X?
- Vocabulary in context: What does this word mean here?
- Inference: Why did X happen? (FK 4.0+)
- Text structure: What's the main idea? What's the author's purpose? (FK 5.0+)
Slow page detection
The telemetry system tracks time spent on each page. If a child spends more than 2× the average time on a page, it's flagged as a "slow page". More than 3 slow pages per session triggers an engagement_signal: struggling in the Learner Bot's memory — which the bot uses when selecting the next book.
🏗️Architecture
Pickatale is built as a set of independently deployable microservices, each with its own API and database. Services communicate exclusively via REST APIs — never via direct database access.
Services connect via API contract only. Service A never reads Service B's database directly. If B doesn't have an API endpoint for the data A needs, build one first.
The four core systems
Data flows
Reading session → intelligence
Quiz result → bot update
Vocabulary tap → gap tracking
Infrastructure
- Server: 4 vCPU, 15 GB RAM (AWS EC2) — readingtester.com
- Reverse proxy: Caddy — automatic HTTPS, subdomain routing
- Databases: Single shared MySQL 8 Docker container (shared-db, port 3316). Each project gets its own database and user.
- Containers: All services run in Docker (docker compose per project)
- Internal networking: Services communicate via 172.17.0.1 (Docker host bridge)
- Auth: X-Internal-Key header for service-to-service calls. JWT for user sessions.
⚙️Services & APIs
Each service is independently deployable with its own versioned REST API. Any service can be licensed to external partners.
Intelligence layer
| Service | Domain | Port | Status |
|---|---|---|---|
| Learner Bot | learner-bot.readingtester.com | 3120 | LIVE |
| Adaptive Content Engine | adapt.readingtester.com | 3119 | LIVE |
| Behavioral Telemetry | telemetry.readingtester.com | 3110 | LIVE |
| LRS (xAPI 1.0.3) | lrs.readingtester.com | 3111 | LIVE |
| Recommendation Engine | recommendation.readingtester.com | 3115 | LIVE |
| Content Metadata | content.readingtester.com | 3112 | LIVE |
| Analytics ETL | analytics.readingtester.com | 3114 | LIVE |
| Learner Profile | learner.readingtester.com | 3109 | LIVE |
User-facing products
| Product | Domain | Port | Status |
|---|---|---|---|
| Reader (PWA) | app.readingtester.com | 3125 | LIVE |
| Teacher Portal | teacher.readingtester.com | 3116 | LIVE |
| Curriculum Mapper | cm.readingtester.com | 3100 | LIVE |
| Teacher Materials | tm.readingtester.com | 3101 | LIVE |
| Fluency Assessment | fluency.readingtester.com | 3102 | LIVE |
| Talk (ESL Chat) | talk.readingtester.com | 3104 | LIVE |
| Parent Portal | parents.readingtester.com | 3118 | LIVE |
| Interest Onboarding | onboard.readingtester.com | 3113 | LIVE |
API conventions
- All APIs versioned:
/api/v1/... - External access: API key in
Authorization: Bearer <key>header - Internal calls:
X-Internal-Key: pickatale-internal-key-2026header - Webhooks: every service supports webhook callbacks for key events (objective mastered, report generated, session ended)
- Response format: JSON, snake_case keys
🤖Learner Bot
The Learner Bot is the core of the Pickatale platform. Every child gets their own AI agent with a persistent memory store. It runs nightly, detects gaps, selects content, and prepares reports.
One bot per child
This is not a shared recommendation engine. Each bot holds an individual RAG (memory store) for its child — tracking what they've mastered, what they're struggling with, what worked and what didn't.
What the bot stores
Nightly run cycle
- Pull all memory signals from the child's RAG store
- Identify which curriculum objectives need reinforcement (gaps, low scores, slow pages)
- Select or request generation of a book that targets those objectives at the child's FK level
- Evaluate mastery from recent quiz results — update curriculum_state accordingly
- Prepare reports: teacher (technical, with reasoning) + parent (warm, no jargon)
API endpoints
| Endpoint | Purpose |
|---|---|
| GET /api/v1/bot/:id/status | Current learner profile — reading level, books read, miles, patterns |
| POST /bot/:id/quiz-result | Store quiz result, trigger bot re-evaluation async |
| POST /api/v1/telemetry/vocab-taps | Ingest vocabulary gap data from session end |
| POST /api/v1/telemetry/session-summary | Slow pages, reading pattern, engagement signals |
| GET /api/v1/bot/:id/next-content | Recommendation — next book + curriculum objective reasoning |
| GET /api/v1/bot/:id/teacher-report | Full teacher-facing report with reasoning |
Aiden (aiden011): FK 2.0, Year 2 — struggling reader. Avg quiz 55%, 7 vocab gaps (camouflage, amphibian, predator…), slow pages flagged. On teacher attention list.
Priya (priya012): FK 5.0, Year 6 — excelling reader. Avg quiz 92%, 3 rare technical terms tapped. All quizzes "raise" level recommendations.
📚Content Pipeline
Content flows from curriculum objectives through to leveled, translated, narrated books served to each child. Every step is automated; the teacher's role is review and approval.
The three-step pipeline
CM maps curriculum
The Curriculum Mapper extracts all learning objectives for any territory and year level. The architecture is territory-agnostic — adding a new country is a content task, not an engineering task. Turkey (5,366 unique objectives), UK, and Norway are already loaded as live examples.
Generate general book
AI generates a research-backed, teacher-reviewed canonical lesson book for each objective. This is the verified, approved version. Cannot personalise garbage — this step must produce quality.
Personalise per child
Learner Bot personalises Step 2's approved book for each child — adjusting FK level, language, vocabulary support, and reading challenges based on the child's profile.
Step 3 only works if Step 2 is teacher-approved. Never skip to personalisation before the canonical version has been reviewed.
Book structure
Short curriculum-aligned non-fiction books follow a research-backed structure:
- Cover — title, illustration, grade level indicator
- Learning goal — what the child will know after reading
- Key words — 3–7 target vocabulary items with simple definitions
- Content spreads (3–5 pages) — one idea per spread, visual + text
- Did You Know? — surprising fact to hook interest and aid retention
- Real World Connection — links the topic to the child's lived experience
- Recap — retrieval practice: "Can you remember…?"
- Reflect — higher-order question: "Why do you think…?"
- Teacher layer (not shown to child) — curriculum objective, assessment guidance, differentiation notes
Adaptive Content Engine
The engine takes any book and:
- Re-levels text to any Flesch-Kincaid grade (GPT-powered, provider-swappable)
- Translates to any language (same call — one LLM does leveling + translation)
- Re-narrates with the appropriate voice style for the age group
- Applies ZPD offset (+0.5 FK by default)
- Caches the result — generate once, serve forever, no repeat LLM calls
Library vs Lesson Books
| Library | Lesson Books |
|---|---|
| Fiction, child picks freely | Curriculum-aligned non-fiction, teacher-assigned |
| ~9,000 catalog books | AI-generated per objective |
| Intrinsic motivation driver | Curriculum mastery driver |
| Existing Pickatale platform | New platform space (being built) |
👩🏫Teacher Experience
Teachers are power users of the platform. They get full transparency into what the AI is doing — and always have the ability to override it.
Teacher portal
The teacher portal (teacher.readingtester.com) gives teachers:
Dashboard design principles
- Light theme — scannable, data-dense, less clicks (not dark)
- Dense information — class selector on top, everything visible without scrolling
- Big fonts — teachers read this on classroom displays, not just laptops
- No jargon — "Grade 3.5" not "FK 3.5" in the UI
- Override always available — teachers can always countermand the bot
What teachers see per student
| Signal | Source | Meaning |
|---|---|---|
| Grade X.X (FK level) | Placement + quizzes | Current reading level vs grade expected |
| Books read | Reading miles | Engagement proxy |
| Miles total | Word count × engagement | Sustained reading effort |
| Quiz avg % | Quiz results | Comprehension mastery signal |
| Vocab gap words | Word taps | Which words are barriers to comprehension |
| Slow pages | Telemetry | Pages where reading pace dropped — potential difficulty |
📈Data & Analytics
Pickatale generates a unique cross-national dataset. No other ed-tech platform can compare reading outcomes across countries on equivalent curriculum objectives. The CM is territory-agnostic by design — any country, any curriculum framework, any language. Entering a new market is a content task, not an engineering task.
Analytics hierarchy
Privacy model
- Individual data: visible only to the child's teacher and parent
- Class/school data: aggregated + anonymized
- Nation/global data: k-anonymity enforced, never re-identifiable
- GDPR compliant — full data export and deletion available
- COPPA compliant — parental consent required for children under 13
xAPI / LRS
All reading events are logged as xAPI statements to our Learning Record Store (LRS). This enables interoperability with any LMS that supports xAPI (Tin Can API).
- Events: page_turned, word_tapped, quiz_completed, book_finished, session_started/ended
- All events include: learner_id, book_id, timestamp, FK level at time of event
- Offline events queued in Service Worker IndexedDB, replayed on reconnect
Offline-first telemetry
The Reader app works fully offline. The Service Worker intercepts telemetry POSTs when the device is offline and stores them in IndexedDB (7-day retention). Browser automatically replays them on reconnect — even if the app is closed. Each event has a UUID (event_id) for server-side deduplication.
🗺️Roadmap
What's built, what's in progress, and what's next for the Pickatale platform.
✅ Complete
- Curriculum Mapper (CM) — territory-agnostic, any country supported; Turkey, UK, Norway loaded as live examples
- Reader PWA — FK-leveled text, finger-follow, TTS karaoke, quizzes, vocabulary taps, Miles/Tokens
- Learner Bot — per-child RAG memory, quiz result processing, vocab gap tracking, session summaries
- Telemetry service — xAPI LRS, session tracking, offline-first Service Worker queue
- Adaptive Content Engine — FK leveling, ZPD offset, text caching (1,031 books × 3 levels)
- Teacher Portal — class dashboard, attention list, vocab gap view, student detail cards
- All 5 services connected end-to-end with verified data flows
🔨 In progress
- Lesson book generator (Step 2 of content pipeline) — teacher review + approve workflow
- Reader PWA deployment to app.readingtester.com
- Cross-grade book generation for CM objectives
📋 Next to build
- AI Orchestrator — pipeline manager connecting CM → Create → Bot. The missing piece.
- Pickatale Create API — generate custom illustrated books tied to specific objectives
- Cross-nation analytics — school_id, district_id, nation_code in learner onboarding
- Parent portal — warm reports, "Sofia had a great day!", no jargon
- Mobile narration pipeline — ElevenLabs/Fish Audio voice generation per book per language
- Curriculum objective → book mapping — populate curriculum_mappings table
When the AI Orchestrator is built: CM detects a gap → generates a book → Learner Bot assigns it → child reads it → quiz verifies mastery → teacher sees the full reasoning chain. Fully automated, fully transparent.