Architecture Document Generator

Produce formal High-Level Design (HLD) and Low-Level Design (LLD) documents from the project's living docs/Architecture.md and codebase.

Project Context — Read project-config.md for brand tokens, org name, tech stack, and project metadata used in document headers.
Document metadata — Any Markdown companion doc or source doc created or updated in this workflow must follow .github/instructions/document-frontmatter.instructions.md. For DOCX/PPTX deliverables, mirror the same author/date/model fields on the cover page or revision history.

When to Load This Skill

• Stakeholder requests a formal architecture deliverable
• Audit or compliance review requires documented HLD/LLD
• Onboarding pack for new team members
• Architecture review board submission
• Project milestone that requires design documentation

Prerequisites

Before generating, ensure:

1. docs/Architecture.md exists and is current (the @architect agent maintains this)
2. Architecture diagrams exist in docs/architecture/*.drawio (or .png exports)
3. project-config.md has a profile set (for org name, tech stack, branding)

Output Formats

Format	Skill to Load	Best For
DOCX (recommended)	.github/skills/document-skills/docx/SKILL.md	Full HLD/LLD — editable, ToC, numbered sections
PPTX	.github/skills/document-skills/pptx/SKILL.md	Executive summary / architecture overview deck
PDF	.github/skills/document-skills/pdf/SKILL.md	Final read-only distribution (generate from DOCX)

---

HLD — High-Level Design

Document Structure

COVER PAGE
    Project: <APP_TITLE>
    Organization: <ORG_NAME>
    Document Type: High-Level Design (HLD)
    Version: {from Architecture.md front-matter or git tag}
    Date: {current date}
    Author: {architect or team}
    Status: Draft | Under Review | Approved
    Classification: Internal | Confidential

REVISION HISTORY
    | Version | Date | Author | Changes |

APPROVAL TABLE
    | Role | Name | Signature | Date |

TABLE OF CONTENTS (auto-generated)

§1  INTRODUCTION
    §1.1  Purpose
    §1.2  Scope
    §1.3  Audience
    §1.4  References & Related Documents
    §1.5  Glossary & Abbreviations

§2  EXECUTIVE SUMMARY
    - Business context (1-2 paragraphs)
    - Solution overview (1-2 paragraphs)
    - Key architectural decisions summary

§3  SYSTEM CONTEXT
    §3.1  System Context Diagram (C4 Level 1)
    §3.2  External Systems & Interfaces
    §3.3  User Roles & Access Patterns
    §3.4  Data Sources

§4  ARCHITECTURE OVERVIEW
    §4.1  Architecture Style & Patterns
    §4.2  Component Architecture Diagram (C4 Level 2)
    §4.3  Component Descriptions
          (table: Component | Responsibility | Technology | Interfaces)
    §4.4  Technology Stack Summary

§5  DATA ARCHITECTURE
    §5.1  Data Flow Diagram
    §5.2  Data Sources & Stores
    §5.3  Data Integration Patterns
    §5.4  Data Retention & Archival

§6  INTEGRATION ARCHITECTURE
    §6.1  Integration Patterns (sync/async, push/pull)
    §6.2  API Overview (endpoints, protocols)
    §6.3  External System Interfaces
    §6.4  Message Flows / Event Flows

§7  DEPLOYMENT ARCHITECTURE
    §7.1  Deployment Diagram
    §7.2  Infrastructure Components
    §7.3  Environment Strategy (Dev/UAT/Prod)
    §7.4  Scaling & High Availability

§8  SECURITY ARCHITECTURE
    §8.1  Authentication & Authorization
    §8.2  Data Protection (at rest, in transit)
    §8.3  Network Security
    §8.4  Compliance Requirements

§9  NON-FUNCTIONAL REQUIREMENTS
    §9.1  Performance Targets
    §9.2  Availability & Reliability
    §9.3  Scalability
    §9.4  Maintainability
    §9.5  Observability (logging, monitoring, alerting)

§10  ARCHITECTURAL DECISIONS
    §10.1  Key Decisions Log (ADR summary table)
    §10.2  Alternatives Considered
    §10.3  Constraints & Trade-offs

§11  RISKS & MITIGATIONS
    (table: Risk | Likelihood | Impact | Mitigation)

§12  APPENDICES
    §A  Full Diagram Index
    §B  Glossary
    §C  Referenced Documents

Content Sourcing

HLD Section	Source
§1 Introduction	project-config.md (org, tech stack) + README.md
§2 Executive Summary	docs/Architecture.md introduction/overview
§3 System Context	docs/Architecture.md context sections + docs/architecture/system-context.drawio
§4 Architecture Overview	docs/Architecture.md component sections + diagrams
§5 Data Architecture	docs/Architecture.md data sections + project-config.md data sources
§6 Integration	docs/Architecture.md API/integration sections
§7 Deployment	docs/Architecture.md deployment sections + project-config.md deploy env
§8 Security	docs/Architecture.md security sections + project-config.md compliance
§9 NFRs	docs/Architecture.md NFR sections
§10 Decisions	docs/architecture/ ADR files or decisions section
§11 Risks	docs/Architecture.md risks section (or flag if missing)

---

LLD — Low-Level Design

Document Structure

COVER PAGE (same format as HLD, Document Type: Low-Level Design)
REVISION HISTORY
APPROVAL TABLE
TABLE OF CONTENTS

§1  INTRODUCTION
    §1.1  Purpose
    §1.2  Scope (which HLD components this LLD covers)
    §1.3  HLD Reference (link to HLD document + version)

§2  MODULE DESIGN
    §2.1  Module Overview Diagram
    §2.2  Module Descriptions
          For each module:
          - Responsibility
          - Public interface (functions/methods/endpoints)
          - Dependencies (internal + external)
          - Configuration

§3  DATA MODEL
    §3.1  Entity Relationship Diagram
    §3.2  Table Definitions
          (table: Table | Columns | Types | Constraints | Indexes)
    §3.3  Data Validation Rules
    §3.4  Migration Strategy

§4  API DESIGN
    §4.1  API Endpoints
          (table: Method | Path | Request | Response | Auth | Rate Limit)
    §4.2  Request/Response Schemas (with examples)
    §4.3  Error Codes & Handling
    §4.4  Versioning Strategy

§5  SEQUENCE DIAGRAMS
    §5.1  Key User Flows
          (one sequence diagram per critical flow)
    §5.2  Error / Edge Case Flows
    §5.3  Background Process Flows

§6  CLASS / MODULE STRUCTURE
    §6.1  Package/Module Hierarchy
    §6.2  Key Classes & Responsibilities
    §6.3  Design Patterns Used
    §6.4  Dependency Injection / Configuration

§7  CACHING & STATE MANAGEMENT
    §7.1  Caching Strategy
          (table: Layer | Object | Strategy | TTL | Invalidation)
    §7.2  Session State Management
    §7.3  Serialization Constraints

§8  ERROR HANDLING & RESILIENCE
    §8.1  Error Classification
    §8.2  Retry Strategies
    §8.3  Circuit Breaker Patterns
    §8.4  Logging & Observability

§9  CONFIGURATION & ENVIRONMENT
    §9.1  Environment Variables
    §9.2  Feature Flags
    §9.3  Configuration Files
    §9.4  Secrets Management

§10  TESTING STRATEGY
    §10.1  Unit Test Approach
    §10.2  Integration Test Approach
    §10.3  E2E Test Scenarios
    §10.4  Performance Test Plan

§11  APPENDICES
    §A  Full Class Diagram
    §B  Database Schema DDL
    §C  Sample API Payloads

Content Sourcing

LLD Section	Source
§2 Module Design	Codebase scan (src/ structure) + docs/Architecture.md
§3 Data Model	Database schema + project-config.md data sources
§4 API Design	FastAPI route inspection or API docs
§5 Sequence Diagrams	Generate from codebase call flows
§6 Class Structure	Codebase scan (imports, classes, modules)
§7 Caching	docs/Architecture.md caching sections + codebase
§8 Error Handling	Codebase patterns (try/catch, error types)
§9 Configuration	.env.example, config.py, project-config.md
§10 Testing	Test files + docs/Architecture.md testing strategy

---

Generation Workflow

Step 1: Gather Sources

1. Read docs/Architecture.md (full content)
2. Read project-config.md (profile, tech stack, org name)
3. List docs/architecture/*.drawio and *.png (diagram inventory)
4. If LLD: scan src/ for module structure, key classes, API routes

Step 2: Determine Scope

Ask the user:

• HLD, LLD, or both?
• Output format? DOCX (recommended), PPTX (exec summary), or both?
• Which components? Full system or specific subsystem?

Step 3: Assemble Content

Map each section to its source (see Content Sourcing tables above). For each section:

• If source content exists → extract and format
• If source is thin → flag with [TODO: Expand — insufficient detail in Architecture.md]
• If source is missing → flag with [MISSING: No content found — update Architecture.md first]

Step 4: Generate Document

Load the appropriate document skill:

• DOCX: Load .github/skills/document-skills/docx/SKILL.md — use OOXML for professional formatting
• PPTX: Load .github/skills/document-skills/pptx/SKILL.md — use html2pptx workflow

Step 5: Output

Save to:

• docs/deliverables/HLD-{project-name}-v{version}.docx
• docs/deliverables/LLD-{project-name}-v{version}.docx
• docs/deliverables/Architecture-Overview-{project-name}-v{version}.pptx

---

Formatting Standards

Enterprise Document Conventions

• Font: Arial or Calibri, 11pt body, 14pt headings
• Section numbering: §1, §1.1, §1.1.1 (three levels max)
• Tables: Bordered, header row shaded with brand primary color
• Diagrams: Captioned ("Figure N: Description"), referenced in text
• Page headers: Project name + Document type + "CONFIDENTIAL" (if applicable)
• Page footers: Page N of M + Version + Date
• Line spacing: 1.15 for body text
• Margins: 2.5cm all sides

Diagram Embedding

For DOCX:

• Embed .png exports of .drawio diagrams
• Caption each figure: "Figure {N}: {Description}"
• Reference in text: "See Figure {N}"

For PPTX:

• One diagram per slide (full-width)
• Slide title = diagram caption
• Speaker notes = brief description

Quality Checklist

Before delivering:

• Every section has content or explicit [TODO] marker
• All diagrams embedded and captioned
• Table of Contents generated and correct
• Revision history has current entry
• Cover page has correct project name, org, date
• No placeholder tokens (<ORG_NAME> etc.) remain — all resolved from project-config.md
• Section numbering is consistent and sequential
• Cross-references (e.g., "See §4.2") point to correct sections