| name | architect-systems |
| source | botcore |
| description | Guides software architecture decisions across patterns, trade-offs, and documentation. Covers monolith vs microservices, modular monoliths, event-driven architecture, CQRS, hexagonal/ports-and-adapters, DDD bounded contexts, ADRs, evolutionary architecture with fitness functions, and platform engineering. Use when designing system architecture, choosing patterns, writing ADRs, decomposing domains, evaluating trade-offs, or planning migrations. Triggers: architecture, system design, microservices, monolith, DDD, bounded context, event-driven, CQRS, ADR, hexagonal, fitness function, platform engineering.
|
| version | 1.0.0 |
| triggers | ["architecture","system design","microservices","monolith","modular monolith","DDD","domain driven design","bounded context","event-driven","CQRS","ADR","architecture decision record","hexagonal architecture","ports and adapters","fitness function","evolutionary architecture","platform engineering","service decomposition","system decomposition"] |
| portable | true |
Architecting Systems
Software architecture patterns, decision-making frameworks, and agent-maintainable design for modern systems.
Capabilities
- Pattern Selection -- Evaluate and recommend architecture patterns (monolith, modular monolith, microservices, serverless) based on team size, domain complexity, and operational maturity
- Domain Decomposition -- Apply DDD strategic design to identify bounded contexts, subdomains, and context maps that drive service boundaries
- Architecture Decision Records -- Author and review ADRs using lightweight markdown templates that capture context, decision, and consequences
- Event-Driven Design -- Design event-driven systems using CQRS, event sourcing, and asynchronous messaging patterns
- Hexagonal Architecture -- Structure applications using ports-and-adapters to isolate domain logic from infrastructure concerns
- Evolutionary Architecture -- Define fitness functions and automated governance to ensure architectures evolve safely over time
- Agent-Maintainable Design -- Architect systems with explicit boundaries, clear contracts, and discoverable structure so AI agents can navigate, modify, and extend them confidently
- Platform Engineering Guidance -- Advise on internal developer platform design, self-service capabilities, and golden paths
Routing Logic
Core Principles
1. Decisions Over Diagrams
Architecture is the set of decisions that are hard to reverse.
Document decisions (ADRs), not just diagrams. Diagrams rot; recorded reasoning endures.
Every significant architectural choice must produce an ADR. The ADR captures why a decision was made, not just what was decided. When revisiting a decision later, the context section tells you whether the original constraints still hold.
2. Start Simple, Evolve Deliberately
Begin with the simplest architecture that meets current constraints.
Premature decomposition is more expensive than a well-structured monolith.
| Team / Domain Signal | Recommended Starting Point |
|---|
| Single team, unclear domain boundaries | Modular monolith |
| Multiple teams, well-understood domains | Service-per-bounded-context |
| Spike / prototype / validation | Single deployable |
| High-scale, independent release cadence per domain | Microservices |
Split only when you have evidence: independent scaling needs, distinct release cadences, or organizational boundaries that demand it.
3. Domain First, Technology Second
Let the domain model drive architecture boundaries.
Technology choices serve the domain, not the other way around.
- Identify subdomains -- Core (competitive advantage), Supporting (necessary but not differentiating), Generic (commodity)
- Draw bounded contexts -- Each context owns its ubiquitous language and data
- Map context relationships -- Upstream/downstream, conformist, anti-corruption layer, shared kernel
- Then choose technology -- The pattern (monolith module, service, serverless function) follows from context boundaries
4. Explicit Contracts at Every Boundary
Every boundary between modules, services, or teams must have an explicit contract.
Implicit coupling is the primary cause of architectural decay.
Contracts include:
- API contracts -- OpenAPI specs, protobuf definitions, GraphQL schemas
- Event contracts -- Schema registry, versioned event schemas
- Data contracts -- Ownership, SLAs, schema evolution rules
- Team contracts -- Context maps showing upstream/downstream obligations
5. Agent-Maintainable by Default
Architecture should be navigable and modifiable by AI agents without hidden context.
If an agent cannot discover a boundary, a human will also struggle.
Design for agent maintainability:
- Discoverable structure -- Consistent directory layout, naming conventions, and manifest files
- Explicit wiring -- Dependency injection, configuration-as-code, no magic globals
- Documented boundaries -- Each module/service has a README or manifest describing its purpose, contracts, and dependencies
- Small, focused units -- Files under 500 lines, functions under 50 lines, modules with single responsibilities
- Testable in isolation -- Each bounded context or module can be tested without spinning up the entire system
6. Evolutionary Over Planned
No architecture survives first contact with production unchanged.
Build fitness functions that guard architectural qualities as the system evolves.
- Define fitness functions for key architectural characteristics (modularity, performance, security, coupling)
- Embed fitness functions in CI/CD pipelines so violations fail the build
- Review fitness functions quarterly -- they evolve with business needs
- Use architecture decision records to track why constraints were added or relaxed
Workflow
Step 1: Understand the Problem Space
- Identify the domain and its subdomains (core, supporting, generic)
- Map stakeholders and their concerns (scalability, time-to-market, compliance, cost)
- Understand team topology -- how many teams, their autonomy, communication patterns
- Identify hard constraints (regulatory, existing infrastructure, budget)
Step 2: Establish Bounded Contexts
- Use DDD strategic design to draw context boundaries (see ddd-strategic-design.md)
- Define ubiquitous language within each context
- Create a context map showing relationships between contexts
- Validate boundaries against team structure (Conway's Law)
Step 3: Select Architecture Pattern
- Use the decision matrix in pattern-selection.md to evaluate options
- Consider current team maturity and operational capabilities
- Favor the simplest pattern that meets constraints
- Document the decision in an ADR (see adr-guide.md)
Step 4: Define Contracts and Communication
- Choose synchronous (REST, gRPC) vs asynchronous (events, messaging) communication per boundary
- Define event schemas and API contracts
- Establish data ownership rules -- no shared databases across bounded contexts
- Document integration patterns (API gateway, event bus, saga/choreography)
Step 5: Design for Evolution
- Identify key architectural characteristics (performance, scalability, modularity, security)
- Write fitness functions for each characteristic (see evolutionary-architecture.md)
- Plan migration paths -- how does the architecture evolve if assumptions change?
- Set review cadence for architectural decisions
Step 6: Validate Agent-Maintainability
- Verify directory structure follows consistent, discoverable conventions
- Ensure each module has explicit entry points and documented contracts
- Check that dependencies are injected, not hardcoded
- Confirm tests can run per-module without full system setup
- Review naming conventions for grep-ability and clarity
Quick Reference: Architecture Pattern Cheat Sheet
| Pattern | Best For | Watch Out For |
|---|
| Monolith | Small teams, early products, unclear domains | Becomes deployment bottleneck at scale |
| Modular Monolith | Medium teams, well-defined domains, single deployment | Module coupling creep without fitness functions |
| Microservices | Large orgs, independent scaling, autonomous teams | Distributed complexity, operational overhead |
| Serverless | Event-driven workloads, variable traffic, cost-sensitive | Cold starts, vendor lock-in, debugging difficulty |
| Event-Driven | Real-time processing, loose coupling, audit trails | Eventual consistency complexity, debugging async flows |
| CQRS | Read/write asymmetry, complex queries, event sourcing | Added complexity if read/write patterns are symmetric |
| Hexagonal | Testability, swappable infrastructure, long-lived systems | Indirection overhead for small projects |
Quick Reference: ADR Minimal Template
# ADR-NNN: [Short Decision Title]
**Status**: Proposed | Accepted | Deprecated | Superseded by ADR-XXX
## Context
[What forces are at play? What is the problem or opportunity?]
## Decision
[What is the change being made? State it clearly.]
## Consequences
[What becomes easier? What becomes harder? What are the trade-offs?]
Full template and examples in adr-guide.md.
Checklist
Architecture Decision
Agent-Maintainability
ADR Quality
When to Escalate
| Condition | Escalate To |
|---|
| Cross-organization service boundaries requiring governance alignment | Enterprise architect or architecture review board |
| Data sovereignty or regulatory constraints affecting data placement | Legal/compliance team + data architect |
| Migration from monolith to microservices affecting multiple teams | Tech lead + affected team leads for coordination |
| Performance requirements that may need fundamental architecture change | Performance engineering team for load testing validation |
| Vendor lock-in decisions with multi-year cost implications | Engineering leadership + finance for TCO analysis |
| Security architecture (zero-trust, encryption at rest/transit) | Security architect for threat modeling |
| Conflicting bounded context boundaries between teams | Facilitate collaborative Event Storming session |
| Fitness function failures with no clear resolution | Architecture review with senior engineers |
