Architecture Decision Records
This directory contains all architecture decisions for Decksmith.
ADRs are living documents: they can be amended as the project evolves. Each ADR tracks its evolution history.
Active ADRs
| ID | Title | Status | Date |
|---|---|---|---|
| 0001 | Use Fastify as Web Framework | Active | 2026-01-03 |
| 0002 | Monorepo Structure with pnpm and Turborepo | Active | 2026-01-08 |
| 0003 | TypeScript Strict Mode Configuration | Active | 2026-01-08 |
| 0004 | Code Quality and Formatting Standards | Active | 2026-01-08 |
| 0005 | Package Boundaries and Dependency Graph | Active | 2026-01-08 |
| 0006 | Testing Strategy with Vitest and Storybook | Active | 2026-01-08 |
| 0007 | Job Queue with BullMQ and Redis | Active | 2026-01-10 |
| 0008 | Mobile-First Web Design Principles | Active | 2026-02-04 |
| 0009 | Responsive Feature Strategy | Active | 2026-02-04 |
| 0010 | Link Sharing Meta Tags | Active | 2026-02-04 |
| 0011 | File and Folder Conventions | Active | 2026-02-03 |
| 0012 | Prisma Database Package Configuration | Active | 2026-02-06 |
| 0013 | Migrate to Oxlint and Oxfmt | Active | 2026-03-15 |
| 0014 | API-Proxied Auth | Active | 2026-03-17 |
| 0015 | Design System Architecture | Active | 2026-05-30 |
| 0016 | TanStack Start for apps/web | Active | 2026-05-31 |
| 0017 | packages/tokens Implementation Architecture | Active | 2026-06-08 |
| 0018 | Frontend Library Stack | Active | 2026-06-08 |
| 0019 | packages/web-ui Component Architecture | Active | 2026-06-08 |
| 0020 | TanStack DB — Reactive Client Store | Draft | 2026-06-19 |
| 0021 | Icon Sizing Convention in packages/web-ui | Active | 2026-06-27 |
| 0022 | Row Level Security Strategy | Active | 2026-06-30 |
| 0023 | Auth Guard via beforeLoad + SSR Cookie Forwarding | Active | 2026-07-08 |
| 0024 | Service Layer Architecture | Active | 2026-07-14 |
| 0025 | Internationalisation Strategy | Active | 2026-07-14 |
| 0026 | Reverse Proxy & Deployment Topology (Traefik) | Active | 2026-07-21 |
| 0027 | Web Hosting — TanStack Start SSR Node Server | Active | 2026-07-24 |
| 0028 | Release & Versioning — semantic-release | Active | 2026-07-29 |
| 0029 | Multi-Face Card Modeling & Scryfall Fields | Active | 2026-07-30 |
| 0030 | Worker Database Access — Prisma Direct | Active | 2026-08-09 |
| 0031 | Job Queue — BullMQ + Self-Hosted Redis | Active | 2026-08-09 |
| 0032 | Card Search Architecture | Active | 2026-08-10 |
How to Create a New ADR
Using Claude Code (recommended)
In VSCode, open Claude Code and use the ADR creation skill:
/adr.create
I want to document [your decision]Claude Code will guide you through the process using the template.
Manually
- Copy
template.mdto a new file:XXXX-short-title.md(use next sequential number) - Fill in all sections based on template structure
- Update this README with the new entry
- Commit with message:
docs: add ADR-XXXX [title]
How to Update an Existing ADR
In Claude Code:
/adr.update
Update ADR-XXXX: [describe the change]ADRs are living documents. Updates should:
- Preserve evolution history (add entry in "Evolution History" section)
- Update "Last Updated" date
- Change status if needed (Active → Deprecated → Superseded)
- Never delete or rewrite history
ADR Status Values
- Draft: Under discussion, not yet implemented
- Active: Current decision, implemented and in use
- Deprecated: No longer recommended, but not yet replaced
- Superseded: Replaced by a newer ADR (link to successor)