AI Maths Tutor System architecture

One child, one agent pipeline, one day at a time

A daily maths programme for a single child, where the teaching decisions are made by Claude Code agents on the parent's own machine. The child sees a plain web page with no model behind it. Every session is written, measured and independently re-solved before they open it — and the number that decides whether they move on is not the number they are shown. Try a session →

The page · asks
Plain HTML on the child's device. One question at a time, every try posted as it happens.
The agents · decide
Eight of them. Mark, diagnose, decide what the topic needs, write tomorrow, re-solve it cold.
MongoDB · remembers
Two collections. Every attempt, every error pattern, every explanation and whether it landed.
The checks · gate
A deterministic script, then an agent that never saw how the questions were written.

01The daily loop, end to end

Read each lane left to right. The top lane is the child, on their own device, with no AI in it. The bottom lane is the parent's machine, where one command runs the whole pipeline. The middle lane is the record both halves depend on. Dashed markers are the two points where the pipeline stops and waits for a person.

Browser The session The child, on their iPad
Opens the page
one session, pre-written
→
Answers
one question at a time
→
Gets it wrong
clue ladder, never stuck
→
Every try posts
as it happens, not at the end
→
Finishes
marked submitted
MongoDB The record Two collections
curriculum
topics, prerequisites, the parent's queue
topicStatus
verdict, every past session, error profile
teachingProfile
how this child learns
brief
grader → builder handoff
sessions
the attempt record, question by question
Claude Code The tutor Parent runs /grade
Fetch
newest ungraded
→
Grade & decide
grader agent
→
Feedback card
only if needed
→
Build tomorrow
teacher or author
→
Draw
illustrator
→
Verify twice
script, then cold re-solve
→ Gate · parent →
Queue it
one pending, no more

The gate is conditional, not ceremonial: an independent re-solve that passes saves by itself. The pipeline stops for a person only when that re-solve fails, or when a second failed check forces a backtrack to a prerequisite — the two cases where a human must actually decide something.

02The two numbers

The single most consequential design decision here, and the one that took a bug to find. A score that counts help as success is the exact number you must not use to decide what comes next.

Completionshown to the child

How many questions ended correct, with any amount of help — a wrong try, three clues, a revealed answer. This is the morale number, large on their own page.

Decides nothing
Clean / unaidedcomputed, never authored

Right on the first try with zero clues and no reveal. This is the mastery number, and the only one progression reads.

Decides advance, hold or drop
Teachingper explanation

Each lesson is split into cycles — teach a bit, then one guided question on that bit, with full support up. It measures the explanation, not the child.

Decides how to re-teach
The trapA 10-out-of-10 session can be a 6-out-of-10 hold.Both numbers are derived from the attempt record by a script, so no agent can round either one in its own favour.

Why a guided question is excluded from the score entirely. It sits immediately after the explanation that taught it, with every clue available. Counting a heavily scaffolded answer toward mastery would inflate precisely the number that decides whether the child moves on. So it gets its own record — concept slug, outcome, whether a second angle was needed — and that record moves the teaching, never the verdict.

03The eight agents

Each is a separate agent definition with its own instructions and its own tool access. Read-only agents are read-only by configuration, not by being asked nicely — which is the whole point of the ones that judge.

Decide, then build, then check
The agent that judges a session cannot edit it. The agent that wrote it never sees the judgement.
Claude Code · the parent's machine
graderevery run

Marks by working each answer itself, diagnoses why each wrong one was wrong, and decides the verdict and next stage.

  • Reads the whole topic history, not one session
  • Sizes tomorrow against the parent's time budget
  • Writes the brief the builder follows
Reads session, historyWrites grading file
feedbackonly if needed

Writes the child-facing card from the grader's diagnosis — steps first, then the rule.

  • Skipped when a lesson comes next
  • Never shames a skipped question
Reads diagnosisWrites the card
teacherlesson days

Writes the lesson as cycles, each with a guided question and a pre-written second angle for a wrong answer.

  • Must define the idea in words before any example
  • Must say why the rule is true
  • A concept that keeps failing gets a different representation, not a reword
Reads brief, teaching profileWrites the session
authorother days

Writes the questions: the ask, the answer, the clue ladder, and the wrong answers it expects.

  • Predicted wrong answers carry their own message
  • A predicted answer may never equal the right one
Reads briefWrites the session
illustratorwhen asked for

Draws the diagrams the session requested, from a fixed vocabulary of shapes — never free SVG, never raw coordinates.

Reads the requestWrites the drawing
verifierevery build

Re-solves every question cold, with no sight of how it was written. Fails on any disagreement — or any ambiguity.

  • Read-only by configuration, so it cannot quietly fix what it finds
Reads the sessionWrites nothing
curriculumsetup only

Researches the published framework for a board and stage, and proposes topics in prerequisite order.

Reads the webWrites a draft for approval
curriculum-reviewersetup only

Reviews that draft blind, with no sight of how it was derived, for false and missing prerequisites.

Reads the draftWrites nothing
The patternEverything that judges is read-only; everything that writes gets judged.It applies twice: the verifier over a session, the reviewer over a curriculum.

04What happens when the child is wrong

There is no skip button, because every rung of this ladder ends in an answer. The cost is that someone has to predict the wrong answers in advance — which is work the authoring agent does, question by question.

Wrong tryWhat the child getsWhat the record gets
FirstThe coach names that specific mistake, if it was one of the predicted ones. The clues unlock; none opens yet.The slip code
Asks for a handThe next unseen clue opens and is read aloud.Clues used
Second and afterThe next clue opens by itself — the child never has to ask to stop being stuck.Clues used
Clues exhaustedShow me how — the answer, with the last clue as the method, and "good on you for keeping at it".revealed
On a checkNo clues at all, and no answer ever shown. After four tries, a Move on button, and nothing else.exhausted

Those last two rows are different diagnoses, and the system treats them that way. revealed means the clues were not enough. exhausted means the child could not get there with no help available and no pressure to perform — the strongest possible signal to re-teach, and two of them on one topic forces a backtrack to its prerequisite. Both outrank a plain wrong answer. Neither is ever described to the child as failure.

05Diagrams as data, not pictures

No agent writes SVG. A diagram is a claim about what must be true, drawn by one agent and measured back by a script — because a wrong picture teaches the error exactly as directly as a wrong answer key does.

1 · Declare

The writing agent states the facts: a triangle with sides 6, 6 and 9. It does not draw anything.

2 · Draw

A separate agent builds the drawing from a fixed vocabulary of shapes — no coordinates invented by hand.

3 · Measure back

The checker re-measures the drawing. Sides that are not 6, 6 and 9 block the session from saving.

4 · Keep the secret

A question can declare words the picture must not print, and the checker reads the labels back to enforce it.

It also refuses a diagram whose labels overlap. A stimulus the child cannot read is as broken as one drawn wrongly — and nobody reviewing the JSON would ever have noticed.

06Who can write what

The governance question in one table. The child's device holds a key that can do two things; the agents that judge can do nothing at all.

ComponentRuns whereSession recordChild's progressThe web
The child's pageTheir devicePost answers onlyNo accessNo model, no key
graderParent's MacReadWrite, via one scriptNo access
feedbackParent's MacReadNo accessNo access
teacher and authorParent's MacWrite a draft fileReadNo access
illustratorParent's MacWrite drawings onlyNo accessNo access
verifierParent's MacReadNo accessNo access
curriculumParent's MacNo accessDraft, on approvalResearch
The checker scriptParent's MacReadNo accessNo access
The parent—WriteWrite · owns the topic queue—

Three things to notice. Nothing reaches the database except through a script that enforces the rules a prose instruction cannot — a passed check always sets mastered, a failed one never does, and a second failed check refuses to save at all without a named prerequisite to fall back to. No agent can queue a second session while one is pending. And the parent owns the topic queue outright: a topic they pause leaves the queue and keeps its entire history, and no agent may silently put it back.

07Setting it up

About half an hour, most of it the database. The only paid part is Claude Code — the grading and lesson writing is the piece no script replaces.

From clone to first session
Nothing reaches the database until you approve it, twice: once for the curriculum, once at the gate.
Node 18 · MongoDB free tier · Claude Code
1 · Connect a database

Atlas's free tier, no card. npm run check tells you in plain English which of the four usual mistakes it is.

2 · Two access keys

One for the child's device, which can only fetch and answer. One for the dashboard. Local dev skips both.

3 · Approve a curriculum

/setup-child researches the board's published framework and proposes topics in prerequisite order.

4 · Build session one

/next-session. There is nothing to grade yet, so this builds the opening session directly.

5 · Run it

npm start. The child's page at /, yours at /dashboard.html.

6 · Give the coach a voice

Optional. Her built-in lines already ship as audio; this records her on your child's own sessions.

7 · Deploy

Optional, and only if the child needs it on their own device. Local-only works completely.

Then, each day

They do the session. You run /grade. That is the whole routine.

The scripts must run on your real machine. Cloud sandboxes are firewalled off from your database, which is the correct outcome: the one copy of a child's record lives somewhere you control.

What the architecture buys

  1. The child waits for nothing. Every session is written ahead of time, so there is no model in the browser, no API key on the server, and no prompt a child can reach.
  2. Help never counts as mastery. Two scores, both computed from the attempt record rather than authored, so the number that decides progression cannot be flattered.
  3. Being wrong is a diagnosis, not a dead end. The ladder means every question ends in an answer, and each rung the child used is a different signal about what to do next.
  4. Judgement is independent of authorship. The agent that re-solves a session never saw it written, and cannot edit what it finds. The same pattern reviews the curriculum.
  5. The teaching is measured too. Each explanation has its own guided question, so a concept that keeps needing a second angle is visible across topics — and gets a different representation next time, not a reword.
Built for one child at a time, by their parent, on their own database. There is no multi-tenant mode and no hosted service to sign a child up to.
Code on GitHub · Try a session — a seeded demo child, nothing saved. Get one wrong on purpose; that is where most of the system lives.