MTG Deck Builder

Full-stack deck-construction app with a first-principles simulator + optimizer that produces tournament-grade decks for all five major formats. FastAPI backend, Next.js frontend, structured DeckRationale output narrated by an optional LLM coach.

Current state: 486 backend tests passing, frontend TypeScript clean (next build green), end-to-end optimizer flow live behind a feature flag, multi-format meta + deck-evaluation engine + embedding retrieval wired.

Structure

• api/: FastAPI backend, simulator kernel, optimizer, critic loop
• web/: Next.js frontend
• packages/shared/: shared product/domain documentation
• infra/: local infrastructure notes
• .claude/skills/: versioned LLM system prompts (card-evaluator, deck-critic, builder-responder, goldfish-coach)

Local Development

Backend

cd api
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m app.scripts.seed_sample_cards
python -m app.scripts.ingest_tournament_decks
python -m app.scripts.build_archetypes
python -m app.scripts.build_card_profiles      # every card; --modern-only to opt out
uvicorn app.main:app --reload

Frontend

cd web
npm install
API_BASE=http://127.0.0.1:8000 MTG_API_KEY=<same key as the API, if set> npm run dev

The browser never talks to the API directly: web/src/app/api/backend/[...path] is a server-side proxy that forwards /v1/* and /api/* calls to API_BASE and adds X-API-Key from the web server's MTG_API_KEY, so the key never ships in the JS bundle. Run the API with MTG_TRUST_FORWARDED=1 behind it so rate limits stay per client.

Tests

cd api
python -m pytest -q     # 486 tests, about 30 s, no skips

Tests always run against api/tests/fixtures/cards.db.gz: a deterministic cut of about 2k cards from the full Scryfall ingest, plus the full archetype and tournament corpus. conftest.py decompresses it into a temp dir per run, so local runs and CI see the same data and never write to var/.

• Rebuild it after re-ingesting, or when a test needs a card the fixture lacks. Naming the card in the test is enough: python -m app.scripts.build_test_fixture.
• Run against the full local DB instead with MTG_TEST_DATABASE_URL=sqlite:///../var/mtg_deck_builder.db python -m pytest.

CI

.github/workflows/ci.yml runs on every push to main and every PR: the backend pytest suite and the frontend unit tests, tsc --noEmit, lint, and next build.

Deploy

The web app deploys to Vercel and the API to one Fly.io machine, with SQLite on a volume (about $6/month). docs/DEPLOY.md has the setup steps, secrets, the weekly card-refresh workflow and spend caps.

Analytics

Traffic and the deck funnel are recorded with Vercel Web Analytics (@vercel/analytics). The script is in the root layout. Nothing is stored until Web Analytics is enabled for the Vercel project, and no environment variable is required.

1. Open the mtg-deck-builder project in the Vercel dashboard.
2. Go to the Analytics tab and click Enable.
3. Deploy this change to production if it is not already live. Preview deployments report into the Preview environment; production reports into Production.

Page views, including guide pages, are collected on the Hobby plan (50,000 events per month, then collection pauses). Custom events require Pro. On Hobby, Vercel does not record them, so the funnel stays empty until the team is on Pro. On Pro, each custom event can carry two properties. Web Analytics Plus ($10/month) raises that to eight, which this site does not need.

Event	When it fires	Properties
deck_generated	A deck build succeeds	format, source (new or alternative)
deck_refined	A refine succeeds	format
deck_exported	An Arena, Moxfield, or Archidekt export is built	target, format
deck_shared	A share link is created	format
tcgplayer_cart_clicked	"Buy entire deck on TCGplayer" is clicked	format
guide_viewed	A guide article is opened	slug, category

format is one of standard, modern, pioneer, legacy, commander. target is arena, moxfield, or archidekt. Plain-text and CSV exports are not part of the funnel. Prompts, deck titles, card lists, emails, and share tokens are rejected before send. Page-view URLs have the brief and deck query parameters removed, so a guide's "try this" link and a share link do not land in analytics. /privacy describes the same limits.

Capabilities

Legacy heuristic path (default)

• /v1/decks/generate — rules-based deck assembly using archetype templates
• /v1/decks/refine, /v1/decks/analyze, /v1/decks/validate — archetype-similarity analysis and rule checking

Optimizer pipeline (new)

• POST /v1/jobs/optimize — submit a constraint envelope (format, colors, budget, includes, excludes, archetype recipes)
• GET /v1/jobs/{id} — poll for completion
• POST /v1/jobs/{id}/prose — lazily produce LLM-narrated coach prose (202 while job is still running, 200 when ready, 404 if unknown)

To make the optimizer the default for /v1/decks/generate:

export MTG_USE_OPTIMIZER_DEFAULT=true

The wrapper returns the same DeckResponse shape and falls back to the legacy generator on any error so prod traffic isn't affected by a bad deploy. A fixture-database comparison is in qa/OPTIMIZER_COMPARISON.md. The default stays off until that comparison is re-run on the full card database and the optimizer clearly wins.

POST /v1/commander/precon-upgrade turns an official precon (or a pasted list) and a dollar budget into ranked one-for-one swaps, a Commander legality check, a bracket estimate, and a TCGplayer cart for the adds. GET /v1/commander/precons searches the precon catalog. The workshop's "Upgrade a precon" tab calls both.

Simulator architecture

Eleven independently-testable layers, all running headlessly without FastAPI/DB dependencies:

Layer	Module	Purpose
1	api/app/oracle/	Parse oracle text into typed CardProfile: cost vector, effect vector, role weights, combo primitives, alt-cost detection (Evoke/Suspend/Cascade/Delve/Channel/Flashback/Cycling)
2	api/app/sim/mana.py	Mana-base solver: closed-form hypergeometric (Karsten thresholds) + Monte Carlo for fetch/shock/MDFC/painland interactions
3	api/app/sim/goldfish.py	Solitaire turn-by-turn simulator with 4 pluggable policies (aggro/combo/control/midrange) → kill-turn distribution. Tron-assembly rule, ETB-tapped tracking
4	api/app/synergy/	Synergy graph: produces→requires edges, tutor→closer edges, 12 known combo cliques (Splinter Twin, Storm, Living End, Yawgmoth, Ad Nauseam, Hardened Scales, Devoted Druid, Goryo's, Thoracle, Scapeshift, Amulet Titan). Criticality scored via vanilla-replacement ∆kill-turn. Cached by deck identity + profile_version
5	api/app/optimizer/	Simulated annealing with targeted swap proposals (driven by worst fitness axis), constraint-repair branch, monotonic violation reduction, format-aware playset cap (4-of constructed, 1-of singleton)
6	api/app/workers/	Backend-agnostic async job queue. ThreadJobQueue (default, in-process) and CeleryJobQueue (Redis-backed, selectable via MTG_WORKER_BACKEND=celery). Result caching by hash
7	api/app/critic/

Frontend integration

The deck workshop (web/src/components/deck-workshop.tsx) shows the legacy generator's output by default. When a user clicks "Run optimizer," the workshop submits to /v1/jobs/optimize via the useDeckRationale hook, polls for completion, and renders DeckRationaleView with full sections: headline, why-this-wins, key turns, mulligan guide, matchup table, weakness callouts, critic transcript, and sideboard plan.

Skills (versioned LLM system prompts)

Under .claude/skills/. Used out-of-loop with results cached so generation stays fast and deterministic.

• card-evaluator — fallback parser for cards whose oracle text the deterministic parser can't fully cover (writes back to card_profiles)
• deck-critic — GPT-5.5 system prompt for the critic loop
• builder-responder — Claude system prompt for the builder side
• goldfish-coach — narrates structured DeckRationale into prose

Environment variables

Variable	Purpose	Default
DATABASE_URL	Postgres connection	sqlite:///var/mtg_deck_builder.db
CORS_ORIGINS	Allowed CORS origins	http://localhost:3000,http://127.0.0.1:3000
MTG_USE_OPTIMIZER_DEFAULT	Route /v1/decks/generate through optimizer	false
MTG_WORKER_BACKEND	thread or celery	thread
MTG_WORKER_THREADS	ThreadPoolExecutor size	4
REDIS_URL	Celery broker + result backend	redis://localhost:6379/0
ANTHROPIC_API_KEY	Builder client + coach prose	(unset → mocks)
OPENAI_API_KEY	Critic client	(unset → mocks)
MTG_BUILDER_MODEL	Override Claude model	claude-opus-4-7
MTG_CRITIC_MODEL	Override GPT model	gpt-5.5
MTG_COACH_MODEL	Override Haiku model for prose	claude-haiku-4-5-20251001
MTG_CRITIC_MAX_TOKENS_PER_CALL	Per-call output cap	4096
MTG_CRITIC_MAX_USD_PER_JOB	Per-job cost cap (shared across rounds)	1.50
OPENAI_EVAL_MODEL	Judge model for qa/run_eval.py	gpt-6-luna
MTG_COACH_DISABLE	Force-skip coach prose even with key set	(unset)
MTG_API_KEY	Comma-separated API keys; enables X-API-Key auth on optimize/prose/evaluate/save/precon-upgrade	(unset → auth off)
MTG_USE_PGVECTOR

Monetization

Monetized via TCGplayer affiliate links (the marketplace where players actually buy MTG singles). Surfaces:

• Card detail modal — a primary Buy on TCGplayer button (uses the card's own product link, falling back to a name search).
• Shop This Deck panel on every generated deck — a Buy entire deck on TCGplayer button that opens a single Mass Entry cart pre-filled with the whole list at the cheapest available sellers, plus per-card single links.
• Ask About This Deck chat panel under every generated deck (POST /v1/decks/chat, API-key gated like the other LLM endpoints). Questions get deck-specific answers; a message that asks for a change comes back with a proposed refinement and an Apply to deck button that runs it through the normal Refine flow (visible in the Refine box, undoable). The transcript is held client-side and resets when a different deck is generated. Needs ANTHROPIC_API_KEY on the API; without it the panel reports that chat is unavailable.

TCGplayer's program runs through Impact; once approved you get a deep-link prefix — set both variables above to it. Links are wrapped at the API read boundary (app/services/affiliate.py) and at build time on the frontend, so changing the prefix never requires re-ingesting card data. The required affiliate disclosure renders alongside every link surface.

Postgres data pipeline

cd api
createdb mtg_deck_builder
python -m app.scripts.seed_sample_cards
python -m app.scripts.ingest_scryfall              # full Scryfall ingest (optional)
python -m app.scripts.ingest_tournament_decks
python -m app.scripts.ingest_official_decks --download   # MTGJSON precons; see docs/DATA_SOURCES.md
python -m app.scripts.build_archetypes
python -m app.scripts.build_card_profiles          # every card; --modern-only to opt out
python -m app.scripts.build_card_embeddings        # dense embeddings → card_embeddings

Embeddings power the retriever's vector mode (works on SQLite too) and the pgvector <=> path on Postgres. The default embedder is a deterministic feature-hash projection (app/services/embeddings.py) so it runs offline; swap embed_features for a learned model without changing the table schema, ingest script, or retriever.

The optimizer reads from card_profiles when populated and falls back to on-the-fly profiling when it isn't (logs a warning).

Benchmarks pinned by tests

• Burn manabase — solver outputs 19–20 lands (matches published lists ±1)
• Murktide manabase — 19 lands, U sources hit T2 ≥ 85% / T4 ≥ 95%
• Burn goldfish — kill-turn 4.8–5.2 (community benchmark ~4.5–5)
• Aggro vs. dragon pile — fitness function ranks the curved Burn list above an off-curve 6-mana dragon stack
• Constraint monotonicity — optimizer never accepts a swap that adds violations; respects exclude-lists, color identity, and playset cap (4-of constructed, 1-of singleton)
• Self-play symmetry — Burn-vs-Burn matchup ≈ 50% with on-the-play alternation
• Matchup differentiation — Burn 71.8% avg vs the meta, Murktide loses to Burn 16% (fast-clock vs. tempo)
• Format coverage — Modern, Standard, Pioneer, Legacy, Commander all flag size/color/playset violations correctly
• Cross-format matchup correctness — Commander candidate vs Modern opponent applies each side's native mulligan profile
• Synergy cache hit — same deck → same SynergyGraph instance (avoids 9000 graph rebuilds per optimization)
• Goldfish per-turn ETB-tapped — taplands played T3 don't produce mana T3
• Tron assembly — Urza's Tower + Power Plant + Mine together produce 7 colorless mana
• Sideboard correctness — targets losing matchups, deduped, color-aware, empty for Commander
• Critic loop sanity — auto-downgrades critic-APPROVE when deterministic rubric flags errors; rolls back rounds that don't improve any metric
• LLM cost gating — shared budget across all critic-loop rounds enforces the per-job USD cap

Deck evaluation engine

The simulator now ships a multi-signal evaluation layer (api/app/sim/evaluation.py) that grades a concrete decklist beyond a single kill-turn number:

• Win rate + Wilson 95% confidence interval — so callers know when a delta is signal vs. noise.
• Flood / screw resistance — re-runs the deck with opening hands forced land-heavy and land-light.
• Interaction resilience — re-runs with a hypothetical opponent answering a fraction of spells (gated disruption_rate goldfish primitive).
• Inevitability — late-game win share + card-advantage density.
• Consistency — inverse of kill-turn variance.

Exposed at POST /v1/decks/evaluate and folded into the optimizer's fitness as the resilience + inevitability axes (computed on deep_eval=True, off in the hot anneal loop).

Newer endpoints

• POST /v1/decks/evaluate — run the evaluation battery on a decklist
• POST /v1/decks/diff — card-by-card before/after diff
• POST /v1/decks/save, GET /v1/decks/history, GET /v1/decks/saved/{id}, GET /v1/decks/shared/{token}, DELETE /v1/decks/saved/{id} — persistent history + sharing
• GET /v1/cards/{name}/similar — semantic-ish neighbours (pgvector fast-path, deterministic lexical fallback)

Optional API-key auth (MTG_API_KEY, X-API-Key header) gates every endpoint that spends LLM tokens or touches saved decks — generate, refine, analyze, chat, evaluate, optimize, prose, save/history — while validate, parse, export, diff, card/commander search, meta and shared-deck reads stay public behind a per-client rate limit. Saved decks store a hash of the key, and no response contains it.

What a generated deck carries (2026-10)

• constraints — the budget, includes/excludes, owned cards, mode, match type and bracket it was built under; a refine keeps them.
• game_plan — win conditions, exact opening-hand land odds, mulligan rules, a sideboard guide (each card's job, when it comes in, what goes out) and matchup notes; Commander decks also get ramp/draw/removal/wipes/ tutors packages. Deterministic, from the list itself.
• bracket (Commander) — Game Changers, mass land denial, extra turns, tutors and two-card combos with an estimated bracket floor (game_changers.json, versioned).
• alternatives — 1-2 other shells that fit; archetype_name builds one.
• color_sources, unpriced_cards, cost_to_complete_usd, deck_id, and on refine changes (the card diff).
• Provenance: source_type (template = curated/synthesized shape, not observed results), plus llm_added_cards, budget_substitutions and dropped_includes with reasons.

Request options beyond the basics: mode (fast-competitive / constraint-aware / creative-but-viable), match_type (bo1 → no sideboard), bracket (1-5), owned_cards, archetype_name. Briefs are parsed deterministically when no LLM key is set (colors, guilds, budgets, playstyles, "no X", commander names). Export targets: plain, Arena, Moxfield, Archidekt, CSV.

Evaluation

qa/benchmark.py runs 108 deterministic scenarios (all formats, colors, budgets, modes, Bo1/Bo3, brackets, prompts, scripted refines) and reports legality, color fidelity, budget adherence, sideboard completeness, bracket compliance, refine success, prompt fidelity and latency — see qa/README.md. A 40-scenario subset gates CI (api/tests/test_benchmark_gate.py).

Resolved to-do items

• Per-format meta archetypes — META_BY_FORMAT now ships Standard, Pioneer, Legacy, and Commander opponent sets plus Modern Yawgmoth & Amulet Titan; build_matchup_matrix grades each candidate against its own format's meta.
• Synergy registry expansion — combos live in a versioned combos.json (31 cliques across formats) with suggest_clique_candidates() mining tournament lists for new candidates.
• Tournament benchmark coverage — per-archetype goldfish benchmarks in test_meta_benchmarks.py.
• Production wiring — API-key auth, dedicated prose rate limit, and pgvector retrieval (with fallback) are wired.

Still pending

• Real Redis/Celery broker provisioning (the backend is ready)
• A learned embedding model to replace the deterministic feature-hash embedder (the full pipeline — table, build script, vector/pgvector retrieval modes — is wired and tested today)
• Multi-tenant identity (the current owner field is a hash of the API key)
• A real (observed) Commander and constructed tournament corpus: the bundled corpus is synthesized from curated templates and labelled as such. Licensed lists can be imported with ingest_deck_source (CSV/JSON adapters) and build_archetypes.
• Price data: ~22% of cards have no price in the current ingest; decks list them (unpriced_cards) rather than counting them as free.