Software Architecture Design

Use this skill for deep software and platform architecture decisions inside a known solution shape rather than implementation details within a single service or component.

If the question starts from a business workflow, system landscape, target state, or phased cross-system migration, use [../software-solution-architecture/SKILL.md](../software-solution-architecture/SKILL.md) first and come here for runtime, decomposition, and operability depth.

Treat estate modernization, platform engineering, and AI-native interoperability as optional deep dives. Do not load them unless the user is explicitly asking for those concerns.

Quick Reference

When to Use This Skill

Invoke when working on:

• Software shape inside a known solution: Turning a chosen solution shape into runtime boundaries, bounded contexts, and platform decisions
• System decomposition: Deciding between monolith, modular monolith, microservices
• Architecture patterns: Event-driven, CQRS, layered, hexagonal, serverless
• Platform architecture: Internal developer platforms, golden paths, policy and delivery guardrails
• Estate modernization: Too many repos, too many runtime units, polyrepo rationalization, platform-first operating models
• Data architecture: Consistency models, sharding, replication, CQRS patterns
• Scalability design: Load balancing, caching strategies, database scaling
• Resilience patterns: Circuit breakers, retries, bulkheads, graceful degradation
• API boundary design: Service-to-service contract posture, versioning strategy, and integration shape when the boundary decision is architectural
• Architecture decisions: ADRs, tradeoff analysis, technology selection
• Migration planning: Monolith decomposition, strangler fig, database separation
• AI-native architecture: RAG boundaries, tool gateways, and interoperability protocols when the request is architecture-level rather than tool/server implementation

When NOT to Use This Skill

Use other skills instead for:

• Cross-system solution design (business flow, target state, integration landscape, phased transition across systems) → [software-solution-architecture](../software-solution-architecture/SKILL.md)
• Single-service implementation (routes, controllers, business logic) → [software-backend](../software-backend/SKILL.md)
• API endpoint design (REST conventions, GraphQL schemas) → [dev-api-design](../dev-api-design/SKILL.md)
• Security implementation (auth, encryption, OWASP) → [software-security-appsec](../software-security-appsec/SKILL.md)
• Frontend component architecture → [software-frontend](../software-frontend/SKILL.md)
• Database query optimization → [data-sql-optimization](../data-sql-optimization/SKILL.md)
• Agent workflow implementation / MCP server implementation → [ai-agents](../ai-agents/SKILL.md), [agents-mcp](../agents-mcp/SKILL.md)

Boundary Rules

• This skill owns runtime boundaries, deployable-unit decisions, data consistency tradeoffs, resilience internals, and platform defaults.
• Start from the simplest architecture that satisfies the constraints; do not default to microservices, event sourcing, service mesh, or multi-agent splits without explicit evidence.
• If the unresolved question is still "which systems participate, where is the system of record, or what is the target-state landscape?" route back to [software-solution-architecture](../software-solution-architecture/SKILL.md).
• If the unresolved question is implementation of agent protocols, tool servers, or runtime-specific integrations, route to [ai-agents](../ai-agents/SKILL.md) or [agents-mcp](../agents-mcp/SKILL.md).

Decision Tree: Choosing Architecture Pattern

Primary question: [What kind of architecture problem is this?]
    ├─ Large estate with many repos/services and rising cognitive load?
    │   ├─ Runtime count is the main problem → Bounded-context platforms + selective consolidation
    │   ├─ Delivery inconsistency is the main problem → IDP + golden paths + scorecards
    │   └─ Both are true → Platform-first modernization, then consolidate low-value runtime units
    │
    ├─ Deterministic workflow, known steps?
    │   ├─ Single deployable acceptable → Modular Monolith
    │   ├─ Independent teams/capabilities required → Sequential or event-driven services
    │   └─ Burst-driven or edge-triggered workload → Serverless / event-driven
    │
    ├─ Adaptive workflow with tool use and reasoning?
    │   ├─ One agent can own the task → Single-agent system
    │   ├─ Specialized roles truly needed → Multi-agent with explicit stop conditions
    │   └─ High stakes / regulated workflow → Human-in-the-loop + audit trail
    │
    ├─ Strong consistency inside one domain boundary?
    │   ├─ Keep data and writes together → Monolith or Modular Monolith
    │   └─ Split only at stable bounded contexts → Microservices with owned data
    │
    └─ Need platform-level consistency across many teams?
        ├─ Repeated service creation / compliance needs → IDP + golden paths
        └─ Cross-agent or cross-vendor interoperability → MCP for tools/context, A2A for agent-to-agent

Decision Factors:

• Default posture: prefer modular monolith over microservices unless independent deployment, ownership, and operability benefits are clear — see the explicit team-size/release-cadence/operational-maturity gates in [modern-patterns.md § Modular Monolith vs. Microservices](references/modern-patterns.md#modular-monolith-vs-microservices-explicit-gates-2026-default)
• Estate posture: optimize for fewer runtime units before fewer repos; repositories are collaboration units, runtimes are operational cost centers
• Agent posture: prefer deterministic workflows or a single agent before introducing multi-agent coordination
• Connectivity posture: prefer gateway plus application-library patterns until mTLS, traffic policy, or shared telemetry needs justify mesh complexity
• Team structure (Conway's Law) — architecture mirrors org structure
• Deployment independence needs
• Consistency and failure-domain boundaries
• Operational maturity (monitoring, orchestration)
• Interoperability needs (protocols, contracts, external systems)

Where to split: fracture planes (Skelton and Pais, Team Topologies, 2nd ed., 2025). A fracture plane is "a natural seam in the software system that allows the system to be split easily into two or more parts" — the stonemason's analogy. Candidate planes: business domain bounded context (the default, and the one most splits should map to), regulatory compliance, change cadence, team location, risk, performance isolation, technology, and user personas.

• Litmus test, quoted: "Does the resulting architecture support more autonomous teams (less dependent teams) with reduced cognitive load (less disparate responsibilities)?" Concretely: after the split, can each team build, test, and deploy its part without coordinating with another team?
• Composite rule: real boundaries usually combine planes — "we can and should break down a monolith by combining different types of fracture planes," and "often, a combination of fracture planes will be required."
• Distributed-monolith warning: splitting the software without aligning the boundaries to teams and their release paths buys distribution cost with none of the autonomy. The book quotes Amy Phillips: "If you have microservices but you wait and do end-to-end testing of a combination of them before a release, what you have is a distributed monolith." Coupling also creeps in below the service boundary — shared databases, coupled builds and releases.
• Make segments team-sized: "it is essential to make software segments team sized so that teams can effectively own and evolve their software in a sustainable way."

See [references/modern-patterns.md](references/modern-patterns.md) for detailed pattern descriptions, and [references/modern-patterns.md § Connascence](references/modern-patterns.md#connascence-a-finer-grained-coupling-vocabulary) to check whether a proposed seam leaves strong coupling crossing it.

Output Guidelines

The references in this skill are background knowledge for you — absorb the patterns and present them as your own expertise. Do not cite internal reference file names (e.g., "from data-architecture-patterns.md") in user-facing output. Users don't know these files exist.

Every architecture recommendation must cover the following; skip elements only with explicit justification:

• Simplest sufficient topology — state the least-complex architecture that still satisfies requirements
• Concrete technology picks — name specific technologies (e.g., "Temporal.io for workflow orchestration", not just "an orchestrator")
• Recommended option + rejected alternatives — what was considered, why alternatives lost
• What NOT to build — explicitly defer or exclude premature scope
• Team and process alignment — CODEOWNERS, deployment ownership, on-call boundaries
• Repo and runtime model — for multi-repo estates, distinguish repo count from deployable count
• Operability model — deployment topology, failure domains, rollback points, SLO ownership, incident boundaries
• Migration path — sequencing, cutover strategy, reversibility (for refactors or new subsystems)
• Key risks and failure modes — named breakpoints, how to detect early
• Success metrics — measurable indicators: deploy frequency, lead time, error rates, MTTR

Workflow (System-Level)

Use this workflow when a user asks for architecture recommendations, decomposition, or major platform decisions.

1. Clarify: problem statement, non-goals, constraints, and success metrics
2. Capture quality attributes: availability, latency, throughput, durability, consistency, security, compliance, cost
3. Decide workload shape: deterministic workflow, single-agent, or multi-agent; synchronous vs asynchronous
4. Propose 2–3 candidate architectures and compare tradeoffs
5. Default to the least-complex viable topology before justifying more distributed patterns
6. For 20+ repo estates, classify each repo as runtime, adapter, library, channel, platform, tooling, or absorption candidate
7. Define boundaries: bounded contexts, ownership, APIs/events, protocol contracts, interoperability needs
8. Decide data strategy: storage, consistency model, schema evolution, migrations
9. Design for operations: SLOs, failure modes, observability, deployment, DR, incident playbooks
10. Design governance and safety: policy enforcement, auditability, evaluation gates, rollback controls
11. Call out scope limits: what NOT to build yet, what to defer, what to buy vs build
12. Document decisions: write ADRs for key tradeoffs and irreversible choices

Preferred deliverables (pick what fits the request):

• Architecture blueprint: assets/planning/architecture-blueprint.md
• Estate modernization blueprint: assets/planning/estate-modernization-blueprint.md
• Decision record: assets/planning/adr-template.md
• Pattern deep dives: references/modern-patterns.md, references/scalability-reliability-guide.md

ASCII Flow

Architecture design request
  -> Define quality attributes and system boundaries
  -> Map domain model, dependencies, and failure modes
  -> Choose architecture pattern and integration style
  -> Document rejected options and tradeoffs
  -> Define migration, observability, and verification checks
  -> Hand off implementable decisions and open risks

Known Traps

• Choosing microservices because the estate already has many repos, even though runtime sprawl and weak ownership are the real issue.
• Drawing a target-state diagram without a migration sequence, rollback boundary, or compatibility plan between old and new paths.
• Splitting domains before ownership, on-call, and deploy authority are ready to support the additional surface area.
• Introducing async and event-driven workflows on every boundary before deciding which paths actually need decoupling.
• Calling something platform engineering while the golden path remains optional, inconsistent, or under-owned.

Common Anti-Patterns

• Using deployable services as the default decomposition unit instead of bounded contexts, team ownership, and operational cost.
• Copying hyperscaler or vendor reference architectures into teams that do not have equivalent scale, tooling, or platform staffing.
• Designing for peak optional futures instead of the current throughput, failure, compliance, and change-management constraints.
• Keeping every repo and runtime because each has "some value" despite obvious coordination and governance cost.
• Conflating "modern" with "more distributed" and "AI-native" with "multi-agent by default."

Navigation

Core References

Read at most 2–3 references per question — pick the ones most relevant to the specific ask. Do not read all of them.

Templates

Planning & Documentation ([assets/planning/](assets/planning/)):

• [architecture-blueprint.md](assets/planning/architecture-blueprint.md) — Service blueprint (dependencies, SLAs, data flows, resilience, security, observability)
• [estate-modernization-blueprint.md](assets/planning/estate-modernization-blueprint.md) — Estate blueprint (repo/runtime classification, target platform map, migration waves, scorecards)
• [adr-template.md](assets/planning/adr-template.md) — Architecture Decision Record for tradeoff analysis

Architecture Patterns ([assets/patterns/](assets/patterns/)):

• [microservices-template.md](assets/patterns/microservices-template.md) — Microservices design (API contracts, resilience, deployment, testing)
• [event-driven-template.md](assets/patterns/event-driven-template.md) — Event-driven architecture (event schemas, saga patterns, event sourcing)

Operations ([assets/operations/](assets/operations/)):

• [scalability-checklist.md](assets/operations/scalability-checklist.md) — Scalability checklist (DB scaling, caching, load testing, auto-scaling, DR)

Validation

• [evals/evals.json](evals/evals.json) — trigger, non-trigger, and near-boundary behavioral checks for this skill

Applied-Recipe Toolkits

• [references/decision-theory-applied.md](references/decision-theory-applied.md) — Decision-theory applied recipes for architecture: ADRs with EU + sensitivity, real-options for irreversible choices, VoI on spikes.
• [references/queueing-theory-applied.md](references/queueing-theory-applied.md) — Queueing-theory applied recipes for architecture: service sizing, backpressure topology, tail-latency budget.
• [references/theory-of-constraints-applied.md](references/theory-of-constraints-applied.md) — TOC applied recipes for architecture: system-wide bottleneck hunt, refactor scope, stability-vs-velocity ADR.
• [references/distributed-systems-applied.md](references/distributed-systems-applied.md) — Distributed-systems primitives applied to architecture: CAP-conscious service boundaries, consensus algorithm selection, idempotency at API surfaces, leases-with-fencing for leader-elected jobs, quorum sizing, consistency-vs-latency ADR template.
• [references/reliability-theory-applied.md](references/reliability-theory-applied.md) — Reliability primitives (MTBF/MTTR, availability, FMEA, error budgets) applied to software architecture design.

Related Skills

• [software-solution-architecture](../software-solution-architecture/SKILL.md) — End-to-end solution design, system landscape, target-state and migration architecture
• [software-backend](../software-backend/SKILL.md) — Backend engineering, API implementation, data layer
• [software-frontend](../software-frontend/SKILL.md) — Frontend architecture, micro-frontends, state management
• [dev-api-design](../dev-api-design/SKILL.md) — REST, GraphQL, gRPC design patterns
• [ops-devops-platform](../ops-devops-platform/SKILL.md) — CI/CD, deployment strategies, IaC
• [qa-observability](../qa-observability/SKILL.md) — Monitoring, tracing, alerting, SLOs
• [software-security-appsec](../software-security-appsec/SKILL.md) — Threat modeling, auth, secure design
• [data-sql-optimization](../data-sql-optimization/SKILL.md) — Database design, optimization, indexing
• [docs-codebase](../docs-codebase/SKILL.md) — Architecture documentation, docs-as-code structure
• docs-diagram-design — Whether a diagram earns its place, and what it must show
• [ai-agents](../ai-agents/SKILL.md) — Agent system design, orchestration, evaluation
• [agents-mcp](../agents-mcp/SKILL.md) — MCP server/client patterns and integration

Freshness Protocol

When users ask version-sensitive questions about architecture patterns, platform engineering, or AI-native systems, verify current information before answering.

Trigger Conditions

• "What's the best architecture for [use case]?"
• "Microservices vs monolith — what's the current recommendation?"
• "What's the latest in platform engineering / service mesh / AI architecture?"
• "How do I modernize 50/100+ repos or reduce service sprawl?"
• "Is [pattern] still recommended?"

How to Freshness-Check

1. Start from data/sources.json and prefer official docs, standards, release notes, and lifecycle pages.
2. Run a targeted web search for the specific architecture pattern or platform.
3. Use non-primary sources only as durable background, not as freshness authority.

Load only when the question explicitly involves current trends, vendor-specific constraints, AI-native architecture, or "what's the latest thinking on X?"

• [references/architecture-trends.md](references/architecture-trends.md) — Platform engineering, ambient mesh, MCP/A2A interoperability, AI-native systems
• [references/estate-modernization.md](references/estate-modernization.md) — Estate rationalization, bounded-context platforms, platform-first migration posture
• [data/sources.json](data/sources.json) — curated resources organized by category:

- platformengineering2026 — IDPs, software catalogs, and template-driven platform defaults - estatemodernization2026 — strangler migration, anti-corruption layers, repo-vs-runtime guidance - optionalaiarchitecture — MCP/A2A protocols and architecture-level AI interoperability references - modernarchitecture2026 — ambient mesh and other version-sensitive platform patterns

If live web access is available, consult 2–3 authoritative sources from data/sources.json and fold findings into the recommendation. If not, answer with durable patterns and explicitly state assumptions that could change (vendor limits, pricing, managed-service capabilities, or lifecycle status).

Fact-Checking

• Known bugs, regressions, framework/compiler/runtime footguns, and version-specific crash or workaround guidance must be verified against current primary web sources before being treated as current fact.
• Use web search/web fetch to verify current external facts, versions, pricing, deadlines, regulations, or platform behavior before final answers.
• Prefer primary sources; report source links and dates for volatile information.
• If web access is unavailable, state the limitation and mark guidance as unverified.

Learnings Loop

Before applying this skill on a non-trivial task, read learnings.consolidated.md in this directory (and learnings.md if present).

After applying it, if you encountered a pattern worth remembering, a mistake worth preventing, or a domain fact that surprised you, append one dated bullet to learnings.md via agents-skills-feedback-loop/scripts/append_learning.py. Do not modify SKILL.md itself.