HLD Generator

Generate professional High-Level Design (HLD) documents for Azure infrastructure following the enterprise standard defined in docs/standards/hld-template-standard.md.

Modes

1. Template Mode (Default)

Creates a blank HLD template with all required sections pre-structured for manual completion.

Output: Architecture/Templates/HLD/hld-template.md

Usage: Invoke skill without arguments or with --template

2. Customer Mode

Generates a populated HLD document by analyzing existing Bicep/Terraform infrastructure code.

Output: Architecture/Customer/[customercode]/hld/[project-name]-hld.md

Usage: Provide customer code and project name as arguments

Instructions

Step 1: Determine Mode and Gather Information

Auto-detect mode based on arguments:

• •If customer code path provided: Customer Mode
• •If no arguments or --template flag: Template Mode

For Customer Mode, collect:

• •Customer code identifier (e.g., "contoso", "fabrikam")
• •Project name
• •Optional: Specific infrastructure code path to analyze

For Template Mode:

• •No additional information needed

Step 2: Read Required Standards

Always read these standard documents:

1. •docs/standards/hld-template-standard.md - HLD structure and requirements
2. •docs/standards/naming-convention.md - Azure resource naming standards
3. •docs/standards/ip-addressing-scheme.md - Network IP allocation strategy

These provide the foundation for generating compliant HLD documents.

Step 3: Template Mode Process

If generating a template HLD:

1. •

   Copy the pre-built template:

   • •Use templates/hld-template.md as the base
   • •Replace placeholder values with [TO BE COMPLETED] markers
2. •

   Create output directory:

   bash

   mkdir -p Architecture/Templates/HLD
   

3. •

   Write template file:

   • •Output: Architecture/Templates/HLD/hld-template.md
   • •Include all required sections from the standard
   • •Add helpful comments and guidance in each section
4. •

   Inform user:

   • •Confirm template created successfully
   • •Provide path to the generated template
   • •Suggest next steps for customization

Step 4: Customer Mode Process

If generating a customer-specific HLD:

4.1 Analyze Infrastructure Code

1. •

   Discover infrastructure files:

   • •Use Glob to find Bicep files: **/*.bicep
   • •Use Glob to find Terraform files: **/*.tf
   • •Focus on main/root modules and landing zone code
2. •

   Read and analyze key files:

   • •

     Bicep: Look for:

     • •Management group definitions
     • •Subscription resources
     • •VNet and network configurations
     • •Policy assignments
     • •Resource naming patterns
     • •Tags and metadata
   • •

     Terraform: Look for:

     • •Management group modules
     • •Subscription configurations
     • •Network topology (hub-spoke)
     • •Policy definitions
     • •Variable files for naming and IP ranges
3. •

   Extract architecture details:

   • •Management group hierarchy
   • •Subscription strategy (platform vs landing zones)
   • •Network topology (hub-spoke, vWAN)
   • •IP address ranges (reference ip-addressing-scheme.md)
   • •Security controls (NSGs, Azure Firewall, Defender)
   • •Governance policies
   • •Monitoring and backup strategy
   • •Identity services (Azure AD, domain services)
   • •Naming conventions used

4.2 Generate HLD Content

Use the template structure and populate with extracted data:

1. •

   Document Properties:

   • •Project: [Extracted from code or user input]
   • •Client: [Customer code]
   • •Version: 1.0
   • •Date: Current date
   • •Author: AI-Generated (to be reviewed)
   • •Status: Draft
2. •

   Introduction:

   • •Background: Infer from infrastructure purpose
   • •Purpose: Describe the Azure Landing Zone architecture
   • •Scope: Based on resources found in code
3. •

   Architecture Overview:

   • •Design Principles: Extract from policy assignments and architecture patterns
   • •High-Level Architecture: Describe based on code structure
   • •Note: Add placeholder for diagram - "[DIAGRAM: Insert architecture diagram here]"
4. •

   Management Groups and Subscriptions:

   • •Extract hierarchy from code
   • •Document subscription strategy
   • •Reference naming-convention.md for naming patterns
5. •

   Network Design:

   • •Topology: Identify hub-spoke or vWAN from code
   • •IP Addressing: Extract VNet ranges and validate against ip-addressing-scheme.md
   • •Connectivity: Document VPN/ExpressRoute/Bastion based on resources found
   • •DNS: Identify DNS configuration from code
6. •

   Identity and Access:

   • •Extract identity resources (Azure AD, domain controllers)
   • •Document RBAC assignments if present
   • •Note PIM usage if configured
7. •

   Security and Governance:

   • •List Azure Policy assignments found
   • •Document security resources (Firewall, NSGs, Defender)
   • •Extract tagging requirements from code
8. •

   Monitoring and Operations:

   • •Document Log Analytics workspace configuration
   • •Extract backup policies if present
   • •Note monitoring solutions deployed
9. •

   Azure Region:

   • •Extract primary region from code
   • •Note multi-region setup if present
10. •

    Naming Convention:

    • •Summarize naming patterns found in code
    • •Reference naming-convention.md
11. •

    References:

    • •Always link to:
      • •naming-convention.md
      • •ip-addressing-scheme.md
      • •Microsoft Cloud Adoption Framework
      • •Azure Well-Architected Framework

4.3 Save Customer HLD

1. •

   Create output directory:

   bash

   mkdir -p Architecture/Customer/[customercode]/hld
   

2. •

   Write HLD file:

   • •Filename: [project-name]-hld.md
   • •Full path: Architecture/Customer/[customercode]/hld/[project-name]-hld.md
3. •

   Add review notes:

   • •Include note at top: "This HLD was auto-generated from infrastructure code. Please review and validate all sections."
   • •Mark sections that need manual review with [REVIEW REQUIRED]

Step 5: Quality Validation

Before finalizing, verify:

• • All required sections from hld-template-standard.md are present
• • Document follows high-level focus (no implementation details)
• • References to naming-convention.md and ip-addressing-scheme.md included
• • Version history table included
• • Diagram placeholders added where appropriate
• • No IP subnet details (only ranges) - keep it high-level
• • No VM SKUs or detailed configurations - that's LLD content
• • Professional formatting with proper markdown structure
• • Cross-references are accurate

Step 6: User Guidance

After generating the HLD:

1. •

   Confirm completion:

   • •Report the file path where HLD was saved
   • •Summarize what was generated
2. •

   Next steps guidance:

   • •Template Mode: "Customize the template by filling in [TO BE COMPLETED] sections"
   • •Customer Mode: "Review auto-generated content, especially sections marked [REVIEW REQUIRED]"
   • •Suggest creating architecture diagrams for section 3.2
   • •Recommend stakeholder review before finalizing
3. •

   Related documentation:

   • •Point to the standards used (naming-convention.md, ip-addressing-scheme.md)
   • •Suggest creating LLD (Low-Level Design) documents next
   • •Reference hld-template-standard.md for detailed guidance

Arguments

Template Mode

/hld-generator
/hld-generator --template

Customer Mode

/hld-generator --customer <customercode> --project <project-name>
/hld-generator --customer contoso --project azure-landing-zone
/hld-generator --customer fabrikam --project hub-spoke-network --path infrastructure/bicep

Arguments:

• •--customer <code>: Customer identifier (e.g., contoso, fabrikam)
• •--project <name>: Project name for the HLD filename
• •--path <path>: Optional specific path to infrastructure code to analyze
• •--template: Explicitly request template mode (default if no customer specified)

Examples

Example 1: Generate Template HLD

User request: "Create a blank HLD template"

Skill action:

1. •Read hld-template-standard.md
2. •Copy templates/hld-template.md
3. •Create Architecture/Templates/HLD/ directory
4. •Write hld-template.md with all required sections
5. •Confirm: "Template HLD created at Architecture/Templates/HLD/hld-template.md"

Example 2: Generate Customer HLD from Code

User request: "/hld-generator --customer contoso --project azure-landing-zone"

Skill action:

1. •Read standards (hld-template-standard.md, naming-convention.md, ip-addressing-scheme.md)
2. •Search for Bicep/Terraform files in repository
3. •Analyze files:
   • •Found management group hierarchy in bicep/management-groups.bicep
   • •Extracted hub-spoke topology from bicep/networking/hub.bicep and bicep/networking/spoke.bicep
   • •Identified policy assignments in bicep/policies/
   • •Found IP ranges: Hub 10.0.0.0/16, Spokes 10.10.0.0/16, 10.11.0.0/16
4. •Generate HLD with extracted details:
   • •Document Properties: Client=Contoso, Project=Azure Landing Zone
   • •Architecture Overview: Hub-spoke with centralized security
   • •Network Design: Hub 10.0.0.0/16 in Connectivity subscription, spokes peer to hub
   • •Security: Azure Firewall in hub, NSGs on subnets, Defender enabled
   • •Policies: Naming convention enforcement, allowed regions (West Europe)
5. •Create directory: Architecture/Customer/contoso/hld/
6. •Write: azure-landing-zone-hld.md
7. •Confirm: "Customer HLD generated at Architecture/Customer/contoso/hld/azure-landing-zone-hld.md. Review sections marked [REVIEW REQUIRED]."

Example 3: Generate HLD for Specific Code Path

User request: "/hld-generator --customer fabrikam --project network-infrastructure --path infrastructure/terraform/networking"

Skill action:

1. •Read standards
2. •Focus analysis on infrastructure/terraform/networking/ directory
3. •Analyze Terraform files:
   • •main.tf: Hub VNet configuration
   • •variables.tf: IP ranges and naming variables
   • •spoke.tf: Spoke VNet modules
4. •Generate HLD focusing on network design sections
5. •Save to: Architecture/Customer/fabrikam/hld/network-infrastructure-hld.md

Best Practices

Keep It High-Level

• •Focus on "what" and "why", not "how"
• •Avoid specific IP subnets (use ranges only)
• •No VM SKUs or resource sizes
• •No detailed configuration parameters
• •No step-by-step procedures

Architecture Extraction Tips

• •Management Groups: Look for hierarchy in code structure
• •Subscriptions: Identify from module organization or subscription resources
• •Network Topology: Analyze peering relationships and VNet structure
• •Security: Extract from policy assignments, NSG definitions, firewall rules
• •Naming: Observe patterns in resource names throughout code

Documentation Quality

• •Add diagram placeholders with clear descriptions
• •Reference standards documents instead of duplicating content
• •Use tables for structured information (version history, management groups)
• •Include cross-references to related sections
• •Mark auto-generated assumptions for review

Code Analysis Limitations

• •Cannot extract: Business context, background, project justification
• •May miss: Undocumented design decisions, verbal agreements, external dependencies
• •Requires review: All generated content should be validated by architects

Troubleshooting

Issue: No infrastructure code found Solution:

• •Verify the repository contains Bicep or Terraform files
• •Check if --path argument points to correct directory
• •Fall back to template mode if no code available

Issue: Generated HLD is too detailed Solution:

• •Review against hld-template-standard.md section "What Does NOT Belong in HLD"
• •Remove implementation details, specific configurations, resource group names
• •Keep only architecture-level information

Issue: Cannot determine network topology Solution:

• •Add placeholder: "[TOPOLOGY: Review and document hub-spoke or vWAN architecture]"
• •Mark section as [REVIEW REQUIRED]
• •Suggest manual completion based on infrastructure intent

Issue: IP ranges don't match ip-addressing-scheme.md Solution:

• •Document the discrepancy in HLD
• •Add note: "[REVIEW: IP ranges deviate from standard - verify if intentional]"
• •Reference the standard and note the variance

Requirements

Standards Documents (must exist):

• •docs/standards/hld-template-standard.md
• •docs/standards/naming-convention.md
• •docs/standards/ip-addressing-scheme.md

Output Directories:

• •Template mode: Architecture/Templates/HLD/
• •Customer mode: Architecture/Customer/[customercode]/hld/

Supported Code Formats:

• •Azure Bicep (.bicep)
• •Terraform (.tf)
• •ARM Templates (.json) - limited support

Related Skills

• •azure-landingzone-generator: Generate infrastructure code that HLD documents
• •azure-workload-generator: Generate workload infrastructure to document
• •skill-maker: Create additional documentation skills

References

• •HLD Template Standard
• •Naming Convention Standard
• •IP Addressing Scheme
• •Microsoft Cloud Adoption Framework
• •Azure Landing Zone Architecture