arch-builder

Architecture Builder

Purpose

Generate Technical Architecture documents that translate product requirements into system design. Architecture docs define the COMPONENTS, CONNECTIONS, and CONSTRAINTS that shape how the system is built.

When to Use

Activate this skill when:

• PRD is complete and needs technical translation
• Designing system components and data flow
• User says "architecture", "system design", or "how should this be built"
• Making technology stack decisions
• Defining API contracts and integration patterns

Wolfejam Workflow Position

Sys Reqs → PRD → [3. ARCHITECTURE] → project.faf → WJTTC-TESTS.md → Code → Test → GOLD Code
                       ↑
                    YOU ARE HERE

Architecture Document Structure

Template

# Technical Architecture: {Project Name}

**Version:** 1.0
**Date:** {Date}
**Architect:** {Name} (via Claude)
**Status:** Draft | Review | Approved

---

## 1. Architecture Overview

### 1.1 System Context
[High-level view: what the system is and how it fits in the larger ecosystem]

### 1.2 Architecture Style
[e.g., Monolith, Microservices, Serverless, Event-Driven, Hybrid]

### 1.3 Key Design Decisions
| Decision | Choice | Rationale |
|----------|--------|-----------|
| [Decision 1] | [Choice] | [Why] |
| [Decision 2] | [Choice] | [Why] |

---

## 2. System Components

### 2.1 Component Diagram

┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Client │────▶│ API │────▶│ Database │ │ (Browser) │ │ (Server) │ │ (Storage) │ └─────────────┘ └─────────────┘ └─────────────┘

### 2.2 Component Specifications

#### Component: {Name}
**Responsibility:** [What it does]
**Technology:** [Stack/framework]
**Interfaces:** [APIs it exposes/consumes]
**Dependencies:** [Other components it relies on]

#### Component: {Name}
...

---

## 3. Data Architecture

### 3.1 Data Model

┌──────────────┐ ┌──────────────┐ │ User │ │ Item │ ├──────────────┤ ├──────────────┤ │ id │───┐ │ id │ │ email │ │ │ name │ │ created_at │ └──▶│ user_id (FK) │ └──────────────┘ └──────────────┘

### 3.2 Data Flow
[How data moves through the system]

### 3.3 Data Storage
| Data Type | Storage | Reasoning |
|-----------|---------|-----------|
| [Type 1] | [Store] | [Why] |
| [Type 2] | [Store] | [Why] |

---

## 4. API Design

### 4.1 API Style
[REST | GraphQL | gRPC | WebSocket | Hybrid]

### 4.2 Key Endpoints

#### POST /api/{resource}
**Purpose:** [What it does]
**Request:**
```json
{
  "field": "value"
}

Response:

{
  "id": "123",
  "status": "created"
}

GET /api/{resource}/{id}

...

---

5. Technology Stack

5.1 Stack Summary

Layer	Technology	Version	Rationale
Frontend	[Tech]	[Ver]	[Why]
Backend	[Tech]	[Ver]	[Why]
Database	[Tech]	[Ver]	[Why]
Hosting	[Tech]	[Ver]	[Why]
CI/CD	[Tech]	[Ver]	[Why]

5.2 Dependencies

{
  "dependencies": {
    "package": "version"
  }
}

---

6. Security Architecture

6.1 Authentication

[How users prove identity: OAuth, JWT, Sessions, etc.]

6.2 Authorization

[How access is controlled: RBAC, ABAC, Scopes]

6.3 Data Protection

• At rest: [Encryption method]
• In transit: [TLS, etc.]
• Secrets: [Management approach]

---

7. Infrastructure

7.1 Deployment Architecture

┌─────────────────────────────────────┐
│           Cloud Provider            │
├─────────────┬─────────────┬─────────┤
│   CDN       │   Compute   │   DB    │
│ (Static)    │  (Server)   │ (Data)  │
└─────────────┴─────────────┴─────────┘

7.2 Environments

Environment	Purpose	URL
Development	Local testing	localhost
Staging	Pre-production	staging.example.com
Production	Live users	example.com

7.3 Scaling Strategy

[Horizontal | Vertical | Auto-scaling rules]

---

8. Integration Points

8.1 External Services

Service	Purpose	Protocol	Auth
[Service 1]	[Use]	[API type]	[Auth method]
[Service 2]	[Use]	[API type]	[Auth method]

8.2 Internal Integrations

[How components communicate internally]

---

9. Non-Functional Requirements Mapping

NFR	Architectural Solution
Performance (<50ms)	[How achieved]
Security (OAuth)	[How achieved]
Scalability (10x)	[How achieved]
Reliability (99.9%)	[How achieved]

---

10. Technical Risks

Risk	Impact	Mitigation
[Risk 1]	[Impact]	[Strategy]
[Risk 2]	[Impact]	[Strategy]

---

11. Architecture Decision Records (ADRs)

ADR-001: {Decision Title}

Status: Accepted | Proposed | Deprecated Context: [Why this decision was needed] Decision: [What was decided] Consequences: [Positive and negative effects]

---

Appendix

A. Sequence Diagrams

[Key user flows]

B. Related Documents

• System Requirements: [link]
• PRD: [link]

---

Generated with Wolfejam Workflow - Step 3: Architecture

## Architecture Patterns Quick Reference

### Monolith
**When:** Small team, simple domain, rapid iteration needed
**Pros:** Simple deployment, easy debugging, single codebase
**Cons:** Scaling entire app, deployment risk, team coupling

### Microservices
**When:** Large team, complex domain, independent scaling needed
**Pros:** Independent deployment, tech flexibility, fault isolation
**Cons:** Operational complexity, network latency, data consistency

### Serverless
**When:** Variable load, event-driven, cost optimization priority
**Pros:** No server management, pay-per-use, auto-scaling
**Cons:** Cold starts, vendor lock-in, execution limits

### Event-Driven
**When:** Loose coupling, async processing, audit trails needed
**Pros:** Decoupling, scalability, temporal flexibility
**Cons:** Debugging complexity, eventual consistency, event ordering

## Process

### Step 1: Understand Requirements
Review PRD and System Requirements:
- Map user stories to components
- Map NFRs to architectural decisions

### Step 2: Choose Architecture Style
Select based on:
- Team size and skills
- Scaling requirements
- Deployment constraints
- Budget and timeline

### Step 3: Design Components
For each major capability:
- Define component boundaries
- Identify interfaces
- Document dependencies

### Step 4: Define Data Architecture
Design:
- Data models (entities, relationships)
- Storage choices (SQL, NoSQL, cache)
- Data flow (sync, async, streaming)

### Step 5: Document Decisions
Create ADRs for significant choices:
- Why the decision was made
- What alternatives were considered
- What trade-offs were accepted

## Output Location

Save architecture document to:

{project}/docs/ARCHITECTURE.md

Or for FAF projects:

{project}/FAF/architecture.faf

## Input/Output Flow

**Input:** PRD (PRD.md) + System Requirements (SYS-REQS.md)
**Output:** Technical Architecture (ARCHITECTURE.md)

## Next Step

After completing Architecture, proceed to:
- **project.faf creation** - Encode DNA into FAF format
- **WJTTC-TESTS.md** - Pre-define test scenarios

---

*Wolfejam Workflow Step 3 of 8*
*"Architecture is the skeleton; code is the muscle."*