wicked-garden-engineering-system-design

System Design Skill

Decompose systems into well-defined components with clear boundaries and interfaces.

Purpose

Transform architecture into concrete components:

• Component identification and boundaries
• Interface definition
• Dependency management
• Module organization

Process

1. Identify Components

Ask:

• What are major capabilities?
• What changes together?
• What has different scaling needs?
• What domain concepts exist?

2. Define Boundaries

Apply:

• High Cohesion - Related functionality together
• Low Coupling - Minimal dependencies
• Single Responsibility - One reason to change
• Information Hiding - Encapsulate internals

3. Design Interfaces

For each component:

• Public API (what it exposes)
• Dependencies (what it needs)
• Events (what it publishes/subscribes)
• Data contracts (I/O structures)

4. Document

Creates in phases/design/:

design/
├── components/
│   ├── overview.md
│   ├── auth-component.md
│   └── dependencies.mmd
└── interfaces/
    └── component-api.md

Component Patterns

Layered - Presentation → Application → Domain → Infrastructure Hexagonal - Business logic with adapter ports Plugin - Core system with pluggable extensions

See component patterns in refs/ (patterns-layered-pattern.md, patterns-facade-pattern.md).

Dependency Management

Rules

1. Acyclic - No circular dependencies
2. Unidirectional - Dependencies flow one way
3. Stable - Depend on stable abstractions
4. Explicit - Declare in constructor/config

Common Anti-Patterns

God Object - One component does everything Fix: Split by responsibility

Feature Envy - Component uses another's data extensively Fix: Move functionality to data owner

Circular Dependencies - A depends on B, B depends on A Fix: Extract shared logic or use events

Leaky Abstraction - Internal details exposed Fix: Refine public interface

See dependency guides in refs/ (dependencies-dependency-principles.md, dependencies-best-practices.md).