clean-architecture

Clean Architecture Skill

Practical layering rules for this repo. Based on Robert C. Martin's Clean Architecture and Alistair Cockburn's Hexagonal Architecture, translated to the concrete directory layout we actually use.

When to use this skill

• Designing a new feature (commander deck feature, AI suggestion flow, pricing integration, etc.).
• Deciding where a new file goes (lib/, components/, app/api/, server/, hooks/, ...).
• Reviewing a PR that adds Prisma calls inside a React component or Scryfall fetches inside an API route that should delegate.
• During a /refactor that moves code across layers.

Core principle

Dependencies point inward, toward the domain. Outer layers know about inner layers; inner layers do NOT know about outer ones. Concretely in this repo:

    UI (React components, pages)            <-- depends on hooks + lib
         |
    Hooks + server actions + route handlers <-- depends on lib + domain
         |
    Lib (pure domain + use-cases)           <-- depends on domain types only
         |
    Domain types (entities, value objects)  <-- depends on nothing
         |
    Infrastructure (Prisma, Scryfall, Auth) <-- implements ports defined by domain/lib

Layers in this repo

1. Domain (innermost)

• Lives in src/types/, src/lib/<domain>/types.ts, src/lib/<domain>/constants.ts.
• Pure TypeScript. No imports from next, react, @prisma/client, or @auth/*.
• Represents the MTG / Commander business concepts: DeckCard, CommanderPairingType, CardCategory, BracketScore, etc.

2. Use cases / application logic

• Lives in src/lib/<domain>/*.ts (e.g. src/lib/deck/validate.ts).
• Pure functions taking domain types in and returning domain types out.
• MUST be unit-tested (vitest) — these are the highest-value tests.
• Must NOT import from src/app/**, src/components/**, or directly from Prisma / Scryfall clients.

3. Infrastructure adapters

• Prisma access: src/lib/db/<domain>.ts — wraps Prisma queries behind domain-shaped return types. Components never import @prisma/client directly.
• External APIs: src/lib/scryfall.ts, src/lib/moxfield.ts — single entry point per provider, with rate limiting and retries. Components never fetch("api.scryfall.com/...").
• Auth: src/lib/auth.ts wraps next-auth calls; session shape is typed in domain.