Modern Architecture

DDD + TDD + Clean Architecture + Event-Driven + API-First for TS/Python/Go.

Decision Tree

New feature or module?
|
+- Complex business rules?
|  YES -> DDD Tactical Patterns (references/ddd-tactical.md)
|  |
|  +- Different stakeholders use different terms for same concept?
|  |  YES -> Bounded Contexts (references/ddd-strategic.md)
|  |
|  +- External system integration?
|  |  YES -> Anti-Corruption Layer (references/ddd-strategic.md)
|  |
|  +- Read/write patterns differ significantly?
|     YES -> CQRS (references/event-driven.md)
|
+- Has API surface?
|  YES -> Contract-First: schema before code (references/api-first.md)
|
+- Needs async/real-time communication?
|  YES -> Event-Driven (references/event-driven.md)
|
+- Any of the above?
   YES -> Clean Architecture layers (references/clean-architecture.md)
   NO  -> Simple module, skip this skill

1. Domain Discovery

Define ubiquitous language. List domain events in past tense.

Domain: Order Management
Events: OrderPlaced, OrderCancelled, PaymentReceived
Aggregates: Order, Payment, Shipment

2. Contract First (if API exists)

Define API schema before writing code. See references/api-first.md.

3. Outside-In TDD

Acceptance Test (RED) -> Domain Test (RED->GREEN) -> Use Case Test (RED->GREEN) -> Adapter (GREEN) -> Acceptance (GREEN) -> Refactor

Full workflow in references/tdd-ddd-workflow.md. </important>

domain/           -> Entities, VOs, Events, Ports (zero dependencies)
application/      -> Use Cases, Commands, Queries (depends on domain only)
infrastructure/   -> DB adapters, API controllers (depends on all)

Dependency Rule: Inner layers NEVER import outer layers.

Directory Structure

src/modules/{context-name}/
  domain/
    model/           # Aggregate Root, Entities, Value Objects
    events/          # Domain Events (past tense)
    ports/           # Repository & Service interfaces
    services/        # Domain Services (stateless)
  application/
    use-cases/       # One class per use case
    dto/             # Commands & Queries
  infrastructure/
    persistence/     # Repository implementations + Mappers
    api/             # HTTP Controllers / GraphQL Resolvers
    messaging/       # Event publishers / subscribers

All domain objects return new instances. Never mutate.

// CORRECT: return new instance
addItem(item: OrderItem): Order {
  return new Order(this.id, [...this._items, item], this._status)
}

// WRONG: mutation
addItem(item: OrderItem): void {
  this._items.push(item)  // VIOLATION
}

References

• references/ddd-tactical.md -- Entity, VO, Aggregate, Repository, Domain Event, Factory (TS/Python/Go)
• references/ddd-strategic.md -- Bounded Context, Context Map, Anti-Corruption Layer
• references/clean-architecture.md -- Layers, Ports and Adapters, DI, testing per layer
• references/event-driven.md -- Event Bus, CQRS, Event Sourcing, Pub/Sub
• references/api-first.md -- OpenAPI, tRPC, GraphQL, versioning, error contracts
• references/tdd-ddd-workflow.md -- Outside-In TDD phases, property-based testing