architecture

Architecture Design Skill

Reusable workflow extracted from baccio-tech-architect expertise.

Design scalable, maintainable, secure system architectures using DDD, Clean Architecture, cloud-native patterns.

When to Use

New system design | Legacy modernization | Stack selection | Scalability planning | Microservices design | Cloud migration | Debt evaluation | Architecture review

Workflow

| Step | Actions | |------|---------| | 1. Requirements | Gather functional/NFRs, constraints (budget, timeline, team), scale (users, data, traffic), compliance | | 2. Domain Model | Apply DDD: bounded contexts, aggregates, entities, ubiquitous language | | 3. Pattern Selection | Choose style (monolith/microservices/serverless), patterns (CQRS, Event Sourcing, Saga), Clean Architecture | | 4. Tech Stack | Evaluate options vs requirements, team expertise, vendor lock-in, cost, compliance | | 5. Scalability | Horizontal/vertical scaling, caching (app/CDN/DB), load balancing, sharding, geo-distribution | | 6. Security | Zero-Trust, auth/authz, encryption (at-rest/in-transit), boundaries, defense-in-depth | | 7. Observability | Structured logging, metrics (Prometheus, CloudWatch), tracing, dashboards, alerts | | 8. Documentation | ADRs, C4 diagrams, API contracts/versioning, deployment architecture, capacity planning |

Inputs

• Business requirements (problem to solve)
• NFRs (performance, security, compliance)
• Scale (current/projected users, data, traffic)
• Constraints (budget, timeline, team skills, existing systems)
• Compliance (GDPR, HIPAA, SOC2, etc.)

Outputs

• Architecture Blueprint
• ADRs (decision records with rationale)
• Tech Stack Recommendation
• Scalability Plan
• Security Architecture
• Deployment Diagrams
• Migration Roadmap

Architecture Patterns

Styles

| Pattern | Traits | |---------|--------| | Monolithic | Single deployable, simpler, less scalable | | Microservices | Independent services, complex, highly scalable | | Serverless | Event-driven, pay-per-use, elastic | | Modular Monolith | Compromise between monolith and microservices | | SOA | Enterprise service bus |

Design Patterns

| Pattern | Use Case | |---------|----------| | DDD | Bounded contexts, aggregates, entities | | Clean Architecture | Dependency inversion, layers, boundaries | | CQRS | Command Query Responsibility Segregation | | Event Sourcing | Event log as source of truth | | Saga | Distributed transactions | | API Gateway | Single entry point | | BFF | Backend for Frontend (API per client) |

Communication

• Sync: REST, GraphQL, gRPC
• Async: Kafka, RabbitMQ, SQS
• Pub/Sub: Event-driven
• RPC: Request-Reply

ADR Template

## Decision: [Technology/Pattern]

### Context
[Problem, constraints]

### Options
1. **Option A**: [Pros/Cons/Cost]
2. **Option B**: [Pros/Cons/Cost]

### Decision
[Choice with rationale]

### Consequences
- Positive: [Benefits]
- Negative: [Drawbacks]
- Mitigation: [Actions]

NFR Checklist

See [nfr-checklist.md](./nfr-checklist.md) for performance, availability, security, observability, maintainability requirements.

Example

Input: E-commerce platform, 10K users, 99.9% uptime, PCI DSS

Steps:
1. Requirements: User accounts, catalog, cart, checkout
2. Domain: User, Product, Cart, Order contexts
3. Pattern: Microservices + API Gateway + Event-driven
4. Stack: Node.js, PostgreSQL, Redis, Kafka, AWS ECS/RDS
5. Scale: Horizontal (ECS), read replicas, CDN
6. Security: OAuth2+JWT, PCI gateway, encryption
7. Observability: CloudWatch, X-Ray, Grafana
8. Docs: ADRs, C4 diagrams, API specs

Output: Blueprint + ADRs + diagrams

Tech Stack Evaluation

| Criterion | Weight | Option A | Option B | Option C | |-----------|--------|----------|----------|----------| | Team expertise | 20% | 8/10 | 5/10 | 6/10 | | Scalability | 25% | 9/10 | 7/10 | 8/10 | | Cost | 15% | 6/10 | 9/10 | 7/10 | | Community | 10% | 9/10 | 8/10 | 6/10 | | Compliance | 15% | 8/10 | 7/10 | 9/10 | | Lock-in | 15% | 7/10 | 5/10 | 8/10 | | Total | 100% | 7.9 | 6.9 | 7.5 |

Related Agents

• baccio-tech-architect - Full reasoning/decision-making
• luca-security-expert - Security validation
• dan-engineering-gm - Leadership alignment
• marco-devops-engineer - Infrastructure/deployment
• domik-mckinsey-strategic-decision-maker - Strategic decisions

Engineering Fundamentals

• Document ADRs for all major decisions
• Apply proven design patterns
• Trade studies before decisions
• Technical spikes for high-risk unknowns
• Design for NFRs from day one
• Infrastructure as Code
• GitOps workflows