# Solution Architecture Workflow

**Status:** Production-Ready | Scale-Adaptive Architecture Generation

---

## Overview

This workflow generates comprehensive, scale-adaptive solution architecture documentation tailored to your project type, technology stack, and scale level (0-4).

**Unique Features:**

- ✅ **Scale-adaptive**: Level 0 = skip, Levels 1-4 = progressive depth
- ✅ **Pattern-aware**: 171 technology combinations across 12 project types
- ✅ **Template-driven**: 11 complete architecture document templates
- ✅ **Engine-specific guidance**: Unity, Godot, Phaser, and more
- ✅ **GDD/PRD aware**: Uses Game Design Doc for games, PRD for everything else
- ✅ **ADR tracking**: Separate Architecture Decision Records document
- ✅ **Specialist integration**: Pattern-specific specialist recommendations

---

## When to Use

Run this workflow **AFTER** completing:

| Prerequisite               | Required For                  | Location                           |
| -------------------------- | ----------------------------- | ---------------------------------- |
| **plan-project workflow**  | All projects                  | `/docs/project-workflow-status.md` |
| **PRD with epics/stories** | Level 1+ projects             | `/docs/PRD.md`                     |
| **GDD (for games)**        | Game projects                 | `/docs/GDD.md` or `/docs/PRD.md`   |
| **UX Specification**       | UI projects (web/mobile/game) | `/docs/ux-specification.md`        |

---

## Quick Start

```bash
workflow solution-architecture
```

**The workflow will:**

1. Load `project-workflow-status.md` (from plan-project)
2. Check prerequisites (PRD/GDD, UX spec if needed)
3. Read requirements (PRD for apps, GDD for games)
4. Ask architecture pattern questions
5. Load appropriate template and guide
6. Generate architecture + ADR documents
7. Run cohesion check validation

---

## Outputs

### Primary Documents

| File                        | Purpose                              | Notes                                               |
| --------------------------- | ------------------------------------ | --------------------------------------------------- |
| `solution-architecture.md`  | Complete architecture document       | Pattern-specific sections                           |
| `architecture-decisions.md` | Architecture Decision Records (ADRs) | Tracks all decisions, options considered, rationale |

### Validation Outputs

| File                       | Purpose                             |
| -------------------------- | ----------------------------------- |
| `cohesion-check-report.md` | Validates 100% FR/NFR/Epic coverage |
| `epic-alignment-matrix.md` | Maps epics → components/tech/APIs   |

---

## Project Types and Templates

### 12 Project Types Supported

| Type          | Examples                     | Template                          | Guide Examples       |
| ------------- | ---------------------------- | --------------------------------- | -------------------- |
| **web**       | Next.js, Rails, Django       | web-fullstack-architecture.md     | (TBD)                |
| **mobile**    | React Native, Flutter, Swift | mobile-app-architecture.md        | (TBD)                |
| **game**      | Unity, Godot, Phaser         | game-engine-architecture.md       | Unity, Godot, Phaser |
| **embedded**  | ESP32, STM32, Raspberry Pi   | embedded-firmware-architecture.md | (TBD)                |
| **backend**   | Express, FastAPI, gRPC       | backend-service-architecture.md   | (TBD)                |
| **data**      | Spark, Airflow, MLflow       | data-pipeline-architecture.md     | (TBD)                |
| **cli**       | Commander, Click, Cobra      | cli-tool-architecture.md          | (TBD)                |
| **desktop**   | Electron, Tauri, Qt          | desktop-app-architecture.md       | (TBD)                |
| **library**   | npm, PyPI, cargo             | library-package-architecture.md   | (TBD)                |
| **infra**     | Terraform, K8s Operator      | infrastructure-architecture.md    | (TBD)                |
| **extension** | Chrome, VS Code plugins      | desktop-app-architecture.md       | (TBD)                |

### 171 Technology Combinations

The workflow maintains a registry (`templates/registry.csv`) with 171 pre-defined technology stack combinations:

**Examples:**

- `web-nextjs-ssr-monorepo` → Next.js SSR, TypeScript, monorepo
- `game-unity-3d` → Unity 3D, C#, monorepo
- `mobile-react-native` → React Native, TypeScript, cross-platform
- `backend-fastapi-rest` → FastAPI, Python, REST API
- `data-ml-training` → PyTorch/TensorFlow, Python, ML pipeline

Each row maps to:

- **template_path**: Architecture document structure (11 templates)
- **guide_path**: Engine/framework-specific guidance (optional)

---

## Architecture Flow

### Step 0: Prerequisites and Scale Check

Load `project-workflow-status.md`:

- Extract: `project_level` (0-4), `project_type` (web/game/mobile/etc.), `field_type` (greenfield/brownfield)
- Validate: PRD exists, UX spec exists (if UI project)
- **Skip if Level 0** (single atomic change)

### Step 1: Requirements Analysis

**For Games:**

- Read **GDD** (Game Design Document)
- Extract: gameplay mechanics, engine (Unity/Godot/etc.), platform, multiplayer

**For Everything Else:**

- Read **PRD** (Product Requirements Document)
- Extract: FRs, NFRs, epics, stories, integrations

**For UI Projects:**

- Read **UX Specification**
- Extract: screens, flows, component patterns

### Step 2: User Skill Level

Ask user: Beginner / Intermediate / Expert

- Affects verbosity of generated architecture

### Step 3: Architecture Pattern

Determine:

- Architecture style (monolith, microservices, serverless, etc.)
- Repository strategy (monorepo, polyrepo, hybrid)
- Pattern-specific choices (SSR for web, native vs cross-platform for mobile)

### Step 4: Epic Analysis

Analyze PRD epics:

- Identify component boundaries
- Map domain capabilities
- Determine service boundaries (if microservices)

### Step 5: Project-Type Questions

Load: `project-types/{project_type}-questions.md`

- Ask project-type-specific questions (not yet engine-specific)

### Step 6: Load Template + Guide

**6.1: Search Registry**

```
Read: templates/registry.csv
Match WHERE:
  - project_types = {determined_type}
  - languages = {preferred_languages}
  - architecture_style = {determined_style}
  - tags overlap with {requirements}

Get: template_path, guide_path
```

**6.2: Load Template**

```
Read: templates/{template_path}
Example: templates/game-engine-architecture.md

This is a COMPLETE document structure with:
- Standard sections (exec summary, tech stack, data arch, etc.)
- Pattern-specific sections (Gameplay Systems for games, SSR Strategy for web)
- All {{placeholders}} to fill
```

**6.3: Load Guide (if available)**

```
IF guide_path not empty:
  Read: templates/{guide_path}
  Example: templates/game-engine-unity-guide.md

Guide contains:
- Engine/framework-specific questions
- Architecture patterns for this tech
- Common pitfalls
- Specialist recommendations
- ADR templates
```

**Example Flow for Unity Game:**

1. GDD says "Unity 2022 LTS"
2. Registry match: `game-unity-3d` → `game-engine-architecture.md` + `game-engine-unity-guide.md`
3. Load complete game architecture template
4. Load Unity-specific guide
5. Ask Unity-specific questions (MonoBehaviour vs ECS, ScriptableObjects, etc.)
6. Fill template placeholders
7. Generate `solution-architecture.md` + `architecture-decisions.md`

### Step 7: Cohesion Check

Validate architecture quality:

- 100% FR/NFR/Epic/Story coverage
- Technology table has specific versions
- No vagueness ("a library", "some framework")
- Design-level only (no implementation code)
- Generate Epic Alignment Matrix

---

## File Structure

```
/solution-architecture/
├── README.md                        # This file
├── workflow.yaml                    # Workflow configuration
├── instructions.md                  # Main workflow logic
├── checklist.md                     # Validation checklist
├── ADR-template.md                  # ADR document template
├── templates/                       # Architecture templates and guides
│   ├── registry.csv                 # 171 tech combinations → templates
│   ├── game-engine-architecture.md  # Complete game architecture doc
│   ├── game-engine-unity-guide.md   # Unity-specific guidance
│   ├── game-engine-godot-guide.md   # Godot-specific guidance
│   ├── game-engine-web-guide.md     # Phaser/PixiJS/Three.js guidance
│   ├── web-fullstack-architecture.md
│   ├── web-api-architecture.md
│   ├── mobile-app-architecture.md
│   ├── embedded-firmware-architecture.md
│   ├── backend-service-architecture.md
│   ├── data-pipeline-architecture.md
│   ├── cli-tool-architecture.md
│   ├── desktop-app-architecture.md
│   ├── library-package-architecture.md
│   └── infrastructure-architecture.md
└── project-types/                   # Project type detection and questions
    ├── project-types.csv            # 12 project types + detection keywords
    ├── game-questions.md
    ├── web-questions.md
    ├── mobile-questions.md
    └── ... (12 question files)
```

---

## Template System

### Complete, Standalone Templates

Each template in `templates/` is a **complete** architecture document structure:

**Standard Sections (all templates):**

1. Executive Summary
2. Technology Stack and Decisions (required table)
3. Architecture Overview
4. Repository and Service Strategy
5. Data Architecture
6. Component and Integration Overview
   7-N. **Pattern-Specific Sections** (varies by template)
   N+1. Proposed Source Tree
   N+2. Getting Started (Human Setup)
   N+3. Implementation Patterns and Conventions (Agent Guidance)
   N+4. Testing Strategy
   N+5. Deployment and Operations
   N+6. Security
   N+7. Specialist Sections

**Pattern-Specific Sections Examples:**

**Game Engine Template:**

- Gameplay Systems (player controller, game state)
- Scene Architecture
- Asset Pipeline
- Audio Architecture
- Save System
- Multiplayer Architecture (if applicable)

**Web Fullstack Template:**

- Frontend Architecture
- Backend Architecture
- API Design (REST/GraphQL/tRPC)
- State Management
- SSR/Caching Strategy
- Performance Optimization

**Embedded Firmware Template:**

- Hardware Architecture
- Communication Protocols
- Power Management
- Sensor/Actuator Integration
- OTA Update Strategy

---

## Guide System

### Engine/Framework-Specific Guides

Guides are **workflow instruction documents** that:

- Ask engine-specific questions
- Provide architecture pattern recommendations
- Suggest what sections to emphasize
- Define ADRs to create

**Guides are NOT:**

- ❌ Reference documentation (use official docs)
- ❌ Tutorials (how to code)
- ❌ API references

**Guides ARE:**

- ✅ Question flows for architecture decisions
- ✅ Pattern recommendations specific to the tech
- ✅ Common pitfalls to avoid
- ✅ Specialist recommendations

**Example: game-engine-unity-guide.md**

```markdown
## Unity Architecture Questions

- MonoBehaviour or ECS?
- ScriptableObjects for game data?
- Addressables or Resources?

## Unity Patterns

- Singleton GameManager (when to use)
- Event-driven communication
- Object pooling strategy

## Unity-Specific Sections to Include

- Unity Project Configuration
- Scene Architecture
- Component Organization
- Package Dependencies

## Common Pitfalls

- Caching GetComponent calls
- Avoiding empty Update methods
```

---

## ADR Tracking

Architecture Decision Records are maintained separately in `architecture-decisions.md`.

**ADR Format:**

```markdown
### ADR-001: [Decision Title]

**Date:** YYYY-MM-DD
**Status:** Accepted | Rejected | Superseded
**Decider:** User | Agent | Collaborative

**Context:**
What problem are we solving?

**Options Considered:**

1. Option A - pros/cons
2. Option B - pros/cons
3. Option C - pros/cons

**Decision:**
We chose Option X

**Rationale:**
Why we chose this over others

**Consequences:**

- Positive: ...
- Negative: ...

**Rejected Options:**

- Option A rejected because: ...
```

**ADRs are populated throughout the workflow** as decisions are made:

- Step 3: Architecture pattern ADR
- Step 5: Technology selection ADRs
- Step 6: Engine-specific ADRs (from guide)

---

## Scale-Adaptive Behavior

| Level | Project Size                     | Architecture Depth          | Specialist Sections        |
| ----- | -------------------------------- | --------------------------- | -------------------------- |
| **0** | Single task                      | Skip architecture           | N/A                        |
| **1** | Small feature (1-10 stories)     | Lightweight, essential only | Inline guidance            |
| **2** | Small project (5-15 stories)     | Standard depth              | Inline guidance            |
| **3** | Standard project (12-40 stories) | Comprehensive               | Specialist placeholders    |
| **4** | Ambitious product (40+ stories)  | Comprehensive + specialists | Specialist recommendations |

---

## Specialist Integration

Pattern-specific specialists are recommended based on project characteristics:

**Game Projects:**

- Audio Designer (music, SFX, adaptive audio)
- Performance Optimizer (profiling, optimization)
- Multiplayer Architect (netcode, state sync)
- Monetization Specialist (IAP, ads, economy)

**Web Projects:**

- Frontend Architect (component design, state management)
- Backend Architect (API design, microservices)
- DevOps Specialist (CI/CD, deployment)
- Security Specialist (auth, authorization, secrets)

**Embedded Projects:**

- Hardware Integration (sensors, actuators, protocols)
- Power Management (battery, sleep modes)
- RF/Wireless (WiFi, BLE, LoRa)
- Safety Certification (if required)

Specialists are documented with:

- When they're needed
- What they're responsible for
- How they integrate with the workflow

---

## Key Differences from Legacy HLA Workflow

| Aspect              | Legacy HLA      | New Solution Architecture                 |
| ------------------- | --------------- | ----------------------------------------- |
| **Templates**       | Fixed structure | 11 complete templates, pattern-specific   |
| **Tech Selection**  | Manual          | 171 pre-defined combinations              |
| **Engine Guidance** | Generic         | Engine-specific guides (Unity/Godot/etc.) |
| **ADRs**            | Inline          | Separate document                         |
| **GDD Support**     | No              | Yes, for game projects                    |
| **Guides**          | None            | Pattern-specific workflow guidance        |
| **Scale**           | One size        | Adaptive Levels 0-4                       |

---

## Validation and Quality Gates

### Cohesion Check (Step 7)

**Validates:**

- ✅ 100% FR coverage (or gaps documented)
- ✅ 100% NFR coverage (or gaps documented)
- ✅ Every epic has technical foundation
- ✅ Every story can be implemented with current architecture
- ✅ Technology table complete with specific versions
- ✅ No vagueness detected
- ✅ Design-level only (no over-implementation)

**Outputs:**

- `cohesion-check-report.md` - Pass/fail with detailed gaps
- `epic-alignment-matrix.md` - Mapping validation

**If cohesion check fails:**

- Document gaps
- Update architecture
- Re-run check

---

## Getting Started for Implementers

### For Games:

1. Run `workflow plan-project` → Create GDD
2. Specify engine in GDD (Unity/Godot/Phaser/etc.)
3. Run `workflow solution-architecture`
4. System detects engine from GDD
5. Loads game-engine template + engine-specific guide
6. Generates Unity/Godot/Phaser-specific architecture

### For Web Apps:

1. Run `workflow plan-project` → Create PRD
2. Run `workflow ux-spec` → Create UX spec
3. Run `workflow solution-architecture`
4. Answer: SSR or SPA? Monolith or microservices?
5. System loads web-fullstack template
6. Generates framework-specific architecture

### For Other Projects:

1. Run `workflow plan-project` → Create PRD
2. Run `workflow solution-architecture`
3. Answer project-type questions
4. System loads appropriate template
5. Generates pattern-specific architecture

---

## Extending the System

### Adding a New Template

1. Create `templates/new-pattern-architecture.md`
2. Include all standard sections + pattern-specific sections
3. Add rows to `templates/registry.csv` pointing to new template

### Adding a New Guide

1. Create `templates/new-tech-guide.md`
2. Include: questions, patterns, pitfalls, specialist recommendations
3. Update `templates/registry.csv` with `guide_path` column

### Adding a New Project Type

1. Add row to `project-types/project-types.csv`
2. Create `project-types/new-type-questions.md`
3. Ensure templates exist for this type
4. Update instructions.md if special handling needed (like GDD for games)

---

## Questions?

- **Validation:** See `checklist.md`
- **Workflow Logic:** See `instructions.md`
- **Configuration:** See `workflow.yaml`
- **Registry Format:** See `templates/registry.csv`
- **Example Guide:** See `templates/game-engine-unity-guide.md`

---

_This workflow replaces the legacy HLA workflow with a modern, scale-adaptive, pattern-aware architecture generation system._