# 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
- ✅ **Intent-based**: LLM intelligence over prescriptive lists
- ✅ **Template-driven**: 11 adaptive architecture document templates
- ✅ **Game-aware**: Adapts heavily based on game type (RPG, Puzzle, Shooter, etc.)
- ✅ **GDD/PRD aware**: Uses Game Design Doc for games, PRD for everything else
- ✅ **ADR tracking**: Separate Architecture Decision Records document
- ✅ **Simplified structure**: ~11 core project types with consistent naming

---

## When to Use

Run this workflow **AFTER** completing:

| Prerequisite               | Required For                  | Location                         |
| -------------------------- | ----------------------------- | -------------------------------- |
| **plan-project workflow**  | All projects                  | `/docs/bmm-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 `bmm-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

### Simplified Project Type System

The workflow uses ~11 core project types that cover 99% of software projects:

| Type               | Name                     | Template                   | Instructions                   |
| ------------------ | ------------------------ | -------------------------- | ------------------------------ |
| **web**            | Web Application          | web-template.md            | web-instructions.md            |
| **mobile**         | Mobile Application       | mobile-template.md         | mobile-instructions.md         |
| **game**           | Game Development         | game-template.md           | game-instructions.md           |
| **backend**        | Backend Service          | backend-template.md        | backend-instructions.md        |
| **data**           | Data Pipeline            | data-template.md           | data-instructions.md           |
| **cli**            | CLI Tool                 | cli-template.md            | cli-instructions.md            |
| **library**        | Library/SDK              | library-template.md        | library-instructions.md        |
| **desktop**        | Desktop Application      | desktop-template.md        | desktop-instructions.md        |
| **embedded**       | Embedded System          | embedded-template.md       | embedded-instructions.md       |
| **extension**      | Browser/Editor Extension | extension-template.md      | extension-instructions.md      |
| **infrastructure** | Infrastructure           | infrastructure-template.md | infrastructure-instructions.md |

### Intent-Based Architecture

Instead of maintaining 171 prescriptive technology combinations, the workflow now:

- **Leverages LLM intelligence** to understand project requirements
- **Adapts templates dynamically** based on actual needs
- **Uses intent-based instructions** rather than prescriptive checklists
- **Allows for emerging technologies** without constant updates

Each project type has:

- **Instruction file**: Intent-based guidance for architecture decisions
- **Template file**: Adaptive starting point for the architecture document

---

## Architecture Flow

### Step 0: Prerequisites and Scale Check

Load `bmm-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: Intent-Based Technical Decisions

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

- Use intent-based guidance, not prescriptive lists
- Allow LLM intelligence to identify relevant decisions
- Consider emerging technologies naturally

### Step 6: Adaptive Template Selection

**6.1: Simple Template Selection**

```
Based on project_type from analysis:
  web → web-template.md
  mobile → mobile-template.md
  game → game-template.md (adapts heavily by game type)
  backend → backend-template.md
  ... (consistent naming pattern)
```

**6.2: Load Template**

```
Read: project-types/{type}-template.md
Example: project-types/game-template.md

Templates are adaptive starting points:
- Standard sections (exec summary, tech stack, data arch, etc.)
- Pattern-specific sections conditionally included
- All {{placeholders}} to fill based on requirements
```

**6.3: Dynamic Adaptation**

Templates adapt based on:

- Actual project requirements from PRD/GDD
- User skill level (beginner/intermediate/expert)
- Specific technology choices made
- Game type for game projects (RPG, Puzzle, Shooter, etc.)

**Example Flow for Unity RPG:**

1. GDD says "Unity 2022 LTS" and "RPG"
2. Load game-template.md and game-instructions.md
3. Template adapts to include RPG-specific sections (inventory, quests, dialogue)
4. Instructions guide Unity-specific decisions (MonoBehaviour vs ECS, etc.)
5. LLM intelligence fills gaps not in any list
6. Generate optimized `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
└── project-types/                   # All project type files in one folder
    ├── project-types.csv            # Simple 2-column mapping (type, name)
    ├── web-instructions.md          # Intent-based guidance for web projects
    ├── web-template.md              # Adaptive web architecture template
    ├── mobile-instructions.md       # Intent-based guidance for mobile
    ├── mobile-template.md           # Adaptive mobile architecture template
    ├── game-instructions.md         # Intent-based guidance (adapts by game type)
    ├── game-template.md             # Highly adaptive game architecture template
    ├── backend-instructions.md      # Intent-based guidance for backend services
    ├── backend-template.md          # Adaptive backend architecture template
    ├── data-instructions.md         # Intent-based guidance for data pipelines
    ├── data-template.md             # Adaptive data pipeline template
    ├── cli-instructions.md          # Intent-based guidance for CLI tools
    ├── cli-template.md              # Adaptive CLI architecture template
    ├── library-instructions.md      # Intent-based guidance for libraries/SDKs
    ├── library-template.md          # Adaptive library architecture template
    ├── desktop-instructions.md      # Intent-based guidance for desktop apps
    ├── desktop-template.md          # Adaptive desktop architecture template
    ├── embedded-instructions.md     # Intent-based guidance for embedded systems
    ├── embedded-template.md         # Adaptive embedded architecture template
    ├── extension-instructions.md    # Intent-based guidance for extensions
    ├── extension-template.md        # Adaptive extension architecture template
    ├── infrastructure-instructions.md  # Intent-based guidance for infra
    └── infrastructure-template.md   # Adaptive infrastructure template
```

---

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

---

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

1. Add row to `project-types/project-types.csv` (just type and name)
2. Create `project-types/{type}-instructions.md` with intent-based guidance
3. Create `project-types/{type}-template.md` with adaptive template
4. Update instructions.md if special handling needed (like GDD for games)

### Key Principles

- **Intent over prescription**: Guide decisions, don't list every option
- **Leverage LLM intelligence**: Trust the model to know technologies
- **Adaptive templates**: Templates should adapt to project needs
- **Consistent naming**: Always use {type}-instructions.md and {type}-template.md

---

## Questions?

- **Validation:** See `checklist.md`
- **Workflow Logic:** See `instructions.md`
- **Configuration:** See `workflow.yaml`
- **Project Types:** See `project-types/project-types.csv`
- **Example Template:** See `project-types/game-template.md`

---

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