Aleph

A personal workspace for competition mathematics.

Explore problems. Build practice sets. Track what you learn.

简体中文 · Quick start · Problem bank · Contributing

Aleph is a browser-based math training app built with React and TypeScript. It brings 4,644 problems from AIME, HMMT, BMT, and SMT into a searchable workspace with mathematical notation, solutions, custom practice sets, and progress tracking.

The app runs entirely in the browser. No account, backend, database service, or API key is required. Your progress stays in your browser's local storage.

Features

• Browse and search — filter by mathematical domain, contest, difficulty, topic tag, and solved or starred status. Search statements, IDs, years, rounds, and tags.
• Read math comfortably — KaTeX renders formulas in problem statements and expandable solutions.
• Build practice sets — sample unsolved problems by domain, contest, size, and a difficulty mix. Reopen your 20 most recent generated sets.
• Check numerical answers — submit numbers, fractions, or supported expressions such as sqrt(2) and pi/2 when a stored answer is available. Training mode allows three attempts per problem visit.
• Keep a personal record — mark problems as solved, save favorites, and rate their difficulty and elegance.
• See your progress — review solved counts, domain progress, contest and difficulty charts, a six-month activity heatmap, and a daily challenge.
• Practice offline — the production build includes an installable PWA and caches the app and problem bank after a successful initial online load.

Quick start

Use Node.js 22.12 or newer and npm. Python is only needed for the optional data-maintenance scripts.

git clone https://github.com/Mars723/Aleph.git
cd Aleph
npm ci
npm run dev

Open the local URL printed by Vite, usually http://localhost:5173.

Commands

Command	Purpose
npm run dev	Start the development server with hot reload
npm run build	Check TypeScript and build the app into dist/
npm run preview	Serve the production build locally
npm run lint	Run the existing ESLint checks

Current validation status: the production build passes. The existing ESLint configuration reports 15 errors in the application code, including React Hooks rules, explicit any types, and prefer-const; lint is not currently a passing check.

To try the production build and offline behavior:

npm run build
npm run preview

Load the app online first and allow the service worker to finish caching. PWA installation requires a supported browser and HTTPS, or localhost during development. The problem JSON alone is about 7.6 MB, so the initial cache download is larger than the application shell.

Problem bank

The checked-in public/problems.json contains 4,644 unique problem IDs, with year labels spanning 1983–2026. These counts describe the included collection; they do not imply complete contest archives.

Contest	Problems
AIME	1,027
HMMT	1,711
BMT	1,020
SMT	886
Total	4,644

Domain	Problems
Algebra	985
Geometry	1,133
Number Theory	858
Probability	586
Combinatorics	793
Calculus	242
Integration Bee	47

1,111 entries currently have a nonempty stored answer. The answer input is shown only for those entries. Checking compares numerical values; it is not a symbolic algebra engine or a proof checker. Unsupported expressions and incomplete or incorrect data can produce an incorrect result. You can also mark a problem as solved manually.

Data format

The app loads public/problems.json as an array of records matching src/types.ts:

interface Problem {
  id: string;
  source: string;
  year: number;
  round: string;
  number: number;
  statement: string;
  solution: string;
  difficulty: "Easy" | "Medium" | "Hard" | string;
  domain: string;
  tags: string[];
  answer?: string | null;
}

Statements and solutions support LaTeX delimiters, including $...$ and $$...$$. Keep problem IDs stable: saved progress and training history refer to those IDs.

The collection includes AI-assisted answer extraction and solution-repair artifacts. Review mathematical content against the original contest material before relying on it or contributing a correction.

Stack and structure

React 19 · TypeScript · Vite 7 · React Router · KaTeX · Recharts · Lucide · vite-plugin-pwa

src/
  pages/                 Dashboard, library, problem view, training, credits
  components/            Navigation, math rendering, and ratings
  context/               Shared problem-bank loading
  hooks/                 Browser-local progress storage
  utils/                 Numerical answer parsing and comparison
  types.ts               Problem schema
public/
  problems.json          Runtime problem bank
  pwa-icon-*.png          App icons
Final_Problem_Json/       Source collections and data-repair artifacts
scripts/                 Data maintenance and service-worker utilities
vite.config.ts           Development, build, and PWA configuration

Data-maintenance scripts

The Python scripts in scripts/ are historical utilities for merging collections, extracting answers, and applying repairs. They currently target src/data/problems.json, while the app reads public/problems.json. They are not part of the normal build. Review their paths and output before using them; rerunning a merge can replace later answer or solution repairs.

PWA generation is already handled by vite-plugin-pwa during npm run build; the separate scripts/generate-sw.js utility is not needed for the standard build.

Storage and deployment

• Progress, ratings, and favorites use the aleph_user_progress local-storage key. Training history uses aleph_training_history.
• There is no built-in account sync or backup. Clearing site data, switching browser profiles, or changing the app's origin can make previous progress unavailable.
• Deploy the generated dist/ folder to a static host with HTTPS. The app uses hash-based routes.
• The current configuration assumes deployment at the domain root: the data request is /problems.json and the PWA start URL is /. Hosting under a subdirectory, such as a GitHub Pages project URL, needs coordinated changes to the Vite base, data URL, and PWA paths.

Contributing

Bug reports, accessibility improvements, UI refinements, and verified problem corrections are welcome. Please see CONTRIBUTING.md.

For a data issue, include the problem ID, the observed error, a proposed correction, and a reference to the original contest material. Preserve source attribution and only contribute content you have permission to share.

License and attribution

Original application code and project documentation are available under the MIT License.

Competition problems, solutions, and third-party material are excluded from that license. Their rights remain with their respective owners; inclusion in this repository does not grant an additional license to those materials. See THIRD_PARTY_NOTICES.md for the scope and source organizations.

Aleph is an independent project and is not affiliated with or endorsed by the listed competitions.