Software Architecture Design

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 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
• Single-service implementation (routes, controllers, business logic) → software-backend
• API endpoint design (REST conventions, GraphQL schemas) → dev-api-design
• Security implementation (auth, encryption, OWASP) → software-security-appsec
• Frontend component architecture → software-frontend
• Database query optimization → data-sql-optimization
• Agent workflow implementation / MCP server implementation → ai-agents, agents-mcp

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.
• If the unresolved question is implementation of agent protocols, tool servers, or runtime-specific integrations, route to ai-agents or agents-mcp.

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: