architecture-document

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