Clean Architecture — TypeScript

Apply Clean Architecture (Robert C. Martin), DDD tactical patterns, Hexagonal/Explicit Architecture (Herberto Graca), and Clean Code practices to TypeScript codebases. 76 rules across 11 categories.

Guardrails — never violate these

• Never import outer layers from inner layers — domain imports nothing; application imports only domain
• Never put ORM decorators or Prisma types on domain entities — use mappers in infrastructure
• Never return null for domain errors — use a discriminated Result<T, E> return. In this repo the result branch uses ok: true | false; if E is a rich error union, give each error variant an _tag for exhaustive handling.
• Never use as any or @ts-ignore without a documented justification comment
• Never dispatch domain events before persistence — pull events AFTER save(), dispatch AFTER commit
• Never share one type across domain/API/DB layers — accept cross-layer duplication, each model serves a different master
• Never use barrel files (index.ts with export *) in application code — use direct imports
• Never validate inside domain or use cases — parse at the adapter boundary with Zod, trust inside
• Always use # private fields on entities (runtime encapsulation) — not the private keyword
• Always separate Entity.create() (validates, emits events) from Entity.reconstitute() (loads from DB, no events)
• Always wire dependencies in a single composition root (main.ts) — the only file that knows all concretions
• Always use import type for cross-layer type imports — enable verbatimModuleSyntax: true