Commander Spellbook Backend — Developer Docs
Welcome. This is the developer documentation for the Commander Spellbook Backend, the engine and REST API behind commanderspellbook.com — a combo database, wiki, and search engine for Magic: The Gathering.
These pages are for contributors. If you read them top to bottom you should be able to set up the project, understand how it fits together, and open your first pull request. They complement (not replace) the root README and CONTRIBUTING.md.
What this project does
Editors describe combos (small interactions between Magic cards that produce an effect). The backend then automatically generates every concrete card combination — a variant — that achieves a result, by walking a graph of cards, features, and combos. Those variants are served through a REST API that the React frontend, the chat bots, and third-party tools consume.
The heart of the project is therefore not CRUD — it is the variant generation engine.
The stack at a glance
| Component | Technology | Role |
|---|---|---|
| Database | PostgreSQL (SQLite for local dev) | Stores cards, combos, features, generated variants |
| Backend | Django + Django REST Framework | Domain model, admin panel, REST API, variant engine |
| Worker | django-tasks (db_worker) |
Runs long jobs: variant generation, Scryfall card sync |
| Clients | Generated from OpenAPI | Python & TypeScript SDKs published to PyPI / npm |
| Bots | Discord, Reddit, Telegram | Standalone services that consume the API via the Python client |
| Frontend | React (separate repo) | The website; not in this repository |
Documentation map
Start here and follow the order:
- Getting Started — install dependencies, run the stack, run the tests and the linter.
- Architecture — the repository layout and how the pieces (backend project,
spellbookapp,websiteapp,common, clients, bots) connect. - Domain Model — Cards, Features, Combos, Templates, Variants, and Suggestions: the vocabulary everything else is built on.
- Variant Generation — the combo graph and the algorithm that turns editor-authored combos into concrete variants.
- API & Clients — the REST endpoints, authentication, the OpenAPI schema, and the generated SDKs.
- Git Flow & Versioning — branching, semantic versioning, and how a release ships.
Reference material:
- uv Vademecum — the dependency and environment workflow: the projects, lockfiles, dependency groups, and how versions are derived.
- The Minimal Set of Multisets ADT — the data structure behind the engine's minimality pruning.
Getting help
Ask on the Commander Spellbook Discord — the #website channel is the best place for backend questions. Maintainers are happy to help you get started.