usm/gen-technical-design [built]

Technical Design Document generator — renders a 13-section detailed design document from .usm specs. The universal "how is this system designed end-to-end" reading path. Each section is its own page, rendered only when data exists. Adapts to any project type (CLI tool, SaaS platform, library, monorepo). Adds new schema fields for stakeholders, assumptions, personas, non-functional requirements, testing strategy, and backup/recovery. Restructures the generated sidebar into five groups: Getting Started, Design (13 pages), Project Management (roadmap, features, decisions), Developers (source map, coverage, references), Exports (TOGAF, ArchiMate).

Status: built

Why this exists

Every engineering team needs a detailed design document that ties the whole system together — project overview, requirements, architecture, modules, database, API, security, deployment, testing, maintenance, backup, risks, and future plans. USM specs already contain most of this data, but it's scattered across feature docs, TOGAF phases, and service pages. This generator assembles it into one coherent reading path that works for any project type. It follows the first principle that generators are renderers, not authors — structured data from specs drives every section, with optional content-block enrichment from system.usm for prose that doesn't fit structured fields.

Design decisions

generator-not-author

Decision: The technical design document is a generator (structured renderer), not an authored doc. All content comes from .usm specs, schema, or declared content blocks.

Rationale: Follows the first principle established by gen-content-blocks: generators are renderers, not authors. The mapping from USM data to the 13 sections is deterministic.

design-pages-parallel-to-reference-pages

Decision: system.usm gains a design_pages[] field parallel to reference_pages[]. Each entry can declare inline content blocks for a section, enriching the structured data.

Rationale: Some sections need prose that doesn't fit structured fields (e.g. disaster recovery narrative, testing philosophy). Content blocks provide that escape hatch while keeping the generator as the primary renderer.

suppress-empty-sections

Decision: Sections with no data are suppressed entirely — no empty stub pages, no sidebar links to pages that don't exist.

Rationale: Follows the docs-experience principle: a CLI tool shouldn't have a Database Design page. The template adapts to the project.

five-group-sidebar

Decision: The sidebar is restructured into five groups: Getting Started, Design, Project Management, Developers, Exports. This replaces the current fragmented groups (Core Concepts, Workflows, Architecture, Deployment, Contributing).

Rationale: The current sidebar mixes concerns — architecture phases next to reference pages next to feature groups. Five clean groups by audience and purpose: onboarding, holistic design, project governance, developer reference, alternative framework exports.

nav-template-definition

Decision: The nav template structure is the standard for all generated technical docs. It defines five top-level groups and the pages within each. The template is fixed in structure but adaptive in rendering — groups and pages only appear when data exists.

Getting Started
  Home
  Getting Started

Design
  Project Overview
    Project Name
    Project Description
    Stakeholders
    Assumptions
    Use-cases
  Requirements
    Functional Requirements
    Non-Functional Requirements
      Performance
      Scalability
      Security
      Reliability
      Maintainability
  System Architecture
    High-Level Diagram
    Technology Stack
      Frontend
      Backend
      Database
      Infrastructure
    System Components
  Module Design
    Module Name
    Purpose
    Inputs
    Outputs
    Dependencies
    Flow
  Database Design
    ER Diagram
    Schema Design
    Indexes
    Transactions
  API Design
    Endpoints
      HTTP Method (GET/POST/PUT/DELETE)
      URL Schemas / naming conventions
    Request/Response structure
    Authentication
    Authorization (roles, resources, permissions)
    Rate Limiting
    Error Handling
  Security Design
    Authentication / Authorization
    Data Encryption
    Security Auditing
    Vulnerabilities
    Security Stack
  Deployment Architecture
    Deployment Diagram
    Environment Setup
      Development
      Staging
      Production
    Scaling Strategy
    Monitoring Stack
  Testing Strategy
    Unit Testing
    Integration Testing
    Acceptance Testing
    Performance Testing
    Security Testing
    Automated Testing
  Maintenance & Monitoring
    Logging
    Alerting
    System Health Monitoring
    Error Tracking
  Backup & Recovery
    Backup Strategy
    Disaster Recovery
  Risks & Mitigation
    Technical Risks
    Mitigation Strategies
  Future Enhancements
    Roadmap
    Scalability Considerations

Project Management
  Roadmap
  Features (grouped by service/area)
  Decision Register

Developers
  Source Map
  Test Coverage
  Spec Coverage
  API Reference
  CLI Reference
  Configuration

Exports (collapsed)
  TOGAF Phases
  ArchiMate Model

Level 1 = sidebar group. Level 2 = sidebar page link. Level 3+ = page content sections (rendered as the page outline/TOC, not sidebar links). The sidebar is 2 levels deep (group > page). Groups and pages only appear when their data source exists — the template adapts to the project type.

Rationale: Capturing the full template structure as a decision ensures the generator has a single authoritative reference for what to render. The template is universal — it applies to any project type — but adapts by suppressing sections without data.

decision-register-consolidated

Decision: A Decision Register page consolidates all decisions from features, services, and system principles into one page under Project Management.

Rationale: Decisions are currently scattered across feature docs and TOGAF Phase H. A single register is the project governance view — what was decided, why, and what alternatives were rejected.

features-as-project-management

Decision: Features are grouped under Project Management, not Design. Features with flows/contracts/tests/status are work records, not design prose.

Rationale: Separating how the system is designed from how the project is managed is cleaner. Design is the system; Project Management is the work.

How it works

Generate the 13-section technical design document (gen-design-doc)

usm generate runs the technical-design generator. It reads all .usm files (system, services, features, data) and renders up to 13 pages under .usm-workspace/docs/design/. Each page is only rendered if its data source exists. The generator then updates the sidebar config with the Design group containing only the rendered pages.

1. Parse — system.usm + all service, feature, and data .usm files
2. Determine — which of the 13 sections have data
3. Generate — one markdown page per section that has data, to .usm-workspace/docs/design/
4. Enrich — sections with inline content blocks declared on system.usm (if any)
5. Update — sidebar config with Design group containing only rendered pages

Render Project Overview page (render-project-overview)

Section 1. Reads system.identity (name, domain, repository), system.summary, system.roles (as stakeholders/personas), new system.stakeholders[], new system.assumptions[], and system.index (features as use-cases). Renders project name, description, stakeholders table, assumptions list, and core use-cases summary.

1. Read — system.identity for name, domain, repository
2. Read — system.summary for project description
3. Read — system.roles and system.stakeholders for stakeholder table
4. Read — system.assumptions for assumptions list
5. Read — system.index to summarise core features as use-cases
6. Render — markdown page with escaped prose, tables, and content-block enrichment

Render Requirements page (render-requirements)

Section 2. Functional requirements from features (summary + intent). Non-functional requirements from new system.non_functional{} object with sub-fields for performance, scalability, security, reliability, maintainability. Renders two sub-sections with feature table and NFR table.

1. Read — all feature .usm files for functional requirements (summary, intent, status)
2. Read — system.non_functional for NFRs
3. Render — Functional Requirements as a table of features with descriptions
4. Render — Non-Functional Requirements as a table with category, requirement, target

Render System Architecture page (render-system-architecture)

Section 3. High-level diagram from Mermaid (services + dependencies). Technology stack from service.tech_stack across all services. System components from system.services + system.apis. Renders diagram, tech stack table, and component list.

1. Generate — high-level Mermaid diagram from system.services and depends_on
2. Collect — tech_stack from all services, merged by layer
3. Read — system.services for component list with types and ports
4. Read — system.apis for third-party service dependencies
5. Render — diagram, tech stack table, components table

Render Module Design page (render-module-design)

Section 4. Per-module breakdown from service.modules[]. For each module: name, purpose, inputs, outputs, dependencies, and a flow description (from features whose implementation.primary is in the module). Renders one sub-section per module.

1. Read — all service .usm files for modules[]
2. Match — features to modules via implementation.primary path
3. Render — per-module sub-section with name, purpose, inputs, outputs, dependencies, flow

Render Database Design page (render-database-design)

Section 5. ER diagram from data .usm files or detected ORM schema. Schema design from data.usm models. Indexes from data.usm index definitions. Transactions from data.usm transaction strategies. Renders ER diagram, schema tables, index list, transaction notes. Only rendered if data .usm files or a detected ORM schema exist.

1. Read — data .usm files for models, indexes, transactions
2. Read — system.data for data references
3. Generate — ER diagram (Mermaid) from data models
4. Render — schema design tables, index list, transaction notes

Render API Design page (render-api-design)

Section 6. Endpoints from feature.routes[]. HTTP method, URL, request/response structure. Authentication from system.auth_schemes and service.security. Authorization from service.rbac (roles, resources, permissions). Rate limiting from route-level or service-level config. Error handling conventions. Renders endpoint table, auth summary, authz matrix, rate limiting notes, error format. Only rendered if any feature has routes.

1. Collect — all feature routes[] across all services
2. Read — system.auth_schemes for authentication methods
3. Read — service.rbac for authorization model
4. Read — route-level or service-level rate limiting config
5. Render — endpoint table, auth summary, RBAC matrix, rate limits, error format

Render Security Design page (render-security-design)

Section 7. Authentication/authorization from system.auth_schemes and service.rbac. Data encryption from service.security and infrastructure TLS config. Security auditing from system.operations and service.infrastructure.monitoring. Vulnerabilities from system.risks where severity is high/critical. Security stack from new system.security_stack{} field (first line, last line of defense). Renders auth summary, encryption table, audit notes, vulnerability list, security stack.

1. Read — system.auth_schemes and service.security for auth/encryption
2. Read — service.rbac for RBAC model
3. Read — service.infrastructure for TLS, secrets, monitoring
4. Read — system.risks filtered by severity for vulnerabilities
5. Read — system.security_stack for defense-in-depth layers
6. Render — auth summary, encryption table, audit notes, vulnerability list, security stack

Render Deployment Architecture page (render-deployment-architecture)

Section 8. Deployment diagram (Mermaid) from system.infrastructure and service.infrastructure. Environment setup from system.deployment.environments (development, staging, production). Scaling strategy from service.infrastructure.scaling and system.infrastructure. Monitoring stack from system.operations and service.infrastructure.monitoring. Renders diagram, environment table, scaling notes, monitoring stack. Only rendered if deployment or infrastructure data exists.

1. Generate — deployment Mermaid diagram from infrastructure data
2. Read — system.deployment.environments for environment table
3. Read — service.infrastructure.scaling for scaling strategy
4. Read — system.operations and service.infrastructure.monitoring for monitoring stack
5. Render — diagram, environment table, scaling notes, monitoring stack

Render Testing Strategy page (render-testing-strategy)

Section 9. Unit testing from service.testing (framework, command, coverage target). Integration testing from service.testing_details. Acceptance testing from feature.tests[]. Performance testing and security testing from new system.testing_strategy{} field. Automated testing from CI integration notes in system.testing_strategy. Renders per-layer testing table with framework, command, and notes.

1. Read — service.testing and service.testing_details for unit/integration
2. Read — feature.tests[] for acceptance test count and coverage
3. Read — system.testing_strategy for performance, security, automated testing policies
4. Render — testing strategy table per layer (unit, integration, acceptance, performance, security, automated)

Render Maintenance & Monitoring page (render-maintenance-monitoring)

Section 10. Logging from system.operations and service.infrastructure.monitoring.logs. Alerting from system.operations.alerts. System health monitoring from service.infrastructure.monitoring.metrics. Error tracking from new system.error_tracking{} field. Renders logging strategy, alerting config, health metrics, error tracking tool.

1. Read — system.operations for monitoring, alerts, on-call
2. Read — service.infrastructure.monitoring for logs, metrics, alarms
3. Read — system.error_tracking for error tracking tool and config
4. Render — logging strategy, alerting config, health metrics table, error tracking notes

Render Backup & Recovery page (render-backup-recovery)

Section 11. Backup strategy from service.infrastructure.data.backup_retention_days and new system.backup_recovery{} field. Disaster recovery from service.infrastructure.disaster_recovery (rto_minutes, rpo_minutes) and system.backup_recovery. Renders backup schedule table, RTO/RPO targets, disaster recovery plan. Only rendered if backup or DR data exists.

1. Read — service.infrastructure.data for backup_retention_days
2. Read — service.infrastructure.disaster_recovery for rto/rpo
3. Read — system.backup_recovery for backup strategy and DR plan
4. Render — backup schedule table, RTO/RPO targets, DR plan summary

Render Risks & Mitigation page (render-risks-mitigation)

Section 12. Technical risks from system.risks[] (all items). Mitigation strategies from each risk's mitigation field. Also includes service-level risks from service.risks[]. Renders risk table with ID, title, severity, status, mitigation, and a severity summary chart.

1. Read — system.risks for system-level risks
2. Read — service.risks for service-level risks
3. Render — risk table with ID, title, severity, status, mitigation
4. Render — severity summary grouped by severity level

Render Future Enhancements page (render-future-enhancements)

Section 13. Roadmap from system.roadmap[] (planned and in-progress items). Scalability considerations from service.infrastructure.scaling and service.future[] items. Renders roadmap table with status badges, target dates, and future items list grouped by service.

1. Read — system.roadmap for roadmap items
2. Read — service.future for per-service future items
3. Read — service.infrastructure.scaling for scalability considerations
4. Render — roadmap table with status, target date, and feature link
5. Render — future items grouped by service, scalability notes

Render Decision Register page (render-decision-register)

Consolidates all decisions[] from features, services, and system.principles into one page. Each decision shows ID, decision text, status, rationale, alternatives considered, consequences, date, and source. Renders a table view and a detailed view.

1. Collect — decisions[] from all feature .usm files
2. Collect — decisions[] from all service .usm files
3. Collect — system.principles as architecture decisions
4. Render — summary table (ID, decision, status, source) and detailed per-decision breakdown

Restructure sidebar into five groups (restructure-sidebar)

The docs sidebar generator is updated to produce five top-level groups: Getting Started (Home, Getting Started), Design (13 pages, only rendered ones), Project Management (Roadmap, Features grouped by area, Decision Register), Developers (Source Map, Test Coverage, Spec Coverage, API Reference, CLI Reference, Configuration), Exports (TOGAF Phases, ArchiMate Model). Groups and pages only appear if data exists. The existing Core Concepts, Workflows, Architecture, Deployment, and Contributing groups are replaced by this structure.

1. Determine — which Design pages have data (same logic as gen-design-doc)
2. Build — Getting Started group from index + getting-started page
3. Build — Design group with only rendered section pages
4. Build — Project Management group with roadmap, features (grouped), decision register
5. Build — Developers group with source-map pages and reference pages that have data
6. Build — Exports group with TOGAF and ArchiMate (collapsed)

Guarantees

adapt-to-project-type

The generator must adapt to any project type — a CLI tool with no database, a library with no deployment, a monorepo with multiple services. Sections with no data are suppressed entirely, not rendered as empty stubs.

Acceptance criteria:

• [ ] Each of the 13 pages is only rendered if its data source exists
• [ ] The sidebar only includes links to rendered pages
• [ ] A CLI-only project produces no Database Design, API Design, or Deployment Architecture pages
• [ ] No page contains an empty section with no content

one-source-many-views

The technical design document is a view of the same .usm data as TOGAF, feature docs, and source mapping. It must not duplicate or hardcode content — it renders from specs.

Acceptance criteria:

• [ ] All content is derived from .usm files, schema, or declared content blocks
• [ ] No USM-specific content hardcoded in the generator
• [ ] No content duplicated from TOGAF or feature docs — both read from the same specs independently

content-block-enrichment

system.usm can declare inline content blocks for any Design section via a new design_pages[] field (parallel to reference_pages[]). These enrich the structured data with prose that doesn't fit schema fields.

Acceptance criteria:

• [ ] design_pages[] entries have id, title, audience, and either content[] (content blocks) or source (structured data)
• [ ] Inline content blocks render AFTER structured data on the same page
• [ ] Sections without design_pages entries still render from structured data alone

prose-escaping

All prose from specs must be escaped via escapeProse before rendering to prevent VitePress Vue template compilation errors from unescaped angle brackets.

Acceptance criteria:

• [ ] All spec-authored prose passed through escapeProse
• [ ] All table cell content passed through escapeTableCell or escCell
• [ ] Mermaid diagram blocks are exempt (they use their own escaping)

sidebar-data-driven

The sidebar structure is generated from data availability, not hardcoded. Groups and pages appear only when their underlying data exists.

Acceptance criteria:

• [ ] Design group only includes pages that were rendered
• [ ] Project Management group only appears if roadmap, features, or decisions exist
• [ ] Developers group only includes reference pages that have data
• [ ] Exports group only appears if TOGAF or ArchiMate outputs exist

decision-register

The Decision Register consolidates all decisions from features, services, and system principles into one page — the single source of truth for what was decided and why.

Acceptance criteria:

• [ ] All feature decisions[] included with source feature $id
• [ ] All service decisions[] included with source service $id
• [ ] System principles[] rendered as architecture decisions
• [ ] Each decision shows ID, decision, status, rationale, alternatives, consequences

nav-template-structure

The generated sidebar follows a fixed five-group template structure that applies to any project. The template defines which groups exist, which pages go in each group, and which content sections each Design page contains. Groups and pages are suppressed when their data source doesn't exist, but the structure itself is the standard template.

Acceptance criteria:

• [ ] Getting Started group: Home, Getting Started
• [ ] Design group: 13 section pages (Project Overview, Requirements, System Architecture, Module Design, Database Design, API Design, Security Design, Deployment Architecture, Testing Strategy, Maintenance & Monitoring, Backup & Recovery, Risks & Mitigation, Future Enhancements) — only rendered pages appear
• [ ] Project Management group: Roadmap, Features (grouped by service/area), Decision Register
• [ ] Developers group: Source Map, Test Coverage, Spec Coverage, API Reference, CLI Reference, Configuration (only pages with data appear)
• [ ] Exports group: TOGAF Phases, ArchiMate Model (collapsed)
• [ ] Each Design page has a defined set of content sections (3rd-level outline) that the generator renders — these are the page's TOC, not separate sidebar links

Test specifications

design-full-system

Given:

• system_with_services_features_data: true

Then:

• assertion: 13 design pages generated when all data sources present
• assertion: Each page has frontmatter with title and generated date
• assertion: All prose is escaped (no raw < or > outside code fences and Mermaid blocks)
• assertion: Sidebar Design group contains links to all 13 rendered pages

design-cli-only

Given:

• system_with_cli_service_only: true

Then:

• assertion: No Database Design page generated (no data .usm files)
• assertion: No Deployment Architecture page generated (no infrastructure data)
• assertion: Sidebar Design group only includes pages that were rendered
• assertion: No empty stub pages with zero content

design-content-block-enrichment

Given:

• system_with_design_pages_content_blocks: true

Then:

• assertion: Inline content blocks render after structured data on the same page
• assertion: Sections without design_pages entries still render from structured data
• assertion: Content blocks use the same content-block renderer as reference_pages

decision-register

Given:

• features_and_services_with_decisions: true

Then:

• assertion: All feature decisions included with source $id
• assertion: All service decisions included with source $id
• assertion: System principles rendered as architecture decisions
• assertion: Each decision shows ID, decision, status, rationale

sidebar-data-driven

Given:

• system_with_partial_data: true

Then:

• assertion: Sidebar groups only appear when their data exists
• assertion: Design group pages match exactly what was rendered
• assertion: No dead links to pages that don't exist

nav-template-conformance

Given:

• system_with_all_data_sources: true

Then:

• assertion: Sidebar has exactly five groups in order (Getting Started, Design, Project Management, Developers, Exports)
• assertion: Design group contains all 13 section pages when all data present
• assertion: Project Management group contains Roadmap, Features, Decision Register
• assertion: Developers group contains Source Map, Test Coverage, Spec Coverage, API Reference, CLI Reference, Configuration
• assertion: Exports group is collapsed and contains TOGAF Phases, ArchiMate Model

prose-escaping

Given:

• spec_with_angle_brackets_in_descriptions: true

Then:

• assertion: All prose escaped via escapeProse — no raw < or > outside code/Mermaid
• assertion: Table cells escaped via escapeTableCell — no raw < or > or unescaped pipes
• assertion: VitePress build succeeds without template compilation errors

Implementation

• Primary: src/generators/technicalDesign.ts
• Test code: tests/technicalDesign.test.ts
• Test code status: manual