/architect [arguments]

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

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

## 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)

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

 
**Response (200):**
 

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

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

# 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 consistency guarantees
-Rich query capabilities
-JSON support for flexible data
 
**Negative:**
-Vertical scaling limits (mitigated: can add read replicas)
-More complex than managed services (mitigated: use RDS)
-Higher operational overhead
 
**Trade-offs:**
-Chose familiarity over horizontal scaling
-Chose rich queries over eventual consistency
-Can re-evaluate if scale requirements change
 
## Validation
 
-Team confirmed expertise in PostgreSQL
-Load testing shows meets performance requirements
-Cost analysis shows acceptable for first year

# Architecture Design: [System/Feature Name]
 
## Context
 
### Problem Statement
[What business problem are we solving?]
 
### Goals
[What are we trying to achieve?]
 
### Non-Goals
[What are we explicitly NOT trying to achieve?]
 
### Requirements
 
**Functional:**
-[Requirement 1]
-[Requirement 2]
 
**Non-Functional:**
-Performance: [e.g., < 200ms response time]
-Scalability: [e.g., handle 10k concurrent users]
-Security: [e.g., PCI compliance]
-Maintainability: [e.g., easy to modify]
 
### Constraints
[Technical, time, resource, or business constraints]
 
## Current Architecture
[What exists today? What needs to change?]
 
## Proposed Architecture
 
### High-Level Design
 
[Diagram or description of system components]
 

 
### Components
 
#### Component A
**Responsibility:** [What it does]
**Interface:** [How others interact with it]
**Dependencies:** [What it depends on]
**Technology:** [Implementation stack]
 
#### Component B
[Similar structure...]
 
### Data Flow
[How data moves through the system]
 
### API Design
[Key endpoints, schemas, contracts]
 
### Data Model
[Database schema, key entities]
 
### Security Model
[Authentication, authorization, data protection]
 
## Alternative Approaches Considered
 
### Alternative 1: [Approach name]
**Pros:**
- [Advantage 1]
- [Advantage 2]
 
**Cons:**
- [Disadvantage 1]
- [Disadvantage 2]
 
**Why not chosen:** [Reasoning]
 
### Alternative 2: [Another approach]
[Similar structure...]
 
## Decision Rationale
 
### Why This Architecture?
[Explain the key decisions and trade-offs]
 
### Trade-offs Accepted
[What we gave up for what benefits]
 
### Assumptions
[What we're assuming to be true]
 
## Implementation Strategy
 
### Phase 1: [Foundation]
[What to build first]
 
### Phase 2: [Core Features]
[Next phase]
 
### Phase 3: [Enhancement]
[Final phase]
 
### Migration Strategy
[If replacing existing system, how to transition?]
 
## Risks & Mitigation
 
| Risk | Impact | Probability | Mitigation |
|------|--------|-------------|------------|
| [Risk 1] | High | Medium | [How to mitigate] |
| [Risk 2] | Medium | Low | [How to mitigate] |
 
## Testing Strategy
[How will we validate this architecture?]
 
## Monitoring & Observability
[How will we know if it's working?]
 
## Success Metrics
[How will we measure success?]
 
## Open Questions
[What still needs to be resolved?]
 
## References
[Links to research, related docs, RFCs]

BAD: Microservices from day 1 with 20 services
GOOD: Start with monolith, split when needed

GOOD:
- Auth Service: Authentication only
- User Service: User profile management
- Order Service: Order processing
 
BAD:
- God Service: Does everything

// BAD: Tight coupling
class OrderService {
  constructor(private db: PostgresDatabase) {}
}
// GOOD: Loose coupling
class OrderService {
  constructor(private db: Database) {}  // Interface
}

GOOD:
user/
  - create_user.ts
  - update_user.ts
  - delete_user.ts
  - user_repository.ts
 
BAD:
create/
  - create_user.ts
  - create_order.ts
update/
  - update_user.ts
  - update_order.ts

// BAD: Implicit dependency
function processOrder(orderId: string) {
  const db = global.database  // Where does this come from?
  // ...
}
// GOOD: Explicit dependency
function processOrder(
  orderId: string,
  db: Database,
  logger: Logger
) {
  // Dependencies are clear
}

// BAD: Silent failure
function divide(a: number, b: number) {
  if (b === 0) return 0  // Wrong!
  return a / b
}
// GOOD: Fail fast
function divide(a: number, b: number) {
  if (b === 0) {
    throw new Error('Division by zero')
  }
  return a / b
}

// BAD: Hard to test
class OrderService {
  processOrder(orderId: string) {
    const db = new PostgresDatabase()  // Can't mock
    const api = new PaymentAPI()       // Can't mock
    // ...
  }
}
// GOOD: Easy to test
class OrderService {
  constructor(
    private db: Database,      // Can inject mock
    private api: PaymentAPI    // Can inject mock
  ) {}
  processOrder(orderId: string) {
    // ...
  }
}

┌─────────────────────┐
│  Presentation       │ (UI, API controllers)
├─────────────────────┤
│  Business Logic     │ (Domain, services)
├─────────────────────┤
│  Data Access        │ (Repositories, ORMs)
├─────────────────────┤
│  Database           │ (Storage)
└─────────────────────┘

        ┌───────────────────────┐
        │   External Systems    │
        │  (UI, DB, APIs)       │
        └──────────┬────────────┘
                   │
        ┌──────────▼────────────┐
        │      Adapters         │ (Implementation)
        │  (REST, PostgreSQL)   │
        └──────────┬────────────┘
                   │
        ┌──────────▼────────────┐
        │       Ports           │ (Interfaces)
        │  (IUserRepo, IAuth)   │
        └──────────┬────────────┘
                   │
        ┌──────────▼────────────┐
        │    Core Domain        │ (Business logic)
        │    (Pure logic)       │
        └───────────────────────┘

┌─────────┐  ┌─────────┐  ┌─────────┐
│  User   │  │  Order  │  │ Payment │
│ Service │  │ Service │  │ Service │
└────┬────┘  └────┬────┘  └────┬────┘
     │            │            │
     └────────────┴────────────┘
                  │
          ┌───────▼────────┐
          │  Message Bus   │
          │  (Event-driven)│
          └────────────────┘

┌─────────┐       ┌─────────────┐       ┌─────────┐
│Producer │──────▶│ Event Bus   │──────▶│Consumer │
└─────────┘       └─────────────┘       └─────────┘

BAD: Build microservices for 100 users
GOOD: Start with monolith, split when needed

BAD: "I want to learn Kubernetes, let's use it"
GOOD: "Kubernetes fits our scale needs"

BAD: Service A can't deploy without Service B
GOOD: Services are independently deployable

BAD: Any code can call any other code
GOOD: Clear layers and boundaries

BAD: Spend months on perfect architecture
GOOD: Design enough to start, iterate