System Architect Skill
Design scalable, maintainable software systems.
When to Use
- Designing new system/feature
- Evaluating architectural trade-offs
- API/database/caching decisions
- Commands:
/architect, /design, /system-design
Capabilities
1. System Design
- Microservices vs monolith
- API design (REST, GraphQL, gRPC)
- DB selection & schema design
- Caching & message queues
- Event-driven systems
2. Scalability
- Horizontal/vertical scaling
- Load balancing & sharding
- CDN & auto-scaling
3. Reliability
- HA patterns & DR planning
- Circuit breaker & retry
- Graceful degradation
4. Security
- Auth systems (OAuth, JWT, SSO)
- Authorization (RBAC, ABAC)
- API security & encryption
Architecture Decision Process
Step 1: Requirements
1. Functional: Core features, workflows, integrations
2. Non-Functional: Performance, scalability, availability, security, budget
3. Constraints: Tech stack, team expertise, timeline, existing systems
Step 2: Pattern Selection
Reference patterns.json for patterns, tech recommendations, trade-offs.
Step 3: Design Doc Template
# Architecture Design Document
## 1. Overview
[High-level description]
## 2. Goals & Non-Goals
## 3. Architecture
### System Diagram
### Components
| Component | Responsibility | Technology |
|-----------|---------------|------------|
### Data Flow
## 4. Technical Decisions
### Decision 1: [Title]
- Context | Options | Decision | Rationale
## 5. API Design
## 6. Data Model
## 7. Security
## 8. Scalability
## 9. Monitoring & Observability
## 10. Risks & Mitigations
Pattern Reference
Communication
| Pattern | Use When | Trade-offs |
|---|
| Sync REST | Simple CRUD | Tight coupling |
| Async Queue | Decoupling | Complexity |
| Event Sourcing | Audit trail | Storage |
| CQRS | Read/write opt | Eventual consistency |
| GraphQL | Flexible queries | Caching |
| gRPC | High perf | Browser support |
Data
| Pattern | Use When | Trade-offs |
|---|
| SQL | ACID, complex queries | Scaling |
| NoSQL | Flexibility, scale | Consistency |
| Cache-aside | Read-heavy | Invalidation |
Resilience
| Pattern | Purpose |
|---|
| Circuit Breaker | Prevent cascade failures |
| Retry w/ Backoff | Handle transient failures |
| Bulkhead | Isolate failures |
| Timeout | Prevent hanging |
| Fallback | Graceful degradation |
Project Structures
Reference structures.json for:
- Python: FastAPI, Django
- TypeScript: Next.js, React, Express
- Java: Spring Boot
- Go: Standard Layout
Tech Stack Recommendations
Web Apps
Frontend: React/Next.js, Vue/Nuxt, Angular
Backend: Node.js, Go, Python (FastAPI), Rust
DB: PostgreSQL, MongoDB
Cache: Redis | Queue: RabbitMQ, SQS, Kafka
Search: Elasticsearch, Meilisearch
Real-time
WebSocket: Socket.io, ws
Pub/Sub: Redis, Kafka
Data-Intensive
Processing: Spark, Flink
Storage: S3, GCS
Warehouse: Snowflake, BigQuery
Pipeline: Airflow, Dagster
Diagramming
ASCII Component
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Client │────▶│ API Gateway │────▶│ Services │
└─────────────┘ └─────────────┘ └─────────────┘
│ │
▼ ▼
┌─────────────┐ ┌─────────────┐
│ Auth │ │ Database │
└─────────────┘ └─────────────┘
Mermaid Sequence
sequenceDiagram
Client->>API: Request
API->>Auth: Validate Token
Auth-->>API: Valid
API->>Service: Process
Service->>DB: Query
DB-->>Service: Data
Service-->>API: Response
API-->>Client: Response
Evaluation Criteria
| Criterion | Weight | Description |
|---|
| Scalability | High | Can it handle growth? |
| Maintainability | High | Easy to modify/debug? |
| Performance | Med-High | Meets latency/throughput? |
| Cost | Medium | Infra + dev cost |
| Security | High | Meets requirements? |
| Complexity | Medium | Team can build/operate? |
Output Templates
Quick Decision
**Question**: [What needs deciding]
**Recommendation**: [Approach]
**Rationale**: [Why]
**Trade-offs**: [Accepting]
**Alternatives**: [Other options]
Integration
- code-reviewer: Validate impl matches design
- postgres-mcp: DB schema design
- jira-bridge: Create impl tickets
