Skip to content

Architecture Patterns

These patterns govern how systems are structured and how components interact.

Implementation Guide

This guide is part of a modular documentation set. Refer to related guides for complete context.

Patterns in This Section

Separation of Concerns

Single-responsibility components with clear boundaries. Orchestration separate from execution. Testability through isolation.

Use when: Building CLIs, microservices, or any system with distinct responsibilities

Key benefit: Maintainability – change one thing without breaking everything

Hub and Spoke

Centralized orchestration with distributed execution. One coordinator, many workers. Event-driven task distribution.

Use when: Scaling workflows, managing distributed systems, event-driven architectures

Key benefit: Scalability – add workers without changing orchestration

Strangler Fig

Incremental migration from legacy systems. Run old and new in parallel. Gradually shift traffic. Zero downtime transitions.

Use when: Replacing monoliths, migrating to new tech, risky system rewrites

Key benefit: Risk reduction – rollback at any point, validate in production

Three-Stage Design

Separate discovery, execution, and reporting phases. Workflows that fail gracefully and report completely.

Use when: Building complex CI/CD workflows, multi-step automation

Key benefit: Observability – always know what happened, even on failure

Matrix Distribution

Parallel processing of multiple targets. Dynamic matrices for scalability.

Use when: Processing many targets, scaling workflows, reducing execution time

Key benefit: Performance – parallel execution instead of sequential

How These Patterns Relate

flowchart TD
    A[System Design] --> B[Separation of Concerns]
    B --> C[Clear Boundaries]
    C --> D[Hub and Spoke]
    D --> E[Distributed Execution]
    A --> F[Legacy Migration]
    F --> G[Strangler Fig]
    G --> B

    %% Ghostty Hardcore Theme
    style A fill:#65d9ef,color:#1b1d1e
    style B fill:#a7e22e,color:#1b1d1e
    style C fill:#fd971e,color:#1b1d1e
    style D fill:#9e6ffe,color:#1b1d1e
    style E fill:#a7e22e,color:#1b1d1e
    style F fill:#65d9ef,color:#1b1d1e
    style G fill:#f92572,color:#1b1d1e

Separation of Concerns provides the foundation. Hub and Spoke scales it. Strangler Fig migrates to it.

These architectural patterns complement:

Build systems that scale, change, and survive.

Comments