Skip to content

Complete Reference

Architecture First Cheat Sheet

15 chapters. 4 parts. All the key patterns on one page.

The Compounding Flywheel

Docs → Types → Domains → Events → Quality Gates → Ship → Improve ↻

These patterns form a system where shipping speed and code quality both improve over time, instead of trading off.

I The Shift

01 The 10x Math

Without architecture, AI gives you 2x. With it, 10x. The first domain is slow. By the fifth, everything compounds.

AI alone2-3xLots of rework
AI + architecture5-10xMinimal rework

02 Your AI Partnership

You own architecture. AI owns implementation.

YOU: Domain entities · API contracts · DB schema · Security · Error strategy

AI: Variable naming · Test cases · Imports · CRUD boilerplate · Docs

03 Documentation as Code

5 files, ~3k words, ~90 min. AI accuracy: 40% → 90%.

  • ARCHITECTURE.md — Stack + decisions
  • DOMAIN_PATTERNS.md — Feature blueprint
  • API_CONVENTIONS.md — URLs, status codes, pagination
  • DATABASE_PATTERNS.md — Naming, columns, enums
  • TESTING_STRATEGY.md — What, how, naming
II The Foundation

04 Type Safety Pipeline

One schema, zero drift. Pydantic → OpenAPI → TypeScript.

847 compile-time errors caught · 0 runtime type errors

Ban any · All API types from codegen · strict: true

05 Domain Boundaries

Organize by business domain. AI context: 16k lines → 1k lines.

AI first-try: 40% → 88% · Merge conflicts: 6+/wk → 0.4/wk

Service owns logic · No cross-domain imports · Events carry IDs

06 Events Over Calls

8 deps → 1 EventBus. Events are facts (past tense), not commands.

✓ user.deactivated

✗ send.notification

07 Security by Architecture

RLS at database. No context = no data. Fail-safe default.

Auth at middleware → Authz at policy → Isolation at database
III The Craft

08 Quality Gates

3 layers, strict speed budgets, 87% bugs caught before review.

Pre-commit<5sruff, format, secrets
Pre-push<60smypy, unit tests, security
CI/CD<5mFull suite, 80% coverage

Fix cost: 1x at commit → 1,200x in production

09 Ship & Improve

Phase 1: Make it work (2h). Phase 2: Make it right (30min, next morning).

Boy Scout Rule: every file you touch, one improvement

Rule of Three: copied twice? extract on the third

40 features / 6 months · 45h total refactoring · 7% duplication

10 Testing for Confidence

Always test: business rules, authorization, isolation, edge cases

Skip: framework behavior, trivial getters, layout tests

Name: test_{action}_{scenario}_{result}

11 Prompt Engineering

Leverage hierarchy: Docs > Types > Domains > Examples > The prompt itself

Show a working example, ask for the next one. Pattern matching beats explaining.

IV The Playbook

12 The Five Traps

1
Premature Abstraction — Don't DRY until the third time
2
Blind AI Trust — Review like a junior dev PR
3
Big-Bang Refactoring — Continuous small improvements
4
Skipping Documentation — 90 min investment, 10x return
5
Perfection Paralysis — Time-box, ship when timer rings

Start Here — This Week

  1. 1 Build your .claude/ directory 90 min
  2. 2 Install pre-commit hooks 30 min
  3. 3 Set up Pydantic → OpenAPI → TypeScript 2 hours
  4. 4 Reorganize one module into domain structure 1 hour
  5. 5 Apply Boy Scout Rule to every file you touch ongoing

Want the full story behind each pattern?

Start the Free Course