architect

What this skill does

# Architecture Design

Design system architecture and make strategic technical decisions.

## Core Principle

**Good architecture enables change while maintaining simplicity.**

## Name

han-core:architect - Design system architecture and high-level technical strategy

## Synopsis

```
/architect [arguments]
```

## Architecture vs Planning

**Architecture Design (this skill):**

- Strategic: "How should the system be structured?"
- Component interactions and boundaries
- Technology and pattern choices
- Long-term implications
- System-level decisions

**Technical Planning:**

- Tactical: "How do I implement feature X?"
- Specific implementation tasks
- Execution details
- Short-term focus

**Use /architect when:**

- Designing new systems or subsystems
- Significant system change (new subsystem, major refactor)
- Affects multiple components or teams
- Major refactors affecting multiple components
- Technology selection decisions
- Defining system boundaries and interfaces
- Long-term technical strategy needed
- Need to evaluate multiple approaches
- Decisions have broad impact

**Use /plan when:**

- Implementing within existing architecture
- Implementing specific feature within existing architecture
- Tactical execution planning
- Breaking down known work
- Architecture is already decided
- Task sequencing and execution

## Architecture Process

### 1. Understand Context

**Business context:**

- What problem are we solving?
- Who are the users?
- What are the business goals?
- What are the success metrics?

**Technical context:**

- What exists today?
- What constraints exist?
- What must we integrate with?
- What scale must we support?

**Team context:**

- What's our expertise?
- What can we maintain?
- What's our velocity?

### 2. Gather Requirements

**Functional requirements:**

- What must the system do?
- What are the features?
- What are the user scenarios?

**Non-functional requirements:**

- **Performance**: Response time, throughput
- **Scalability**: Expected load, growth
- **Availability**: Uptime requirements
- **Security**: Compliance, data protection
- **Maintainability**: Team size, skills
- **Cost**: Budget constraints

**Example:**

```markdown
## Requirements

### Functional
- Users can search products by name/category
- Users can add items to cart
- Users can checkout and pay

### Non-Functional
- Search response time < 200ms (p95)
- Support 10,000 concurrent users
- 99.9% uptime
- PCI DSS compliant for payments
- Team of 5 developers can maintain
```

### 3. Identify Constraints

**Technical constraints:**

- Must use existing authentication system
- Must integrate with legacy inventory system
- Database must be PostgreSQL (existing infrastructure)

**Business constraints:**

- Budget for infrastructure
- Must support EU data residency

**Team constraints:**

- Team experienced in Python, less in Go
- No DevOps specialist on team
- Remote team across timezones

### 4. Consider Alternatives

**Never design in a vacuum - consider options:**

**Example: Data storage choice**

**Option 1: PostgreSQL**

- Pros: Team knows it, ACID guarantees, rich query support
- Cons: Vertical scaling limits, setup complexity

**Option 2: MongoDB**

- Pros: Flexible schema, horizontal scaling
- Cons: Team unfamiliar, eventual consistency

**Option 3: DynamoDB**

- Pros: Fully managed, auto-scaling
- Cons: Vendor lock-in, query limitations, cost at scale

**Decision: PostgreSQL**

- Team expertise outweighs scaling concerns
- Can re-evaluate if scale becomes issue
- Faster initial development

### 5. Design System Structure

**Define components and their responsibilities:**

```
┌─────────────────────────────────────────────┐
│             Client Apps                      │
│  (Web, iOS, Android)                         │
└────────────────┬────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────┐
│          API Gateway / Load Balancer         │
└────────────────┬────────────────────────────┘
                 │
        ┌────────┴────────┐
        ▼                 ▼
┌───────────────┐  ┌───────────────┐
│   Auth        │  │   Core API     │
│   Service     │  │   Service      │
└───────┬───────┘  └───────┬───────┘
        │                  │
        │         ┌────────┴────────┐
        │         ▼                 ▼
        │  ┌──────────────┐  ┌──────────────┐
        │  │  PostgreSQL  │  │   Redis      │
        │  │  (Primary)   │  │   (Cache)    │
        │  └──────────────┘  └──────────────┘
        │
        ▼
┌───────────────┐
│   User DB     │
└───────────────┘
```

**Component descriptions:**

```markdown
## Components

### API Gateway
**Responsibility:** Route requests, rate limiting, authentication
**Technology:** Nginx
**Dependencies:** Auth Service, Core API Service
**Scale:** 2-3 instances behind load balancer

### Auth Service
**Responsibility:** User authentication, session management, JWT issuing
**Technology:** Python (Flask), PostgreSQL
**API:** REST
**Scale:** Stateless, 2-N instances

### Core API Service
**Responsibility:** Business logic, data access, external integrations
**Technology:** Python (FastAPI), PostgreSQL, Redis
**API:** REST
**Scale:** Stateless, 2-N instances

### PostgreSQL
**Responsibility:** Primary data store
**Scale:** Primary with read replica

### Redis
**Responsibility:** Session storage, caching, rate limiting
**Scale:** Cluster mode (3 nodes)
```

### 6. Define Interfaces

**API contracts:**

```markdown
## API Design

### POST /api/auth/login
**Purpose:** Authenticate user, issue JWT

**Request:**
```json
{
  "email": "[email protected]",
  "password": "secure_password"
}
```

**Response (200):**

```json
{
  "token": "eyJ...",
  "user": {
    "id": "123",
    "email": "[email protected]",
    "name": "John Doe"
  }
}
```

**Errors:**

- 400: Invalid request
- 401: Invalid credentials
- 429: Rate limit exceeded

```

### 7. Plan for Failure

**What can go wrong?**
- Database unavailable
- External API down
- Network partition
- High load
- Data corruption

**Mitigation strategies:**
- Retry with exponential backoff
- Circuit breakers for external services
- Graceful degradation
- Health checks and monitoring
- Database backups

**Example:**
```markdown
## Failure Scenarios

### Database Unavailable
**Impact:** Cannot read/write data
**Mitigation:**
- Read replica failover (automated)
- Circuit breaker after 3 failures
- Cache serves stale data for 5 minutes
- User sees degraded experience message
**Recovery:** Manual failover to replica, fix primary

### External Payment API Down
**Impact:** Cannot process payments
**Mitigation:**
- Retry 3 times with exponential backoff
- Queue payments for later processing
- User notified of delay
- Alert on-call engineer
**Recovery:** Process queued payments once API recovers
```

### 8. Document Decisions

**Architecture Decision Record (ADR):**

```markdown
# ADR-001: Use PostgreSQL for Primary Database

**Status:** Accepted
**Date:** 2024-01-15
**Deciders:** Tech Lead, Backend Team

## Context

We need to choose a primary database for user data, products, and orders.

Requirements:
- Strong consistency (ACID)
- Complex queries (joins, aggregations)
- < 200ms query time for 90% of queries
- Support 100k users initially

## Decision

Use PostgreSQL as primary database.

## Alternatives Considered

### MongoDB
- **Pros:** Flexible schema, horizontal scaling
- **Cons:** Team unfamiliar, eventual consistency issues
- **Why not:** Team expertise more valuable than flexibility

### DynamoDB
- **Pros:** Managed service, auto-scaling
- **Cons:** Vendor lock-in, limited query capability, cost
- **Why not:** Query limitations would hurt development velocity

### MySQL
- **Pros:** Similar to PostgreSQL, team knows it
- **Cons:** Less feature-rich than PostgreSQL
- **Why not:** PostgreSQL offers JSON support, better full-text search

## Consequences

**Positive:**
- Team can be productive immediately
- Strong consis