MathForge is developed as a local-first math question-bank workbench. Changes should preserve the existing FastAPI + React + SQLite architecture and avoid pulling personal data or generated local artifacts into Git.
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
cd apps\web
npm install
cd ..\..Optional OCR engines such as MinerU, PaddleOCR, Pix2Text, Marker, olmOCR, and Qwen-VL are local dependencies. Install them only when working on that specific adapter or verification path.
Run the focused checks before submitting broad changes:
$env:PYTHONPATH="src$([IO.Path]::PathSeparator)."
.\.venv\Scripts\python.exe -m unittest discover -s tests -t .
cd apps\web
npm run build
cd ..\..For frontend behavior changes, also run the relevant Playwright suite from
apps/web.
- Keep changes scoped to the feature or fix being worked on.
- Do not commit personal PDFs, SQLite databases, OCR outputs, runtime caches, or generated release work directories.
- Document honest boundaries for optional model integrations and cloud/template placeholders.
- Prefer existing interfaces and tests before adding new abstractions.