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-analysis.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

workflow solution-architecture

The workflow will:

Load project-workflow-analysis.md (from plan-project)
Check prerequisites (PRD/GDD, UX spec if needed)
Read requirements (PRD for apps, GDD for games)
Ask architecture pattern questions
Load appropriate template and guide
Generate architecture + ADR documents
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-analysis.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:

GDD says "Unity 2022 LTS"
Registry match: game-unity-3d → game-engine-architecture.md + game-engine-unity-guide.md
Load complete game architecture template
Load Unity-specific guide
Ask Unity-specific questions (MonoBehaviour vs ECS, ScriptableObjects, etc.)
Fill template placeholders
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):

Executive Summary
Technology Stack and Decisions (required table)
Architecture Overview
Repository and Service Strategy
Data Architecture
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

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

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

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

For Web Apps:

Run workflow plan-project → Create PRD
Run workflow ux-spec → Create UX spec
Run workflow solution-architecture
Answer: SSR or SPA? Monolith or microservices?
System loads web-fullstack template
Generates framework-specific architecture

For Other Projects:

Run workflow plan-project → Create PRD
Run workflow solution-architecture
Answer project-type questions
System loads appropriate template
Generates pattern-specific architecture

Extending the System

Adding a New Template

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

Adding a New Guide

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

Adding a New Project Type

Add row to project-types/project-types.csv
Create project-types/new-type-questions.md
Ensure templates exist for this type
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.