Lightweight web app that accepts a MakerWorld model URL, scrapes the project BOM, and generates an editable hardware table with McMaster-Carr search links.
# Python environment
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,playwright]"
playwright install chromium # one-time, for MakerWorld scraping
# Frontend
cd frontend && npm install && cd ..
# Run all dev services (API + Vite + JupyterLab)
./scripts/dev.sh- App: http://localhost:5173
- API: http://localhost:8000/api/health
- JupyterLab: http://localhost:5173/jupyter/lab/tree/notebooks
Optional: ./scripts/dev.sh --debug for verbose logging and the in-app debug panel.
./scripts/cleanup.sh # caches and build output (keeps venv + node_modules)
./scripts/uninstall.sh --yes # full local uninstallSee Development guide — Cleanup and uninstall for options (--deep, --with-playwright, --dry-run).
- Prototype logic in
notebooks/(same pipeline code as the API — see docs/notebooks.md) - Promote stable code into
backend/services/ - Expose via FastAPI routers
- Connect frontend screens
| Layer | Tools |
|---|---|
| Backend | FastAPI, Pydantic, httpx, Playwright (optional), BeautifulSoup, pandas |
| Frontend | React, shadcn/ui, Tailwind CSS, TanStack Table |
| Dev | JupyterLab, pytest |
notebooks/ Pipeline development notebooks (shared entry points with API)
backend/ FastAPI app, services, models, routers, rate limiting
frontend/ React UI
tests/ pytest suite (unit + optional live integration)
data/ McMaster routing JSON, taxonomy crawl output — see data/README.md
docs/ Documentation (start at docs/README.md)
.github/ CI: tests on push/PR; monthly McMaster taxonomy crawl
Full documentation lives in docs/:
- Architecture — system overview, pipeline, rate limiting
- API reference — HTTP endpoints (import, BOM, feedback, pricing sync)
- Backend services — scraper, parser, matcher, pipeline
- McMaster taxonomy — category data + monthly crawl
- Security — threat model and deployment checklist
- Development guide — setup, env vars, debug mode
- Data files — routing JSON reference
- Execution plan — phased delivery status and backlog