MagicAIBuilder ✦

A beautiful, intelligent Commander deck builder powered by Scryfall, bracket scoring, and AI suggestions.

Features

• 🔍 Scryfall search — full syntax support, commander mode, By Set, By Color
• 🎨 Card printing selector — choose your preferred art before adding or swap it anytime from the deck list
• 🃏 Drag & drop deck builder — list and grid views, categorized zones; commander pinned first in grid view
• 📊 Live bracket scoring — 6-dimension analysis (ramp, draw, removal, tutors, win speed, CMC)
• ⚡ Game Changers detection — auto-warns when you cross bracket thresholds
• 🤖 AI suggestions — Anthropic Claude or OpenAI GPT analyzes your deck and recommends cards + cuts
• 🤝 Partner pairing — Partner, Partner With, Friends Forever, Background, Doctor's Companion, Character Select (TMNT) — filtered search per pairing type
• 📦 Companion (Ikoria) — dedicated slot + Companion search mode, rule hints, color/mechanical warnings (not the same as Sideboard pile cards)
• 📤 Multi-format export — Moxfield, MTG Arena, MTGO (.dek), TappedOut, Archidekt, Manabox, Plain Text; import from Moxfield format (SET) 123
• 👑 Set as commander — crown icon on any deck card promotes it to commander slot
• 🔢 Card quantities — +/- buttons for basic lands and Commander-legal multiples (auto-detected via oracle text)
• 📝 Deck notes & tags — per-card notes, deck description, colored tag pills
• 📸 Deck snapshots — save and restore deck states at any point
• 🔗 Deck sharing — generate a shareable read-only link
• 🎮 Playtest mode — draw opening hand, mulligan, simulate turns
• ⌨️ Keyboard shortcuts — power-user navigation with undo stack
• 🌙 Dark / Light theme — persisted across sessions
• 🔒 Security hardened — Zod validation, input sanitization, no client-side secrets

Stack

Layer	Tech
Framework	Next.js 15 (App Router)
Language	TypeScript 5
Styling	Tailwind CSS 4
Components	shadcn/ui + Radix
Animations	Framer Motion
State	Zustand 5
Data fetching	TanStack Query 5
Database	PostgreSQL 16 + Prisma
Drag & Drop	dnd-kit 6

Getting Started

Prerequisites

• Node.js 22+
• pnpm 10+
• Docker (for PostgreSQL)

Setup

# Clone
git clone https://github.com/KaelSensei/MagicAIBuilder.git
cd MagicAIBuilder

# Install dependencies (generates Prisma client automatically)
pnpm install

# Configure environment
cp .env.example .env.local
# Edit .env.local — DATABASE_URL is pre-filled for local Docker

# Start the database
pnpm db:up

# Run migrations
pnpm db:migrate

# Start dev server
pnpm dev

Open http://localhost:3000.

AI Suggestions (optional)

Add one of these to .env.local for personalized AI deck analysis:

ANTHROPIC_API_KEY=sk-ant-...
# or
OPENAI_API_KEY=sk-...

Without a key, the AI panel uses curated generic suggestions.

Scripts

Command	Description
pnpm dev	Start dev server
pnpm build	Production build
pnpm analyze	Production build + interactive bundle map
pnpm lint	ESLint check
pnpm test	Unit tests (Vitest)
pnpm test:e2e	E2E tests (Playwright)
pnpm db:up	Start PostgreSQL via Docker
pnpm db:down	Stop PostgreSQL
pnpm db:migrate	Apply pending migrations
pnpm db:studio	Open Prisma Studio
pnpm db:reset	Reset database

E2E in Docker (Playwright)

If running Playwright locally is unreliable, you can run E2E tests fully inside Docker:

docker compose -f docker-compose.e2e.yml up --build --exit-code-from e2e

Architecture

Browser (Zustand — optimistic updates)
    ↕ fetch
Next.js API Routes (/api/decks/*, /api/ai/suggest)
    ↕ Prisma Client
PostgreSQL 16 (Docker)

External APIs:

• Scryfall — card search, images, Game Changers list, banlist (direct from browser, CORS allowed)
• Commander Spellbook — combo detection (proxied via /api/combos)
• Anthropic / OpenAI — AI suggestions (server-side only, key never exposed to client)

Security

See docs/security/security.md for the full security architecture.

Key points:

• All API keys are server-side only
• Input validation via Zod on all API routes
• HTML sanitization on user-controlled strings
• Commander Spellbook proxied to avoid CORS and SSRF vectors

Quality Gate 🧪

Maintained by Marco — The Bug Whisperer. See docs/engineering/quality-gate.md for full details and history.

Metric	Baseline	Minimum
Coverage	94.3%	≥ 90%
Bugs	0	= 0
Vulnerabilities	0	= 0
Code Smells	1	≤ 5
Duplicated Lines	1.8%	≤ 3.0%
Reliability	A	A
Security	A	A

A PR that degrades any of these metrics is blocked until fixed.

Docs

docs/ is organized by audience and purpose (product, engineering, project tracking, security).

docs/
  engineering/
    dx-ci-overview.md          # CI/DX overview: pipelines, local dev checks, quality tooling
    infrastructure.md          # Infra + hosting notes (Vercel, DB, storage, observability)
    quality-gate.md            # Quality thresholds + Sonar/CI expectations
    technical.md               # Technical architecture: modules, data flow, DB, patterns
  product/
    companion-implementation.md  # Ikoria Companion product/rules (linked from user stories)
    competitive-landscape.md   # Competitor analysis / positioning notes
    project-spec.md            # Product/engineering spec: scope, UX, rules, implementation notes
    roadmap.md                 # Future work backlog: technical + functional roadmap + prioritization
    user-flows.md              # End-to-end user journeys and flows
    user-guide.md              # End-user manual: how to use the app
    us-detail.md               # Full user stories backlog
  project/
    changelog.md               # Release notes / history of changes
    progress.md                # Project checklist / milestones / tracking
  security/
    security.md                # Threat model + security architecture + hardening rules
  prompt-system/               # Prompting system docs (AI behavior, prompts, conventions)
  references/                  # Reference material (patterns, examples)
  rules/                       # Internal rules / conventions docs (e.g. magic-comp-rules-*.txt)
  init-prompt.md               # Seed prompt / bootstrap notes for agent-assisted work

AI Assistants 👾

MagicAIBuilder was conceived, designed, and developed by Kael, with three AI assistants playing different roles in the story:

• Claude (Anthropic – Sonnet 4.6 / Opus 4.6) — helped bootstrap the project (Next.js + Prisma boilerplate), define the TypeScript/React architecture, and ship the very first features like deck creation and editing.
• OpenAI Codex / ChatGPT (GPT‑5.4) — brought in later for heavier work: complex features, deep refactors, proxy/export flows, database migrations, and DevOps plumbing.
• Cursor “automatic” model (GPT‑5.1) — the everyday in‑editor helper, used for fast bug‑fix passes, small refactors, and making the codebase feel “alive” while Kael iterates.

Git commit attribution (optional)

To show multiple authors on a commit, add a blank line at the end of the message body, then one or more Co-authored-by: trailers (GitHub links avatars only when the email matches an account):

Assistant	Example trailer
Claude (Anthropic)	Co-authored-by: Claude <noreply@anthropic.com>
OpenAI Codex / ChatGPT	Co-authored-by: OpenAI Codex <email@example.com> — use an address tied to your GitHub user if you want it linked.
Cursor (Auto / Agent)	Co-authored-by: Cursor Agent <noreply@cursor.com>

License

MIT

Legal

Wizards of the Coast, Magic: The Gathering, and their logos are trademarks of Wizards of the Coast LLC. © 1993-2026 Wizards. All Rights Reserved.

MagicAIBuilder is not affiliated with, endorsed, sponsored, or specifically approved by Wizards of the Coast LLC. This project operates under Wizards' Fan Site Policy. MAGIC: THE GATHERING® is a trademark of Wizards of the Coast.

Some card prices and other card data are provided by Scryfall. Scryfall makes no guarantee about its price information.

See LEGAL.md for full legal notices.