A web-first Commander/EDH deckbuilder with a shared core for CLI, headless, and Docker workflows. It builds curated decks, enforces bracket policies, understands owned cards, and ships a modern FastAPI + HTMX UI.
- **Web UI priority**: All homepage actions map to the sections below.
- **Shared logic**: Web, CLI, and headless runs use the same builder engine and exports.
- **Deterministic outputs**: Random modes respect seeds, include/exclude lists, and bracket rules.
- **Data-aware UX**: Owned library, themes, commanders, diagnostics, and logs live side-by-side.
---
## Table of contents
- [Quick start](#quick-start)
- [Homepage guide](#homepage-guide)
- [Build a Deck](#build-a-deck)
- [Run a JSON Config](#run-a-json-config)
- [Initial Setup](#initial-setup)
- [Owned Library](#owned-library)
- [Browse Commanders](#browse-commanders)
- [Browse Themes](#browse-themes)
- [Finished Decks](#finished-decks)
- [Random Build](#random-build)
- [Diagnostics](#diagnostics)
- [View Logs](#view-logs)
- [CLI & headless flows](#cli--headless-flows)
- [Data, exports, and volumes](#data-exports-and-volumes)
- [Environment variables](#environment-variables)
- [Project layout](#project-layout)
- [Development setup](#development-setup)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [License & attribution](#license--attribution)
- [Further reading](#further-reading)
---
## Quick start
Pick the path that fits your setup. All commands target Windows PowerShell.
### Option 1 — Docker Compose (recommended web experience)
```powershell
docker compose up --build --no-deps -d web
```
The Web UI starts on http://localhost:8080. First boot seeds data, refreshes decks, and tags cards automatically (see env defaults in `docker-compose.yml`). Use `docker compose stop web` / `docker compose start web` to pause or resume.
### Option 2 — Docker Hub image
```powershell
docker run --rm -p 8080:8080 `
-v "${PWD}/deck_files:/app/deck_files" `
-v "${PWD}/logs:/app/logs" `
-v "${PWD}/csv_files:/app/csv_files" `
-v "${PWD}/config:/app/config" `
-v "${PWD}/owned_cards:/app/owned_cards" `
mwisnowski/mtg-python-deckbuilder:latest
```
Brings up the same web UI using the prebuilt image. All volumes persist on the host.
| `CARD_INDEX_EXTRA_CSV` | _(blank)_ | Inject extra CSV data into the card index. |
Refer to `.env.example` for advanced editorial, taxonomy, and experimentation knobs (`EDITORIAL_*`, `SPLASH_ADAPTIVE`, `WEB_THEME_FILTER_PREWARM`, etc.). Document any newly introduced variables in the README, DOCKER guide, compose files, and `.env.example`.
---
## Project layout
```
code/ FastAPI app, deckbuilding engine, CLI, scripts, and tests
├─ web/ Web UI (FastAPI + Jinja2 + HTMX)
├─ deck_builder/ Core builder logic and services
├─ tagging/ Tag pipelines and utilities
├─ locks/ Card locking utilities
├─ scripts/ Maintenance and editorial tools
├─ tests/ Pytest suite (web, CLI, random, tagging)
Use `tasks.json` entries such as `pytest-fast-random` or `pytest-fast-locks` for quick feedback.
5. Linting and type checks follow `pyproject.toml` / `mypy.ini` defaults. Keep changes minimal and well-typed.
When adding features, favor the web UI first, keep public builder APIs stable, and update documentation (CHANGELOG → RELEASE_NOTES_TEMPLATE → DOCKER → README) in that order.
---
## Troubleshooting
- **Blank page after start**: Visit `/healthz`, check `/logs`, ensure `SHOW_LOGS=1`, and inspect host `logs/` for stack traces.
- **Stale data**: Run Initial Setup or delete `csv_files/.tagging_complete.json` to force reseeding.
- **Owned-only build fails**: Confirm owned files were uploaded correctly and that `owned_cards/` is mounted.
- **Random build stalls**: Lower `RANDOM_MAX_ATTEMPTS`, increase `RANDOM_TIMEOUT_MS`, and verify selected themes exist via `/themes/`.
- **Commander list outdated**: Rerun the commander refresh script or Initial Setup.
---
## Contributing
Pull requests are welcome—follow the conventional commit style, keep diffs focused, add or update tests when behavior changes, and document new env vars or workflows. Review `CONTRIBUTING_EDITORIAL.md` for editorial tooling guidance.
---
## License & attribution
Licensed under the [MIT License](LICENSE). Card data and imagery are provided by [Scryfall](https://scryfall.com); please respect their [API terms](https://scryfall.com/docs/api).
---
## Further reading
- [Web UI deep dive](docs/web_ui_deep_dive.md) – advanced Stage 5 tooling, multi-copy packages, virtualization tips, and diagnostics overlays.
- [Theme catalog advanced guide](docs/theme_catalog_advanced.md) – API endpoints, governance policies, editorial tooling, and validation scripts.
