---
name: architecture
description: |
  Master architecture skill combining system design, architecture patterns,
  ADRs, C4 modeling, and senior architect tools. Use when designing systems,
  making architecture decisions, or reviewing designs.
---

# Architecture Master

Comprehensive architecture skill combining: requirements analysis, trade-off evaluation, ADR documentation, architecture patterns, C4 modeling, and system design.

---

## Quick Reference

| Task | Use Section |
|------|-------------|
| Make architecture decisions | **Architecture Decision Framework** |
| Choose architecture patterns | **Architecture Patterns** |
| Document decisions | **ADRs** |
| Design system architecture | **System Design** |
| Create C4 diagrams | **C4 Model** |
| Review architecture | **Architecture Review** |

---

## Architecture Decision Framework

**Core Principle:** "Requirements drive architecture. Trade-offs inform decisions. ADRs capture rationale."

### Decision Process
1. **Gather Requirements** - Functional and non-functional
2. **Identify Constraints** - Budget, timeline, technology, team
3. **Evaluate Options** - Compare alternatives with trade-off analysis
4. **Document Decision** - ADR with context, decision, consequences
5. **Communicate** - Explain rationale to stakeholders

### Questions to Ask
- What problem are we solving?
- What are the non-functional requirements?
- What constraints must we work within?
- What trade-offs are we willing to make?
- How will this scale?

---

## Architecture Patterns

**When to Use:** Designing new systems or refactoring existing ones.

### Common Patterns

#### Layered Architecture
```
┌─────────────────────┐
│    Presentation     │
├─────────────────────┤
│    Application     │
├─────────────────────┤
│      Domain        │
├─────────────────────┤
│    Infrastructure  │
└─────────────────────┘
```

#### Clean Architecture
```
┌─────────────────────┐
│   External Actors   │
├─────────────────────┤
│   Input Adapters   │
├─────────────────────┤
│   Use Cases        │
├─────────────────────┤
│  Output Adapters   │
├─────────────────────┤
│     Entities       │
└─────────────────────┘
```

#### Hexagonal Architecture (Ports & Adapters)
- **Core:** Business logic (hexagon)
- **Ports:** Interfaces for input/output
- **Adapters:** Implementations of ports

#### Event-Driven Architecture
- Event sources → Event channel → Event processors
- Decoupled, scalable, real-time

#### Microservices Architecture
- Single responsibility per service
- API gateway, service discovery
- Distributed data management

#### Monorepo Architecture
- Shared code, unified tooling
- Atomic commits across projects
- Consistent dependencies

---

## Architecture Decision Records (ADRs)

**When to Use:** Documenting significant architecture decisions.

### ADR Template
```markdown
# ADR-001: [Title]

## Status
Accepted | Deprecated | Superseded

## Context
[Problem statement, constraints, requirements]

## Decision
[Chosen approach]

## Consequences
### Positive
- ...

### Negative
- ...

### Neutral
- ...
```

### When to Create an ADR
- Significant technology choice
- Cross-cutting concerns
- High-cost implementation
- Reversal cost is high

---

## C4 Model

**When to Use:** Visualizing system architecture at different levels.

### C4 Levels

#### Level 1: Context
- Highest level view
- Shows users, systems, relationships
- External systems labeled

#### Level 2: Container
- Applications, databases, services
- Technology choices visible
- Responsibilities defined

#### Level 3: Component
- Major components within a container
- Responsibilities and collaborations
- Implementation details emerging

#### Level 4: Code
- Implementation details
- Class diagrams, function signatures
- Most detailed level

### Tools
- PlantUML
- Mermaid
- Structurizr
- draw.io

---

## System Design

### API Design
- RESTful vs GraphQL vs gRPC
- Versioning strategy
- Authentication/Authorization
- Rate limiting
- Error handling

### Database Design
- Relational vs NoSQL vs NewSQL
- Schema design
- Indexing strategy
- Replication and sharding
- Backup and recovery

### Authentication Patterns
- JWT tokens
- OAuth 2.0 / OIDC
- SAML
- Session management
- MFA integration

### Messaging Patterns
- Point-to-point
- Pub/Sub
- Event streaming
- Message formats (JSON, Avro, Protobuf)

---

## Architecture Review

### Review Checklist
- [ ] Requirements satisfied?
- [ ] Non-functional requirements met?
- [ ] Trade-offs documented?
- [ ] Risks identified and mitigated?
- [ ] Scalability considered?
- [ ] Security baked in?
- [ ] Observability included?
- [ ] Documentation complete?

### Anti-Patterns to Avoid
- Big bang rewrite
- Gold plating
- Architecture astronautism
- Single point of failure
- Premature optimization

---

## Related Skills

| Skill | Use For |
|-------|---------|
| `@database-architect` | Database-specific architecture |
| `@backend-architect` | Backend system design |
| `@c4-architecture-c4-architecture` | C4 diagram creation |
| `@software-architecture` | General software architecture |

---

## Best Practices

1. **Start Simple** - YAGNI, avoid over-engineering
2. **Document Decisions** - ADRs for significant choices
3. **Consider Trade-offs** - Every decision has pros/cons
4. **Plan for Change** - Flexibility over perfection
5. **Communicate Visually** - Diagrams communicate faster
6. **Review Regularly** - Architecture evolves