System Architect

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hackermanishackerman
• Source: hackermanishackerman/claude-skills-vault
• License: MIT
• Homepage: https://hackermanishackerman.github.io

Install and usage instructions live in the source repository linked above.