WanderWords for Schools
A production-grade Mandarin learning engine — adaptive stories, structured progression, printable worksheets, gamified practice — reframed for institutional deployment, school partnerships, and white-label licensing.
Executive Reframe
WanderWords is not "just a children's Chinese learning app." It is a structured Mandarin acquisition engine with five interlocking capabilities that map directly to institutional needs.
Adaptive Story Generation
AI-generated stories calibrated to each student's exact vocabulary level. Every story uses only known characters plus 3–5 new introductions — comprehension-first learning, not random content.
State Machine + XP System
Characters move through to_learn → practicing → known via blended evidence (story exposure + writing practice). Event-sourced XP ledger. 12-level system. Config-driven unlocks.
Home ↔ School Continuity
Printable PDF worksheets with stroke order (田字格 grids), mnemonic decomposition, and example sentences pulled from the student's own stories. Digital practice meets physical writing.
Gamification + Mascot Cast
Six recurring mascot characters (Qi, Ling, Ming, Yong, Fent, Meng) appear in every story. XP rewards, level badges, streak tracking, and celebration moments create retention loops that keep students reading between classes.
Multi-Profile Architecture
One parent account supports multiple child profiles, each with independent vocabulary state, story history, and progression data. Trial, monthly, and annual plans with Stripe-powered billing.
B2C → B2B Translation Layer
A structured mapping of every existing consumer-facing surface to its institutional equivalent.
| Current B2C Surface | School / B2B Equivalent | What Changes | Lift |
|---|---|---|---|
| Parent account | Family portal / home reinforcement account | Remains as-is. Parent is still the home-side user. | None |
| Child profile | Student profile | Add optional school/class association. Core model unchanged. | Low |
| Dashboard (story streak, XP, level badge, progress ring) | Student dashboard + parent view | No change. Already shows per-child progress with level, XP, streak. | None |
| Story generation (theme selection → AI story) | Guided reading assignment / take-home reinforcement | Teacher can pre-select themes or assign "generate a story tonight." Engine is the same. | Low |
| Story reader (pinyin toggle, character tap, comprehension) | Student reading experience | No change needed. Pinyin toggle per-child already exists. | None |
| Post-story review (mark hard characters) | Teacher/parent review checkpoint | Add teacher as additional reviewer. Current parent flow unchanged. | Med |
| Bookshelf (story history, re-reading) | Reading log / portfolio | Add teacher read-only view. Core bookshelf unchanged. | Low |
| Workbook (character list by state: known/practicing/to_learn) | Student mastery dashboard | Map existing states to school-friendly labels. Add aggregate view for teacher. | Med |
| Worksheet PDF generation (stroke order, 田字格, mnemonics) | Printable homework / class worksheets | Already generates print-ready PDFs. Teacher bulk-generation is an extension. | Low |
| Character state machine (auto-graduation via blended evidence) | Competency tracking / mastery model | No change. State machine is curriculum-agnostic. | None |
| Curriculum selector (HSK 1–3, YCT 1–4, Starter 500) | Curriculum alignment layer | Add school-specific curriculum presets. Current selector framework handles it. | Low |
| XP / levels / streaks (12-level system, event-sourced) | Participation & motivation system | Config-driven — thresholds, XP values tunable without code changes. | None |
| Stroke practice (HanziWriter quiz mode, rounds of 5) | Writing practice module | Architecture locked (ADR-035). Dual entry points. No school-specific changes needed. | None |
| Onboarding (use case → curriculum → character baseline) | Student enrollment / placement | Add school-provisioned enrollment path (teacher sets baseline). | Med |
| Subscription billing (Stripe, trial, monthly, annual) | School license / seat model / institutional billing | New billing layer needed. Current Stripe integration provides foundation. | High |
| Mascot characters (Qi, Ling, Ming, Yong, Fent, Meng) | Brand engagement layer / white-label customizable | In branded mode: keep as-is. In OEM mode: mascots are replaceable assets. | Med |
| Admin panel (user management, comps, subscriptions) | School admin console | Extend existing admin with teacher/class management. Admin auth exists. | High |
Product Surface Mapping
Each major product surface, its current state, what it means for schools, and white-label relevance.
| Surface | Current State | School Value | OEM Relevance | Lift |
|---|---|---|---|---|
| Story Generation Loop | Live. GPT-4o-mini generates stories calibrated to child's known vocabulary + 3–5 new characters. Theme selection. Retry logic. Structured validation. Atomic creation via RPC. | Take-home reading that reinforces what was taught in class. Every student gets a unique story matched to their level. | Core engine. Licensable as API. Theme/prompt layer is customizable. | Ready |
| Reading & Review Flow | Live. Story reader with pinyin toggle, character tap-to-learn, post-story celebration, parent review screen. | Students read independently or with parents. Teachers see which characters were marked hard. | Core UX. Skinnable. Character interaction model is the differentiator. | Ready |
| Worksheet PDF Engine | Live. Puppeteer-generated PDFs with stroke order decomposition (Make Me a Hanzi data), 田字格 grids, pinyin, English meanings, contextual example sentences. | Print-ready homework. Personalized to each student. Quality comparable to commercial 田字格 workbooks. | High OEM value. Schools can brand worksheets. Already generates professional output. | Ready |
| Character Mastery Model | Live. Three-state machine (to_learn → practicing → known). Blended evidence: 3 story exposures + writing practice per hop. Parent override. Event-sourced audit trail. | Objective competency tracking. Teachers see exactly which characters each student knows, is practicing, or hasn't started. | Core IP. The evidence model and state machine are the pedagogical backbone. | Ready |
| Gamification | Live. 12-level system. Event-sourced XP ledger. Streak tracking. Level-up celebrations. Config-driven unlock thresholds. Dashboard gamification card. | Participation incentive. "Homework kids actually want to do." Reduces dropout between sessions. | XP values and level names are config-driven — tunable per deployment without code changes. | Ready |
| Curriculum System | Live. HSK 1–3, YCT 1–4, LinguaPals Starter 500. Two-layer onboarding. | Schools align to their own curriculum. Custom character list is a configuration task. | Curriculum presets are data, not code. Adding a school's custom list is config-level work. | Adapt |
| Multi-Profile System | Live. One parent account, multiple child profiles. Each child has independent state. Max 5 learners. | Foundation for classroom rosters. Each student already has isolated state. | Multi-tenant architecture is implicit. Needs explicit tenant/school layer for true B2B. | Adapt |
| Billing & Access | Live. Stripe. Trial → checkout → webhook → subscription. Monthly, annual, add-on child. Access state resolver. | Foundation exists but needs institutional billing layer (school license, seat model). | Stripe infra reusable. Needs new billing entity (school) above parent accounts. | Build |
School Use Cases
Five concrete institutional modes where WanderWords fits today — with honest assessment of what's ready and what needs work.
Mandarin Weekend School — Between-Class Reinforcement
Who uses it: Students attend Saturday/Sunday Mandarin school. Parents want structured practice during the week.
How it fits: Teacher sets the curriculum level to match the school's textbook. Each week, the student generates 2–3 stories using characters from class. Worksheets are printed for at-home writing practice. The parent sees the same character states the school is teaching.
Value created: Students get 5× more exposure to characters between classes. Parents have a concrete "homework" tool. Schools can point to measurable between-class engagement.
Already relevant: Story generation, curriculum selector, worksheet PDFs, character mastery tracking, XP/streak system.
Adaptation needed: Low — Teacher needs read-only view of student progress. Curriculum presets should match common weekend school textbooks (Mei Zhou, Ma Li Ping, etc.).
After-School Enrichment Program — Engagement + Retention
Who uses it: After-school Mandarin programs competing for enrollment against other extracurriculars.
How it fits: WanderWords becomes the "take-home" layer. Students use it between sessions. The gamification system (XP, levels, streaks) creates habit loops. Stories featuring the mascot crew give kids something to look forward to.
Value created: Programs can offer "app-included" as a premium differentiator. Parents see tangible value (worksheets, progress data) beyond in-class time. Reduces churn — kids who use the app between sessions are less likely to drop the program.
Already relevant: Full product loop, gamification, mascot engagement, streak system.
Adaptation needed: Low — Program branding on login screen. Cohort-level progress view for program director.
Private Academy with Cohorts — Structured Curriculum Companion
Who uses it: A private Chinese language academy running multiple class levels with defined curricula.
How it fits: Each class maps to a curriculum preset (HSK 1, HSK 2, etc.). Teachers assign story generation as homework. The character mastery model provides objective assessment data. Worksheets supplement class materials.
Value created: Objective per-student mastery data. Personalized practice at scale. Professional-grade printable worksheets reduce teacher prep time.
Already relevant: Curriculum system, mastery model, worksheet engine, multi-profile architecture.
Adaptation needed: Med — Teacher dashboard with class roster, aggregate mastery view, and assignment capability. Roster import/invite flow.
Heritage Learner Supplemental Literacy — Home + School Bridge
Who uses it: Chinese heritage families where the child speaks Mandarin at home but reads/writes at a lower level.
How it fits: The curriculum selector already handles this — "My Own Path" mode lets parents set a custom character baseline reflecting what the child speaks vs. reads. Stories are generated at the child's reading level, not their speaking level.
Value created: Addresses the specific gap heritage learners face (oral fluency >> literacy). Schools can offer a differentiated practice tool.
Already relevant: Curriculum selector with custom baseline, character state model, personalized story generation, writing worksheets.
Adaptation needed: Low — Heritage-specific curriculum presets. Messaging adjustment.
Teacher-Led + Home Follow-Through — Blended Learning Model
Who uses it: Any school that wants structured in-class teaching with measurable home practice.
How it fits: Teacher introduces new characters in class. Students go home and generate a story using those characters. Parent and child read together. Parent reviews hard characters. Student prints and completes a writing worksheet. Next class, teacher has data on which characters each student found difficult.
Value created: Closed feedback loop: teach → practice → measure → adjust. Parents are actively involved. "Homework" is a story about space pirates, not a drill sheet.
Already relevant: Story generation with controlled new characters, post-reading review flow, worksheet generation, character mastery states.
Adaptation needed: Med — Teacher-initiated assignment flow. Class-level mastery dashboard showing which characters the class collectively struggles with.
User Model Expansion
Current B2C roles mapped to B2B roles, with honest assessment of what exists vs. what's new.
Student
Sees: Dashboard, story reader, bookshelf, workbook, celebration screens, XP/level
Does: Reads stories, taps characters, completes writing practice, earns XP
Status: Fully built. Profile isolation, independent state, multi-profile support all live.
Parent
Sees: Dashboard, settings, billing, workbook review, story generation, all child profiles
Does: Creates stories, reviews hard characters, generates worksheets, manages subscription
Status: Fully built. In B2B context, parent role unchanged — they remain the home-side user.
Teacher
Would see: Class roster, per-student mastery breakdown, aggregate class progress, assignment controls
Would do: View student progress, set curriculum level, assign story themes, review class-wide character difficulty patterns
Foundation: Admin panel has user search, account management. Student data APIs already exist (GET /progress/:childId). Read-only teacher view is a permissions layer, not a new system.
School Admin
Would see: School-wide dashboard, all classes, enrollment stats, billing, teacher accounts
Would do: Manage teachers, create classes, import rosters, handle institutional billing
Foundation: Admin panel exists with user management and subscription controls. Needs school/tenant entity layer on top.
Class / Cohort Owner
Would see: Subset of teacher view, scoped to one class
Would do: Same as teacher but limited to their assigned class
Foundation: Data isolation already works per-child. Class = group of child profiles. Permission scoping is new.
Why Would a Mandarin School Care?
Commercially legible value propositions grounded in real school problems.
| School Problem | How WanderWords Solves It | Mechanism (Already Built) |
|---|---|---|
| Students forget between classes. Weekend and after-school programs lose 80% of learning to the gap between sessions. | Structured daily practice that students actually enjoy. Stories are engaging; worksheets are personalized; XP/streaks create habit loops. | Story generation engine, worksheet PDFs, gamification system (XP, streaks, level-ups, celebration screens). |
| Homework nobody wants to do. Generic worksheets are boring. Kids resist. Parents nag. | "Homework" is reading a story about space pirates or jungle explorers with their favorite mascot characters, then printing a personalized worksheet for the 5 characters they found hardest. | Theme-based story generation, mascot cast (6 characters), post-story character review, contextual worksheet generation tied to the child's own stories. |
| Parents can't see what's happening. Parents pay tuition but can't track their child's actual progress between classes. | Real-time dashboard showing characters known, stories read, current level, streak, and mastery breakdown. | Parent dashboard with progress ring, XP counter, level badge, character mastery states (known/practicing/to_learn), bookshelf history. |
| One-size-fits-all materials. Every student gets the same worksheet regardless of what they actually know. | Every story and worksheet is calibrated to the individual student's vocabulary level. A student who knows 200 characters gets different content than one who knows 50. | Per-student character state tracking, story generation with controlled vocabulary, character placement/sequencing rules, curriculum baseline system. |
| Drop-off after the first semester. Motivation fades. Families leave. | Gamification creates long-term engagement. Students care about their level, their streak, their mascot characters. | 12-level progression, streak system, XP celebrations, level-up modals, mascot crew that students develop attachment to across stories. |
| Perceived low value of tuition. Parents question whether weekly classes alone justify the cost. | Schools that bundle WanderWords access can show: "Your tuition includes 7-days-a-week structured practice, personalized to your child." | Full product loop running 24/7. Worksheet PDFs are tangible. Dashboard progress is visible. The school's offering transforms from "2 hours of class" to "a complete learning system." |
White-Label / OEM Positioning
Three partnership models, from lightest to deepest integration.
Branded School Partnership
What the school gets: WanderWords access bundled with tuition. School's name and logo on login screen. School-specific curriculum preset. Teacher gets read-only class progress dashboard. Students get the full WanderWords experience.
What stays WanderWords: All product surfaces, mascot characters, story engine, branding within the app, domain (app.wanderwords.co).
What can be branded: Login page co-branding, welcome message, curriculum label ("Mrs. Chen's HSK 1 Class"), worksheet header.
Complexity: Low–Med — Primarily a billing and onboarding change. Teacher dashboard is the main new build.
Sales attractiveness: Easiest to pitch. Lowest friction. "Add this to your program."
White-Label OEM Deployment
What the school gets: The full WanderWords engine running under their own brand. Their name, logo, color scheme, domain. Custom mascot characters or no mascots.
What stays WanderWords: Architecture, story generation engine, progression system, worksheet engine, all backend services. WanderWords is invisible to the end user.
What can be branded: Everything visible — app name, domain, logos, color palette, mascot illustrations, curriculum labels, worksheet headers, celebration screens, onboarding copy.
Complexity: Med–High — Multi-tenant architecture, theme engine, asset pipeline for custom mascots.
Sales attractiveness: Higher revenue per deal. Targets larger academies or chains that want to own the student relationship.
Curriculum Engine / Engagement Layer Integration
What the school gets: WanderWords' story generation engine and progression system as an API layer, integrated into their existing platform or LMS.
What stays WanderWords: Backend APIs: story generation, character state management, XP calculation, worksheet PDF generation. No frontend.
What can be branded: Everything — the school builds their own frontend. WanderWords is an invisible engine.
Complexity: High — API productization, documentation, multi-tenant backend, SLA commitments.
Sales attractiveness: Highest ceiling but longest sales cycle. Targets EdTech platforms, large academy chains.
| Dimension | Model A: Branded Partner | Model B: White-Label | Model C: Engine API |
|---|---|---|---|
| Time to pilot | 4–6 weeks | 8–12 weeks | 12–20 weeks |
| Revenue per school | Low–Med | Med–High | High |
| Engineering lift | Teacher dashboard, billing | Multi-tenant, theming, deployment | API productization, docs, SLA |
| School sees WanderWords brand? | Yes — co-branded | No — school's brand only | No — invisible engine |
| WanderWords controls UX? | Yes | Mostly (themed) | No — school's frontend |
| Best for | Single schools, small academies | Academy chains, franchises | EdTech platforms, LMS vendors |
Why This Can Be Piloted Fast
This is not a vaporware proposal. The system is live, hardened, and production-tested across 86 development sessions.
Real Architecture
React + Vite frontend on Vercel. Express 5 backend on Render. PostgreSQL on Supabase with Row-Level Security. Production infrastructure with structured logging, input sanitization, and error boundaries.
Real Progression Logic
A deterministic state machine wrapped by a progression resolver that enforces invariants. Blended evidence model. Event-sourced XP. 10 formally defined invariants. Level 3 freeze on critical paths.
Real Learning Loop
Story generation → reading with pinyin support → character review → worksheet generation → writing practice → mastery update. The full loop works end-to-end in production today.
Real Billing Foundation
Stripe integration with webhooks, subscription management, trial-to-paid conversion, plan upgrades, add-on children, comp/revoke states, and a single-source-of-truth access resolver.
Real Curriculum Structures
HSK 1–3, YCT 1–4, and a curated Starter 500. Two-layer onboarding. Character seeding scripts. Stroke order data from Make Me a Hanzi for 9,000+ characters.
Real Quality Record
198 bugs tracked. 197 fixed. 1 deferred. Two full production audit passes. Row-level security. Atomic story creation. Webhook idempotency. Production-grade hardening.
Gap Analysis for B2B Readiness
An honest assessment. Three buckets: ready now, adaptable for pilot, requires real new work.
| Capability | Status | Detail |
|---|---|---|
| Story generation engine | Ready Now | Live, validated, atomic, with retry logic and structured validation. |
| Character mastery tracking | Ready Now | Three-state model with blended evidence. Event-sourced. Audit trail. |
| Worksheet PDF generation | Ready Now | Print-ready PDFs with stroke order, 田字格, contextual sentences. |
| Student profiles (independent state) | Ready Now | Multi-profile with isolated vocabulary, stories, progression. |
| XP / gamification / streaks | Ready Now | Config-driven. Tunable without code changes. |
| Curriculum presets | Ready Now | HSK 1–3, YCT 1–4, Starter 500. Framework supports new presets. |
| Stroke practice (writing) | Ready Now | HanziWriter quiz mode. Architecture locked (ADR-035). Dual entry points. |
| Reading flow (pinyin, tap-to-learn) | Ready Now | Full reader with per-child pinyin preference, character detail popover. |
| School-specific curriculum presets | Pilot-Ready | Adding a new preset is data configuration. Need school to provide their character list. |
| Student-to-class association | Pilot-Ready | Child profile needs a class_id field. Lightweight schema addition. |
| Teacher read-only progress view | Pilot-Ready | Data APIs exist (GET /progress/:childId). Need a frontend view scoped to a class. |
| Co-branded login / onboarding | Pilot-Ready | School logo + welcome message on login. CSS variable override. Low lift. |
| Invite-based enrollment | Pilot-Ready | Teacher generates invite link → parent signs up → child auto-associated with class. |
| Worksheet branding (school name on PDFs) | Pilot-Ready | PDF template change. Puppeteer renders from HTML — adding a header is trivial. |
| Tenant / school entity layer | B2B Extension | New DB entity: school → classes → students. Multi-tenant data isolation. Biggest architectural addition. |
| Teacher dashboard (full) | B2B Extension | Class roster management, aggregate mastery views, assignment system. New frontend pages + API routes. |
| Roster import (CSV / bulk) | B2B Extension | Parse CSV → create parent accounts + child profiles → associate with class. |
| School-level analytics | B2B Extension | Aggregate queries across all students in a school. Data exists; aggregation layer is new. |
| Institutional billing | B2B Extension | School pays for N seats. Per-student or per-class pricing. New billing entity. |
| Branding / theme controls (OEM) | B2B Extension | CSS variable override system, asset pipeline for custom mascots. Only needed for Model B/C. |
| COPPA / parental consent | B2B Extension | Known gap. Email verification + parental consent flow. Pre-launch blocker for B2C too. |
School Pilot Proposal
A concrete pilot structure using Model A (Branded Partnership) with a single school.
Pilot Parameters
Week-by-Week Structure
| Week | Activity | Participants |
|---|---|---|
| 0 (Setup) | School provides class roster + curriculum alignment. WanderWords creates accounts, sets curriculum presets, configures school branding on login. Teacher walkthrough session. | School admin, teacher, WanderWords |
| 1 | Parents receive invite links. Onboard their children. First story generated in class (guided). Worksheet printed and sent home. | Teacher, parents, students |
| 2–3 | Students generate 2–3 stories per week at home. Parents review hard characters. Worksheets printed. Teacher checks class progress weekly. | Parents + students (daily), teacher (weekly) |
| 4 | Mid-pilot check-in. Review engagement metrics (stories generated, worksheets completed, streak rates). Adjust curriculum alignment if needed. | Teacher, WanderWords, school admin |
| 5–7 | Continued use. Teacher begins using mastery data to inform class planning. Parents provide qualitative feedback. | All participants |
| 8 | Pilot wrap. Measure outcomes. Present results. Discuss expansion to additional classes or full-school deployment. | School admin, teacher, WanderWords |
What Gets Measured
Engagement
- Stories generated per student per week
- Worksheets completed
- Writing practice sessions
- Streak maintenance rate
- Average session duration
Learning Outcomes
- Characters moved to "known" per student
- Characters moved to "practicing" per student
- XP earned (proxy for activity volume)
- Level progression
- Pre/post character recognition count
Satisfaction
- Parent NPS survey (week 4 + week 8)
- Teacher qualitative feedback
- Student engagement (return rate, theme choices)
- "Would you continue?" conversion question
What Success Looks Like
Commercial Models
Possible B2B monetization structures. These are model frameworks, not final pricing.
| Model | Structure | Includes | Best For |
|---|---|---|---|
| Per-Student Seat | Annual fee per enrolled student | Full student access, parent access, teacher dashboard, worksheets, all content | Schools with stable enrollment |
| Per-Class License | Annual fee per class (up to N students) | Same as seat model but bundled. Simpler for schools that think in classes. | Weekend schools, after-school programs |
| School-Wide License | Annual school-level subscription | Unlimited students and classes. Teacher dashboard. Admin panel. | Larger academies wanting simplicity |
| Setup + Annual | One-time onboarding fee + recurring annual | Curriculum alignment, roster import, teacher training, co-branding setup | Model A partnerships with customization |
| White-Label Premium | Setup + annual license + per-student royalty | Full white-label deployment with custom branding, domain, mascots, curriculum | Academy chains, franchise operations |
| API / Engine License | Annual platform fee + usage-based | Story generation API, progression API, worksheet PDF API. Documentation and SLA. | EdTech platforms, LMS integrators |
For an initial pilot, the recommended approach is a free or heavily discounted 8-week trial (one class, ~20 students) that converts to a per-class or school-wide annual license based on results. This removes purchase friction and lets the data make the case.
Strategic Positioning
What WanderWords becomes in B2B terms.
WanderWords is not an app. It is an engine.
Specifically: a Mandarin reading, writing, and engagement engine with adaptive story generation, competency-tracked character mastery, printable reinforcement materials, and a gamification layer — deployable as a school companion product, a white-labeled institutional tool, or an invisible curriculum engine inside someone else's platform.
Learning Program
The institutional opportunity is not "selling an app to schools." It is transforming what a Mandarin school can offer its families — from "2 hours of class per week" to "a complete, always-on learning system that tracks every character, adapts to every student, and gives parents something tangible to see."
Schools that adopt this don't just add a tool. They fundamentally change their value proposition to parents — and that changes retention, referrals, and willingness to pay.