AmMath

AmMath is a mobile-first learning MVP. Version 1 focuses on π and teaches problems step by step with deterministic math, longer explanations, and a visual on every step. The architecture is intentionally domain-based so future releases can add algebra, fractions, percentages, and other math domains.

Mobile-first, by design

Most students don't sit down at a desktop to do their math homework — they pull out a phone. Every screen, spacing decision, and touch target in AmMath is built and tested for small screens first (down to a 375px-wide phone), and the layout scales up from there. A dedicated desktop-optimized experience is planned but not yet built, so right now the app will run on desktop browsers, but it is tuned for mobile.

What it looks like

What is fixed in this rebuild

• npm run dev builds the math engine first, then watches the engine, API, and web app together.
• Native CSS is split into maintainable token, base, and app files. It uses CSS custom properties, nesting-ready modern architecture, color-mix, container-friendly layouts, dark mode, reduced-motion support, and six accent themes.
• The π engine now handles basic π expressions such as 5π, five pi, π × 7, circle area/circumference and reverse problems, wheel rotations, arc length, sector area, cylinder volume, and sphere volume.
• Explanations are intentionally longer and explain both what to do and why.
• Every supported solution step includes a visual definition.
• Unsupported questions are still saved to MongoDB so the solver backlog grows from real student questions.
• Automated acceptance tests include What is five pi?.

Requirements

• Node.js 22 LTS recommended (Node 24 may work, but LTS is the production recommendation)
• npm 10+
• MongoDB 7+ locally or MongoDB Atlas

Install

npm install

Copy the API environment example:

Windows Git Bash

cp apps/api/.env.example apps/api/.env

Edit apps/api/.env if your MongoDB connection is different. The default local URI is mongodb://127.0.0.1:27017/ammath. Replace the JWT secret before deployment.

Start development

From the repository root:

npm run dev

The first run automatically compiles @mathworks/math-engine. You should not manually create dist/.

• Web: http://localhost:5173
• API: http://localhost:4000
• Health: http://localhost:4000/api/health

Setting up the web app on its own

If you only want to run or deploy the React client (apps/web), without touching the API or engine:

1. Install dependencies once from the repository root (the web app depends on the local @mathworks/math-engine workspace package):

   npm install

2. The web app talks to the API through the VITE_API_URL environment variable. It defaults to http://localhost:4000/api when unset, which is correct for local development against the API in this repo. For a deployed API, create apps/web/.env with:

   VITE_API_URL=https://your-api-domain.example.com/api

3. Run just the web app:

   npm run dev -w @mathworks/web

4. Build a static production bundle (this is what you would publish to GitHub Pages or any static host):

   npm run build -w @mathworks/web

   The output is written to apps/web/dist. Since the API is a separate Node/Express service, it must be hosted somewhere that can run Node (GitHub Pages only serves static files), and VITE_API_URL must point at that hosted API before you build.
5. Preview the production build locally:

   npm run preview -w @mathworks/web

Test the solver

npm test

The acceptance suite checks multiple categories and requires each teaching step to contain a substantial explanation, a reason, and a visual.

Production build

npm run build

First-use flow

1. Register a student account.
2. Choose an accent theme in Settings. Pink is the visual design target, but Blue, Green, Purple, Red, and Black are included.
3. Choose System, Light, or Dark appearance.
4. Enter a π question on Solve.
5. Work through each explanation and visual.
6. Problems are saved to MongoDB immediately.
7. After the guided-question threshold, the practice flow asks the student to solve one independently.
8. History and Progress persist on the account.

There is no default administrator account in this MVP.

Architecture

apps/
  api/          Express + TypeScript + MongoDB
  web/          React + TypeScript + Vite
packages/
  math-engine/  deterministic π parsing, solving, lesson steps, visuals

The math engine is independent from React, Express, and MongoDB. Future domains should be added to the engine as domain modules rather than hardcoded into UI pages.

Data philosophy

MongoDB stores student accounts, submitted questions, generated solutions, attempts, progression, and unsupported questions. Mathematical correctness does not depend on finding a canned answer in MongoDB. The deterministic engine derives solutions from formulas and relationships.

Important MVP boundary

This is a substantially broader π MVP, but it is not a symbolic computer algebra system. If the engine cannot confidently classify a question, it saves the question and returns a safe unsupported response rather than inventing an answer. AI interpretation can be added later behind a provider interface without replacing deterministic calculation.

Looking for developers

Right now AmMath only teaches π, and that's just the starting point, not the goal. I'd like this to grow into a place where a student can get the same patient, step-by-step treatment for fractions, algebra, percentages, geometry, and more. That's a lot more ground than one person can cover alone.

If you care about math education, enjoy building clean deterministic solvers, or just want to help kids get unstuck on their homework, I'd genuinely love the help. The domain-based architecture in packages/math-engine was built specifically so a new math domain can be added without touching the UI or rewriting what already works. Open an issue, start a discussion, or send a pull request — even small contributions (a new problem type, an explanation improvement, an accessibility fix) are welcome.

---

Made with ❤️ by Riad Kilani for Amma.