HLD Generator

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:

   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:

   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