Skip to content
chuma-beepPublic

About

Open-source adaptive math learning engine: 3,015 concepts, generated problems, mastery gating and FSRS spaced review. Go + Next.js, self-hostable.

Topics

Resources

Contributing

Stars

417 stars

Watchers

1 watching

Forks

Latest commit

 

History

2,099 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

The Mathua landing page, showing the adaptive mathematics hero

Math Understanding Agent

An open-source adaptive math learning engine

Go React License Support Sponsor Concepts Domains


Start learning at mathua.com · Star Mathua on GitHub


Mathua is a local-first adaptive math learning engine inspired by the mastery-gating philosophy of Math Academy. It guides a learner from arithmetic through university math through a checked prerequisite DAG of 3015 atomic concepts and 29 courses, never advancing until the evidence says the prerequisite is mastered. Knowledge is scaffolded into 9045 worked examples (3015 KP shard files × 3 subgoals each) with subgoal labels and 183 dual-coded diagrams. It runs as a Go backend serving a React + Next.js frontend, covering leagues, parent/teacher share links and graph visualisation. Transcripts export as CSV via the API.


What makes it different

  • You cannot advance until you have mastered the prerequisite. The checked DAG enforces this, if you cannot reliably add fractions with different denominators, the system will not show you mixed number addition.
  • Speed matters, not just accuracy. A correct answer that took 45 seconds on a concept with a 12-second threshold counts as weak mastery. You need to be both right and fast.
  • Nothing is forgotten. Concepts resurface automatically through FSRS-6 spaced repetition, with FIRe supplying implicit repetition credit. A concept mastered three weeks ago will reappear before it decays.
  • Problems are generated on demand. Every problem is produced by a parameterised Go generator, with a stored fallback and a replay layer so a session never stalls. The same concept gives you a different problem every time, so there is nothing to memorise.
  • Weekly leagues and shareable progress. Bronze → Diamond leagues promote the top 2 each Monday, and any student can generate a read-only share link (Settings → Share) for a parent or teacher. Pauses, accommodated timing and a 50 XP mastery-check quiz are built in.

Getting started

Try it

The hosted version is at mathua.com. No account is needed to start: guest progress stays in the browser until you create an account.

Build from source

git clone https://github.com/chuma-beep/mathua.git
cd mathua

go build -o bin/mathua ./cmd/mathua

# SQLite (zero-config, local)
./bin/mathua --serve --port 8080
# Or with DATABASE_URL explicitly
DATABASE_URL=sqlite:mathua.db ./bin/mathua --serve --port 8080
# Postgres for multi-user (via pgx/v5, implemented internal/storage/postgres.go:7)
DATABASE_URL=postgres://user:pass@host/mathua ./bin/mathua --serve --port 8080
# Or copy env file first
cp .env.example .env  # edit JWT_SECRET / CORS_ALLOWED_ORIGINS if needed

Create the first owner

Every account is a learner until an administrator promotes it. Roles are owner, admin and moderator; owner is the top role and the only one that can grant another owner. Sign up through the app first.

./bin/mathua admin promote you@example.com

Run this on the machine that holds the database. The command needs no flag, no token and no env var. Do not add a role field to a signup request. A client cannot choose its own role.

The command refuses to create an account, and it grants owner, the first promotion must be able to create the rest. Everyone after that is added from /admin/contributors: an owner or admin issues an invitation bound to an email, and accepting it assigns the role. No deployment secret is involved, because a shared password cannot say which person used it.

One administrator can demote nobody, including themselves. Promote a second administrator first.

Requirements: Go 1.26+ (module targets go 1.26.6; CI/Docker build with 1.27). Python 3.11+ with sympy (pinned in grading/requirements.txt) grades symbolic/polynomial/expression/complex answers, required for those ~32% of concepts; the production Docker image installs it and fails the build if grading is unavailable. Runs without Python only for the pure-Go grading types. Node 24 builds the web app in web/next-app. .nvmrc pins the exact version.

Env: DATABASE_URL (sqlite:mathua.db default, or postgres:// for production via pgx postgres.go:21 / main.go:69), PORT (default 8080), JWT_SECRET (hex 32 bytes or raw ≥32 chars, required in production, else random per run and tokens invalidate on restart internal/auth/auth.go:45), CORS_ALLOWED_ORIGINS (comma-separated allowlist, empty = allow all dev; supports * wildcard suffix like https://*.preview.example.com for previews internal/server/server.go:32), On Fly: fly secrets set JWT_SECRET=$(openssl rand -hex 32) CORS_ALLOWED_ORIGINS=https://mathua.com,https://www.mathua.com. See .env.example.


How it works

The concept graph

All math knowledge in Mathua is a directed acyclic graph. Each node is an atomic concept, something small enough to fail independently. Each edge is a prerequisite relationship.

The graph contains 3015 concepts across 24 domains (3015 KP shard files × 3 = 9045 KPs). It is checked at build time for cycles and orphans (scripts/validate_graph.go), so the prerequisite relation is a DAG by construction, not by convention. The scheduler reads your progress and the graph structure to decide what to show next, it will never surface a concept whose prerequisites you have not mastered.

Mastery gating

Every concept advances on evidence, not one streak. The engine reads the last six attempts and scores accuracy, the difficulty each question was served at, the variety of problem instances and response time. A concept advances at an evidence score of 0.6 once at least six attempts support it. Speed still matters because time is one of the inputs, but a single miss no longer erases the whole run.

A concept moves through five states:

UNSEEN → LEARNING → PRACTICING → MASTERED → DECAYING

DECAYING means you mastered the concept but have not seen it in over 14 days. The scheduler treats decaying concepts as urgent, they appear before new material until you demonstrate you still know them.

The scheduler

priority = 0.5×days_since_last_seen + 0.2×(1-mastery) + 0.3×weakness
         + 5  if DECAYING
         + 2  if encompasses a weak prerequisite (layering)
         − 3  if sharing an InterferenceGroup with recent practice
interleaving: no two consecutive questions share a subdomain
top-3 dissimilar candidates → 70/30 new/review balance

Three hard rules apply: never surface new material whose prerequisites are not mastered, never show the same concept twice in a row, maintain roughly 70% new/practicing and 30% review. Reviews of mastered concepts bypass the prerequisite gate, because retention is not acquisition.

Spaced repetition

When a concept reaches MASTERED, Mathua schedules its next review with FSRS-6, the 21-parameter long-term memory model, pinned to the reference implementation's defaults (fsrs==6.3.2) and a 0.90 retention target. Each review updates the concept's stability and difficulty rather than a single ease factor, and a lapse brings the concept straight back. SM-2 survives only as the migration seed for concepts whose history predates FSRS.

FIRe supplies the repetition side: work on an encompassing concept can bank implicit repetition credit for a dependent concept, and that credit can advance its review schedule without a dedicated card. The ledger is reconstructable exactly and is separate from mastery evidence, XP and diagnostics.

Reviews are woven into normal sessions; every 50 XP a mastery-check quiz surfaces at 80% difficulty. Diagnostic reports include a frontier placement, gaps by domain and completion estimates for accreditation.


Content

Domain Concepts
Arithmetic 120
Fractions 120
Pre-Algebra 120
Algebra 171
Geometry 120
Trigonometry 120
Optimization 200
Precalculus 120
Calculus I 120
Calculus II 120
Calculus III 120
Statistics 120
Linear Algebra 120
Discrete Math 120
Complex Numbers 121
Number Theory 121
Differential Equations 120
Abstract Algebra 120
Machine Learning 120
Topology 122
Graph Theory 120
Probability Theory 120
Numerical Analysis 120
Real Analysis 120
Total 3015

Architecture

Mathua is a Go backend with one delivery method: it serves the React + Next.js frontend as a static export and exposes a single REST API to the engine.

Web (React + Next.js) ═══ REST API ═══ Core Engine ── Grading ── Storage

The five-layer architecture, UI, API, Core Engine, Grading, Storage, is fully documented at docs/architecture.md and in the interactive web docs with React Flow diagrams and pre-rendered D2 SVGs.


Courses and transcripts

29 courses from 4th grade to university are wired through the DAG, including Calculus I/II, Linear Algebra, Discrete Math I/II, Probability & Statistics, Differential Equations, Abstract Algebra I/II, Topology and Machine Learning. Each course shows mastered/total, percent and an estimate of days remaining at your daily XP goal. Transcripts export as CSV via GET /api/transcript?format=csv and the read-only share link (Settings → Share) lets a parent or teacher follow along.

Contributing

The most impactful contributions are new concepts and improved generators. Adding a concept requires exactly three things: a JSON entry in the concept graph, a Go generator function and a fuzz test. Adding a lesson shard requires exactly 3 KPs per concept (data/lessons/kp/<id>.json) with verified section refs. See CONTRIBUTING.md for the quick-start guide and the full contributing docs for the detailed walkthrough with code examples and field schemas.

If Mathua is useful to you, a star on GitHub helps other learners find it: github.com/chuma-beep/mathua.


Running tests

# All tests
go test ./...

# Validate the concept graph (no cycles, no orphans)
go run scripts/validate_graph.go
python3 scripts/audit_lessons.py  # lessons + KP shards + diagrams + course targets (3015 files ×3 =9045 KPs)
python3 scripts/counts.py --check # docs counts match the data (run --write after a content wave)

# Generator fuzz, 1000 local (make fuzz), 100 lightweight in CI (.github/workflows/ci.yml:27)
go test ./internal/generator/... -run TestFuzz -count 1000  # local full; CI runs -count 100 for speed

Self-hosting

# Build for Linux
GOOS=linux GOARCH=amd64 go build -o mathua ./cmd/mathua

# Run (SQLite, local)
./mathua --serve --port 8080
# Or Postgres for production (implemented via pgx internal/storage/postgres.go:7)
DATABASE_URL=postgres://user:pass@host/mathua PORT=8080 ./mathua --serve

# Or with Docker Compose (SQLite default, Postgres supported via DATABASE_URL)
docker compose up
# Or with env file
cp .env.example .env && docker compose up

The server is available at http://localhost:8080. A Dockerfile and docker-compose.yml are included in the repo. For production SQLite backups to Cloudflare R2, see docs/backups.md.

Repairing grading data

If a grader fault or parser gap recorded correct answers as misses, re-grade the persisted attempts and rebuild the affected progress:

./mathua -repair-grading-dry-run   # report what would change (writes nothing)
./mathua -repair-grading           # flip false negatives + rebuild progress

It re-grades every incorrect attempt with the canonical grader (Engine.GradeAnswer), flips those that now grade correct, and replays each affected concept's history into concept_progress. Attempts the grader cannot decide are left untouched, and XP is not rewritten. Requires Python + SymPy (see above) for the symbolic/expression types.


Acknowledgements

Mathua's sequencing philosophy is directly inspired by Math Academy, a commercial product that demonstrated what mastery-gated, dependency-aware math learning can achieve. Mathua uses none of their content or code, it is an independent open implementation of similar ideas, built openly.

Lesson content and diagrams are adapted from OpenStax textbooks (Prealgebra, Precalculus 2e and Calculus Volume 1), used under CC BY-NC-SA 4.0, and from Algebrica by Antonio Lupetti, used under CC BY-NC 4.0. Algebrica provides a free, ad-free university-level mathematics knowledge base. Both licenses carry the NonCommercial term, so Mathua's MIT license does not extend to the adapted lesson content.

MIT OpenCourseWare (curriculum structure) and Art of Problem Solving (problem quality) were consulted as references; no content is taken from either.

Profile characters served by DiceBear (individual avatar styles carry their own licenses, see their license overview).

Mathematical answers are entered through MathLive (MIT), used as published, not forked. See docs/math-input.md for how an answer reaches a verdict, docs/mobile-device-checklist.md for what still needs a real phone and THIRD_PARTY_NOTICES.md for license obligations.


MIT License

About

Open-source adaptive math learning engine: 3,015 concepts, generated problems, mastery gating and FSRS spaced review. Go + Next.js, self-hostable.

Topics

Resources

Contributing

Stars

417 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages