---

name: system-design-principles description: "Define module boundaries, dependency direction, data ownership, resilience, and distributed-system trade-offs. Use for architecture, service boundaries, coupling, scalability, or failure-cascade decisions; defer session facilitation to system-design-methodology." metadata: triggers: keywords: - architecture - scalability - microservice - microservices - module boundary - coupling - bounded context - dependency direction - clean architecture - cap theorem - idempotency

System Design Principles

Priority: P0 (CRITICAL)

Workflow: Evaluate Architecture for New Feature

1. Identify bounded contexts and module boundaries
2. Name the data owner and define dependency direction (outer layers depend on inner)
3. Select communication pattern (sync REST, async event, or hybrid) and failure behavior
4. Validate CAP trade-offs only for distributed components
5. Record boundary, trade-off, and rollback in an ADR

For a failing synchronous dependency, keep the critical path explicit: timeout and circuit-break the dependency, return a defined degraded/fallback result where safe, and move non-critical notifications to an asynchronous event.

Architectural Principles

• SoC: Divide into distinct sections per concern.
• SSOT: One source, reference elsewhere.
• Fail Fast: Fail visibly when errors occur.
• Graceful Degradation: Core functional even if secondary fails.

Modularity & Coupling

• High Cohesion: Related functionality in one module.
• Loose Coupling: Use interfaces for communication.
• DI: Inject dependencies, don't hardcode.

See implementation examples for dependency flow diagrams.

Common Patterns

• Layered: Presentation -> Logic -> Data.
• Event-Driven: Async communication between decoupled components.
• Clean/Hexagonal: Core logic independent of frameworks.
• Statelessness: Favor stateless for scaling/testing.
• Monolith first: Start modular-monolith; split a service out only when a module needs independent scaling, release cadence, or ownership.

Distributed Systems

• CAP: Trade-off Consistency/Availability/Partition tolerance. See CAP & Consistency Patterns.
• Idempotency: Operations repeatable without side effects. See Idempotency Patterns.
• Circuit Breaker: Fail fast on failing services. See Resilience Patterns.
• Eventual Consistency: Design for async data sync. See CAP & Consistency Patterns.

Documentation & Evolution

• Design Docs: Write specs before major implementations.
• Versioning: Version APIs/schemas for backward compatibility.
• Extensibility: Use Strategy/Factory for future changes.

References

• Distributed Systems & CAP Theorem
• Resilience Patterns (Circuit Breaker, Bulkhead, Retry)

Anti-Patterns

• No god classes: Single Responsibility — one reason to change per module.
• No blanket synchronous-coupling ban: choose synchronous, asynchronous, or hybrid communication from the boundary's consistency, latency, failure, and coupling requirements. A bounded synchronous transaction can protect an immediate invariant; independent notifications may remain asynchronous. State the trade-offs and failure behavior.
• No premature abstraction: Design for current load; scale when proven needed.