| name | composable-architecture |
| description | Apply functional and compositional architecture patterns when designing systems, modules, and components. Use when creating architecture definitions, designing system boundaries, defining interfaces, or building modular systems. |
Composable Architecture Patterns
Core Principles
Functional Core, Imperative Shell
- Pure core: Business logic as pure functions (no side effects)
- Imperative shell: I/O pushed to system edges
- Unit test core, integration test shell
Composition Over Inheritance
- Build from small, composable functions
- Prefer data transformation over stateful mutation
- Use pipelines and modifier chaining
Hexagonal Architecture (Ports & Adapters)
[External] → [Adapter] → [Port] → [Core] → [Port] → [Adapter] → [External]
- Core: Pure business logic, no external dependencies
- Ports: Interfaces defining capabilities
- Adapters: Implementations connecting to external systems
C4 Model Hierarchy
- System Context: Boundaries and external actors
- Module: Major architectural components (map 1:1 to directories)
- Component: Internal module structure
- Code: Implementation details
Design Process
New system:
- Define boundaries (inside vs outside)
- Identify ports (capabilities needed/provided)
- Design pure core (business rules as functions)
- Create adapters (connect to external world)
Refactoring:
- Extract pure functions from mixed logic
- Define interfaces for dependencies
- Move I/O to edges
- Replace inheritance with composition
Anti-patterns
- Mixing business logic with I/O
- Circular dependencies between modules
- Using inheritance for code reuse
- Coupling core logic to specific technologies
- "God" modules with multiple responsibilities
Remember: Build from simple, pure, testable pieces. Keep complex logic in pure core, push messy reality to edges.