architecture-patterns

name	architecture-patterns
description	Select an architecture style (layered, hexagonal, microkernel, event-driven, microservices, modular monolith, space-based, serverless) using fitness signals and trade-offs. Use when choosing or evolving the top-level shape of a system.

Architecture Style Selection

The top-level style sets the system's defaults for coupling, deployability, and scaling. This skill maps drivers to the eight foundational styles from Fundamentals of Software Architecture 2e and gives you fitness signals to confirm or refute the choice.

Stack Baseline (2026)

Concern	Recommended
Reference text	Richards & Ford, Fundamentals of Software Architecture, 2e (chapters on architecture styles)
Decomposition guidance	Software Architecture: The Hard Parts (granularity, data ownership)
Microservices guide	Sam Newman, Building Microservices, 2e
Default starting point for green-field business apps	Modular monolith with explicit module APIs
Event backbone (when EDA chosen)	Apache Kafka 3.x or NATS JetStream
Serverless runtime	AWS Lambda / Azure Functions / Cloudflare Workers per locality needs
Currency check	ThoughtWorks Tech Radar

When to Use

• Green-field system needs a top-level shape.
• An existing system is hitting scaling, deployment, or coupling limits.
• A monolith-to-services migration is being scoped.
• Comparing styles for a specific bounded context.

Prerequisites

• Documented quality attribute drivers (ISO/IEC 25010:2023).
• Domain map: at least candidate bounded contexts.
• Honest assessment of team size, platform maturity, and operational capacity.
• Workload shape: read/write ratio, peakiness, latency budgets.

Instructions

flowchart TD
    Q[Quality attribute drivers] --> M{Dominant force}
    M -->|Simplicity, small team| MM[Modular Monolith]
    M -->|Strict isolation per module| HEX[Hexagonal]
    M -->|Plugin extensibility| MK[Microkernel]
    M -->|Async, decoupled flows| EDA[Event-Driven]
    M -->|Independent deploy + scale| MS[Microservices]
    M -->|Extreme elastic read load| SB[Space-Based]
    M -->|Spiky, event-triggered| SL[Serverless]
    M -->|Clear layered concerns, CRUD| L[Layered]

1. Restate dominant drivers. Pick the top 3 quality attributes and the top 2 constraints. Styles are chosen to optimize these, not to follow fashion.
2. Match candidates to drivers using the cheat sheet:
   • Layered — simple CRUD, single deployable, junior team friendly.
   • Modular monolith — green-field default; preserves option to extract services later.
   • Hexagonal (Ports & Adapters) — domain isolation, swappable IO, high testability.
   • Microkernel (Plug-in) — stable core + variable feature set (IDEs, rule engines, ETL hosts).
   • Event-driven — async workflows, broadcast, temporal decoupling.
   • Microservices — independent deploy, polyglot persistence, org scale-out; requires platform maturity.
   • Space-based — extreme elastic read concurrency (booking, ticketing) via in-memory data grid.
   • Serverless — event-triggered, bursty, low baseline; accept cold-start and vendor coupling.
3. Score top 2 candidates on cost of change, time-to-first-deploy, operational surface, data ownership clarity, and team fit.
4. Define fitness signals to detect drift (deploy lead time, change failure rate, p99 latency, blast radius of failure, % cross-service transactions).
5. Document the choice as an ADR linking to the C4 context view and the rejected alternatives.

Mermaid C4 context sketch:

C4Context
    title Order System (Modular Monolith, candidate)
    Person(customer, "Customer")
    System(orders, "Orders App", "Modular monolith: orders, billing, inventory modules")
    System_Ext(payments, "Payments PSP")
    Rel(customer, orders, "Places orders")
    Rel(orders, payments, "Authorizes")

Common Pitfalls

Pitfall	Why it hurts	Mitigation
Microservices as the default	Distributed monolith, ops overload	Start modular monolith; extract on proven need
Confusing EDA with microservices	Two distinct decisions	Decide deployability and async coupling separately
Ignoring data ownership	Shared DB couples "independent" services	One service = one logical schema; integrate via API/event
No fitness signals	Style erodes silently	Track deploy frequency, change-fail rate, p99, blast radius
Style chosen by resume-driven design	Misfit to team capacity	Weight team skills and platform maturity explicitly
Serverless for steady high-throughput	Cost and latency surprises	Reserve serverless for spiky/event-triggered workloads
Space-based for write-heavy OLTP	Wrong fit for the model	Use space-based for elastic read concurrency, not transactional writes

Output Format

# Style Selection: <system or context>
## Drivers and Constraints (top 3 + top 2)
## Candidate Styles Considered
## Trade-off Matrix (attribute x style)
## Recommendation and Rationale
## Migration / Rollout Plan (if changing style)
## Fitness Functions to Monitor
## Links: ADR-NNNN, C4 context view, rejected options

Authoritative References

• Mark Richards & Neal Ford, Fundamentals of Software Architecture, 2e.
• Neal Ford, Mark Richards, Pramod Sadalage, Zhamak Dehghani, Software Architecture: The Hard Parts.
• Sam Newman, Building Microservices, 2e.
• Gregor Hohpe, The Software Architect Elevator.
• ISO/IEC 25010:2023; ISO/IEC/IEEE 42010:2022.
• C4 model: https://c4model.com; arc42: https://arc42.org.
• ThoughtWorks Technology Radar: https://www.thoughtworks.com/radar.