/architect

name: architect
description: Design system architecture and high-level technical strategy

allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash

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:**

## 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:**

## 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:**

## API Design

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

**Request:**
```json
{
  "email": "user@example.com",
  "password": "secure_password"
}

**Response (200):**

{
  "token": "eyJ...",
  "user": {
    "id": "123",
    "email": "user@example.com",
    "name": "John Doe"
  }
}

**Errors:**