Flipcommons
The Flip pinball museum's interactive, collaborative pinball database website
Flipcommons
This is the source code for Flipcommons, an interactive, collaborative database of pinball knowledge.
It's sponsored and hosted by The Flip, Chicago's playable pinball museum.
Architecture
This is a Django + SvelteKit monorepo. SvelteKit handles the user-facing frontend. Django owns the backend: the database data model, APIs, and it also serves Django's admin UI.
- Backend: Django + Django Ninja API at
/api/, admin at/admin/ - Frontend: SvelteKit with Node SSR for public routes and CSR-only authenticated app routes
- Auth: Session-based, same-origin (no JWT, no CORS)
- Dev proxy: Vite proxies
/api/,/admin/,/media/, and/static/to Django - Production routing: Caddy fronts SvelteKit SSR and Django inside one Railway service
Getting started
Requirements: Python 3.14+, Node 24+, uv, pnpm (or enable via corepack enable)
cp .env.example .env
make bootstrap
make dev
Then open http://localhost:5173
To create a Django admin superuser:
cd backend && uv run python manage.py createsuperuser
Commands
| Command | What it does |
|---|---|
make bootstrap |
Install all deps, run migrations, generate API types |
make dev |
Start Django + SvelteKit dev servers |
make test |
Run backend (pytest) + frontend (vitest) tests |
make lint |
Run ruff (backend) + eslint/prettier (frontend) |
make quality |
Lint + type check (svelte-check) |
make api-gen |
Export OpenAPI schema and regenerate TypeScript types |
make pull-ingest |
Download ingest source data |
make ingest |
Run the ingest pipeline |
make agent-docs |
Regenerate CLAUDE.md and AGENTS.md from docs/AGENTS.src.md |
Project Structure
backend/ Django project (uv, pyproject.toml)
frontend/ SvelteKit project (pnpm, package.json)
scripts/ POSIX shell scripts for bootstrap, dev, test, lint
docs/ Product, architecture, development, and operations docs
Makefile Thin wrappers around scripts/
Further Reading
- docs/Overview.md
- docs/Architecture.md
- docs/WebArchitecture.md
- docs/AppBoundaries.md
- docs/DomainModel.md
- docs/Provenance.md
- docs/Ingest.md
- docs/Development.md
- docs/Hosting.md
Contributing
See CONTRIBUTING.md for the PR workflow.
AI Agent Docs
CLAUDE.md and AGENTS.md are generated from docs/AGENTS.src.md. Never edit them directly — edit the source and run make agent-docs.
