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.
- 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.
The hosted version is at mathua.com. No account is needed to start: guest progress stays in the browser until you create an account.
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 neededEvery 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.comRun 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+ withsympy(pinned ingrading/requirements.txt) gradessymbolic/polynomial/expression/complexanswers, 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 inweb/next-app..nvmrcpins the exact version.Env:
DATABASE_URL(sqlite:mathua.dbdefault, orpostgres://for production viapgxpostgres.go:21/main.go:69),PORT(default8080),JWT_SECRET(hex 32 bytes or raw ≥32 chars, required in production, else random per run and tokens invalidate on restartinternal/auth/auth.go:45),CORS_ALLOWED_ORIGINS(comma-separated allowlist, empty = allow all dev; supports*wildcard suffix likehttps://*.preview.example.comfor previewsinternal/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.
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.
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.
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.
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.
| 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 |
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.
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.
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.
# 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# 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 upThe 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.
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 progressIt 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.
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
