Architecture Documenter — Worked Examples

Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.

Externalized from the agent definition per the few-shot-examples rule (#1587).

Step 1: Software Architecture Document (SAD) Creation

Read template from the agent-owned install operation:

~/.local/share/ai-writing-guide/agentic/code/frameworks/sdlc-complete/templates/analysis-design/software-architecture-doc-template.md

Structure SAD:

---
title: Software Architecture Document
version: 1.0
status: DRAFT | REVIEWED | APPROVED | BASELINED
date: 2025-10-15
project: {project-name}
phase: Elaboration
primary-author: architecture-designer
reviewers: [security-architect, test-architect, requirements-analyst]
---

# Software Architecture Document

## 1. Architectural Drivers

### Quality Attributes

**Performance:**
- Response time: p95 < 500ms for API requests
- Throughput: 1,000 requests/second sustained
- Database queries: p99 < 200ms

**Scalability:**
- Horizontal scaling: 10,000 concurrent users
- Auto-scaling: Triggers at 70% CPU utilization
- Data volume: 100M transactions/month

**Security:**
- Authentication: OAuth 2.0 with JWT tokens
- Authorization: Role-based access control (RBAC)
- Encryption: TLS 1.3 in transit, AES-256 at rest

**Availability:**
- Uptime: 99.9% SLA (43 min/month downtime)
- Multi-region: Active-active deployment
- Failover: Automatic within 30 seconds

### Constraints

**Technical:**
- Must use existing PostgreSQL database
- Must integrate with legacy SOAP API
- Cloud provider: AWS only

**Organizational:**
- Team expertise: Node.js, Python
- Budget: $10K/month infrastructure
- Timeline: 6 months to production

**Compliance:**
- GDPR compliance required
- SOC 2 Type II certification

## 2. Component Decomposition

### Logical View

\```text
┌─────────────────────────────────────────┐
│         Presentation Layer              │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐ │
│  │ Web App │  │ Mobile  │  │ Admin   │ │
│  │ (React) │  │ (Native)│  │ Portal  │ │
│  └─────────┘  └─────────┘  └─────────┘ │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│           API Gateway Layer             │
│        (Authentication, Rate Limiting)  │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│         Application Services            │
│  ┌──────────┐  ┌──────────┐  ┌────────┐│
│  │ User     │  │ Product  │  │Payment ││
│  │ Service  │  │ Service  │  │Service ││
│  └──────────┘  └──────────┘  └────────┘│
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│            Data Layer                   │
│  ┌──────────┐  ┌──────────┐  ┌────────┐│
│  │PostgreSQL│  │  Redis   │  │  S3    ││
│  │   (RDS)  │  │ (Cache)  │  │(Files) ││
│  └──────────┘  └──────────┘  └────────┘│
└─────────────────────────────────────────┘
\```

### Physical View

**Microservices:**
1. **User Service**
   - Responsibilities: Authentication, user management, profiles
   - Technology: Node.js (Express)
   - Database: PostgreSQL (users table)
   - APIs: REST, Internal gRPC

2. **Product Service**
   - Responsibilities: Product catalog, inventory, search
   - Technology: Python (FastAPI)
   - Database: PostgreSQL (products table), Redis (cache)
   - APIs: REST, GraphQL

3. **Payment Service**
   - Responsibilities: Payment processing, subscriptions
   - Technology: Node.js (Express)
   - Integrations: Stripe API, legacy SOAP billing system
   - APIs: REST (internal only)

**Shared Components:**
- **API Gateway:** Kong (rate limiting, authentication, routing)
- **Message Queue:** RabbitMQ (async events)
- **Cache:** Redis (session, data caching)
- **Storage:** S3 (user uploads, backups)

## 3. Deployment Architecture

### Environments

**Development:**
- Deployed: Local Docker Compose
- Database: Local PostgreSQL
- Purpose: Developer testing

**Test/Staging:**
- Deployed: AWS ECS (Fargate)
- Database: RDS PostgreSQL (t3.medium)
- Purpose: Integration testing, UAT

**Production:**
- Deployed: AWS ECS (Fargate), Multi-AZ
- Database: RDS PostgreSQL (r6g.xlarge), Multi-AZ
- Regions: us-east-1 (primary), us-west-2 (failover)
- Load Balancer: Application Load Balancer (ALB)
- CDN: CloudFront (static assets)

### Deployment Diagram

\```mermaid
graph TB
    Users[Users] --> CF[CloudFront CDN]
    CF --> ALB[Application Load Balancer]
    ALB --> ECS1[ECS Cluster us-east-1]
    ALB --> ECS2[ECS Cluster us-west-2]

    ECS1 --> User1[User Service]
    ECS1 --> Product1[Product Service]
    ECS1 --> Payment1[Payment Service]

    User1 --> RDS1[(RDS Primary)]
    Product1 --> RDS1
    Product1 --> Redis1[Redis Cache]
    Payment1 --> Stripe[Stripe API]

    RDS1 -.Replication.-> RDS2[(RDS Replica us-west-2)]

    ECS2 --> User2[User Service]
    ECS2 --> Product2[Product Service]
    User2 --> RDS2
    Product2 --> RDS2
\```

## 4. Technology Stack

| Layer | Technology | Rationale |
|-------|------------|-----------|
| **Frontend** | React 18 | Team expertise, component reusability |
| **API Gateway** | Kong | Open-source, plugin ecosystem, rate limiting |
| **Backend** | Node.js, Python | Team expertise, async I/O (Node), ML libs (Python) |
| **Database** | PostgreSQL 15 | ACID compliance, existing expertise, JSON support |
| **Cache** | Redis 7 | High performance, pub/sub, session management |
| **Message Queue** | RabbitMQ | Reliable delivery, dead-letter queues |
| **Container** | Docker | Standardization, portability |
| **Orchestration** | AWS ECS Fargate | Managed, no server management, auto-scaling |
| **CI/CD** | GitHub Actions | Integrated with repo, free for open source |
| **Monitoring** | Datadog | APM, logs, metrics, alerts |

## 5. Integration Architecture

### External Systems

| System | Protocol | Purpose | SLA |
|--------|----------|---------|-----|
| Stripe API | REST (HTTPS) | Payment processing | 99.99% |
| Legacy Billing | SOAP | Subscription management | 99.5% |
| Email Service | REST (SendGrid) | Transactional emails | 99.9% |
| Analytics | REST (Segment) | User behavior tracking | 99.0% |

### Integration Patterns

**API Integration:**
- REST for synchronous requests
- gRPC for service-to-service (internal)
- GraphQL for flexible client queries (Product Service)

**Event-Driven:**
- RabbitMQ for async events (order placed, user registered)
- Publish/subscribe pattern
- Dead-letter queue for failed messages

**Legacy Integration:**
- SOAP adapter service for legacy billing system
- Fallback to manual processing if SOAP unavailable

## 6. Security Architecture

### Authentication Flow

\```mermaid
sequenceDiagram
    participant U as User
    participant G as API Gateway
    participant A as Auth Service
    participant DB as User DB

    U->>G: POST /login (username, password)
    G->>A: Forward credentials
    A->>DB: Verify credentials (bcrypt hash)
    DB-->>A: User validated
    A->>A: Generate JWT token
    A-->>G: Return JWT (expires 24h)
    G-->>U: Return JWT
    U->>G: GET /api/profile (JWT in header)
    G->>G: Validate JWT signature
    G->>Product: Forward request (JWT validated)
\```

### Authorization (RBAC)

**Roles:**
- **Admin:** Full access
- **Manager:** Read/write products, read users
- **User:** Read own profile, read products

**Implementation:**
- JWT claims include user roles
- API Gateway validates roles before routing
- Services enforce role-based permissions

### Data Protection

- **At Rest:** AES-256 encryption (RDS, S3)
- **In Transit:** TLS 1.3 (all external APIs), TLS 1.2 (service-to-service)
- **Secrets:** AWS Secrets Manager (API keys, DB credentials)
- **PII:** Masked in logs, encrypted in database

## 7. Data Architecture

### Data Model

\```sql
-- Users table
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    username VARCHAR(50) UNIQUE NOT NULL,
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    role VARCHAR(20) NOT NULL,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Products table
CREATE TABLE products (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(255) NOT NULL,
    description TEXT,
    price DECIMAL(10, 2) NOT NULL,
    inventory INT NOT NULL DEFAULT 0,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Orders table
CREATE TABLE orders (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id),
    total DECIMAL(10, 2) NOT NULL,
    status VARCHAR(20) NOT NULL,
    created_at TIMESTAMPTZ DEFAULT NOW()
);
\```

### Data Flow

1. **Write Path:** Client → API Gateway → Service → PostgreSQL → Invalidate Redis cache
2. **Read Path (Cache Hit):** Client → API Gateway → Service → Redis → Return cached data
3. **Read Path (Cache Miss):** Client → API Gateway → Service → PostgreSQL → Write to Redis → Return data

### Migration Strategy

- **Tools:** Flyway for schema migrations
- **Process:** Blue-green deployment for schema changes
- **Rollback:** Migration down scripts for every up script

## 8. Key Decisions (ADRs)

| ADR | Title | Status | Date |
|-----|-------|--------|------|
| ADR-001 | Use PostgreSQL for primary database | Accepted | 2025-10-01 |
| ADR-002 | Use Kong for API Gateway | Accepted | 2025-10-05 |
| ADR-003 | Microservices vs. Monolith | Accepted | 2025-10-02 |
| ADR-004 | gRPC for service-to-service communication | Accepted | 2025-10-08 |

**See:** `.aiwg/architecture/adr/` for detailed ADR documents

## Sign-Off

**Required Approvals:**
- [ ] Software Architect: {APPROVED | CONDITIONAL | PENDING} - {name, date}
- [ ] Security Architect: {APPROVED | CONDITIONAL | PENDING} - {name, date}
- [ ] Test Architect: {APPROVED | CONDITIONAL | PENDING} - {name, date}
- [ ] Requirements Analyst: {APPROVED | CONDITIONAL | PENDING} - {name, date}

**Conditions (if conditional):**
1. {Condition description} - Owner: {role} - Due: {date}

**Outstanding Concerns:**
1. {Concern description} - Raised by: {role} - Severity: {HIGH | MEDIUM | LOW}

Step 2: Architecture Decision Records (ADRs)

Read template from the agent-owned install operation:

~/.local/share/ai-writing-guide/agentic/code/frameworks/sdlc-complete/templates/analysis-design/architecture-decision-record-template.md

Create ADR:

# ADR-001: Use PostgreSQL for Primary Database

## Status
**Accepted** (2025-10-01)

## Context
We need to select a primary database for the application. Key requirements:
- ACID compliance for financial transactions
- Support for complex queries (joins, aggregations)
- JSON data type support for flexible schemas
- Team has existing PostgreSQL expertise
- Budget constraint: $500/month database costs

## Decision
Use PostgreSQL 15 (AWS RDS) as the primary database.

## Rationale
**Considered alternatives:**
1. **MongoDB:** Flexible schema, but lacks ACID for multi-document transactions (required for payments)
2. **MySQL:** ACID compliant, but team has stronger PostgreSQL expertise
3. **DynamoDB:** AWS-native, but limited query flexibility, higher learning curve

**Why PostgreSQL:**
- ACID compliance meets financial transaction requirements
- JSON/JSONB support provides schema flexibility where needed
- Team has 3+ years PostgreSQL experience (reduces risk)
- RDS provides managed service (backups, failover, scaling)
- Cost: $300/month for r6g.xlarge (within budget)

## Consequences

**Positive:**
- Strong consistency for transactions
- Mature ecosystem (ORMs, tools, extensions)
- Vertical scaling path (up to 32 vCPUs, 256GB RAM)
- Multi-AZ replication for high availability

**Negative:**
- Vertical scaling limits (may need sharding for > 10M users)
- Less suited for unstructured data (vs. document databases)
- Requires careful index management for performance

**Mitigations:**
- Use read replicas for scaling reads
- Implement caching layer (Redis) for hot data
- Plan for horizontal sharding if scale exceeds vertical limits

## References
- [PostgreSQL vs. MongoDB](https://example.com/comparison)
- [AWS RDS PostgreSQL Pricing](https://aws.amazon.com/rds/postgresql/pricing/)
- Team Expertise Assessment (project-local reference)

## Related Decisions
- ADR-002: API Gateway selection
- ADR-004: gRPC for service-to-service communication

Step 4: Feedback and Annotations

## 3. Deployment Architecture

<!-- ARCH-DOC: EXCELLENT - Clear multi-region deployment strategy -->

### Production
- Deployed: AWS ECS (Fargate), Multi-AZ
- Database: RDS PostgreSQL (r6g.xlarge), Multi-AZ
- Regions: us-east-1 (primary), us-west-2 (failover)

<!-- ARCH-DOC: QUESTION - How is failover triggered? Automatic or manual? Please specify failover time (RTO/RPO). -->

<!-- ARCH-DOC: SUGGESTION - Add disaster recovery section with backup strategy and restoration procedures. -->

## 4. Technology Stack

| Layer | Technology | Rationale |
|-------|------------|-----------|
| **Backend** | Node.js, Python | Team expertise <!-- ARCH-DOC: APPROVED - Clear rationale -->
| **Database** | PostgreSQL 15 | ACID compliance <!-- ARCH-DOC: GOOD - Should reference ADR-001 -->
| **Cache** | Redis 7 | High performance <!-- ARCH-DOC: NEEDS DETAIL - What specific Redis features used? (pub/sub, sessions, data cache?) -->

<!-- ARCH-DOC: WARNING - No monitoring/observability tools listed. Add section on Datadog, CloudWatch, or equivalent. -->