Flipcommons
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/djadmin/ - 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/,/djadmin/,/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 grant yourself Django admin access, sign in to the local site at http://localhost:5173 (which routes through WorkOS), then promote your account:
cd backend && uv run python manage.py grant_admin [email protected]
The admin password form is disabled — WorkOS is the only login surface — so createsuperuser produces a row that can never sign in.
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 pytest (backend) + vitest (frontend) |
make lint |
Run ruff (backend) + eslint/prettier (frontend) |
make mypy |
Run backend type checks |
make quality |
Lint + regenerate API types + svelte-check |
make api-gen |
Regenerate frontend API types from the backend schema |
make pull-ingest |
Download catalog data from R2 |
make ingest |
Run full ingestion 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/
Full Documentation
See docs/README.md for the full documentation index
Pull Requests
See CONTRIBUTING.md for the PR workflow.
