# inabubblewithyou/azure-documenter-tool architecture

> Architecture diagram of the GitHub repository inabubblewithyou/azure-documenter-tool, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/inabubblewithyou/azure-documenter-tool
- Repository: https://github.com/inabubblewithyou/azure-documenter-tool

## Overview

##### Project Type and Purpose
- This is a CLI-based Python utility (“Azure Documenter Tool”) whose purpose is to inventory, analyze, and document Azure environments.

##### High-Level Architectural Components
a. CLI Orchestrator
- azure_documenter/main.py: entry point, parses CLI options (mode, subscriptions, flags), loads configuration, drives the workflow.
b. Configuration Layer
- azure_documenter/config.py: holds settings (authentication, output paths, LLM provider config).
c. Data-Access/Fetch Layer
- azure_documenter/fetchers/: modules that call Azure APIs (via DefaultAzureCredential) across categories (compute, network, storage, security, etc.).
- Each fetcher returns JSON-serializable data.
d. Analysis & Reporting Layer
- azure_documenter/generators/: orchestrates data consumption and builds outputs.
- analysis_helpers.py: data transformations, summaries, delta computations.
- delta_report_writer.py: builds “Compare” mode outputs.
- design_document_writer.py: high-level architecture and recommendations.
- markdown_writer.py & html_exporter.py: convert analysis into Markdown/HTML.
- llm_writer.py: optional AI-enhanced summaries (requires LLM provider).
e. Output Store
f. External Dependencies
- Azure Resource Manager APIs
- Optional LLM endpoints (Azure OpenAI / OpenAI)
- Python runtime & third-party libraries from requirements.txt

##### Relationships & Data Flow
1. User invokes main.py → CLI Parser
2. Config loaded → Authentication context created
3. Fetchers sequentially invoke Azure SDK → raw resource data collected
4. Raw JSON data saved to outputs/data/
5. Generators consume JSON:
- analysis_helpers perform aggregations or delta comparisons
- design_document_writer builds high-level docs
- delta_report_writer builds diff reports
- markdown_writer + html_exporter produce navigable reports in outputs/reports/
- llm_writer optionally inserts AI-generated insights
6. Logs written throughout to outputs/logs/

##### Architectural Patterns & Principles
- Modular Separation of Concerns:
- Fetch-only modules (data layer)
- Generator modules (presentation layer)
- Single orchestrator (main)
- Config isolated from code
- Pipeline Workflow: CLI → Fetch → Save → Generate → Export
- Extensibility Points:
- New fetchers for additional Azure services
- Plug in new writers (e.g., PDF exporter)
- Swap LLM provider via config
- Idempotent Outputs:
- Versioned JSON data files support Compare & Regenerate modes

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    Azure["Azure Resource Manager APIs"]:::external
    LLM["LLM Service"]:::external

    %% CLI Orchestrator and Config
    CLI(["azure_documenter/main.py\nCLI Orchestrator"]):::orchestrator
    Config(["azure_documenter/config.py\nConfiguration"]):::config

    %% Fetch Layer
    subgraph "Fetch Layer"
        direction TB
        AI["ai_services.py"]:::fetcher
        Compute["compute.py"]:::fetcher
        Costs["costs.py"]:::fetcher
        Database["database.py"]:::fetcher
        Governance["governance.py"]:::fetcher
        Identity["identity.py"]:::fetcher
        KeyVault["keyvault.py"]:::fetcher
        Monitor["monitor.py"]:::fetcher
        Network["network.py"]:::fetcher
        Resources["resources.py"]:::fetcher
        Scaling["scaling.py"]:::fetcher
        Security["security.py"]:::fetcher
        Storage["storage.py"]:::fetcher
        Web["web.py"]:::fetcher
    end

    %% Data Store
    DataStore(["outputs/data/\nJSON Store"]):::datastore

    %% Generators Layer
    subgraph "Analysis & Reporting Layer"
        direction TB
        Helpers(["analysis_helpers.py"]):::generator
        DeltaReport["delta_report_writer.py"]:::generator
        DesignDoc["design_document_writer.py"]:::generator
        DiagramGen["diagram_generator.py"]:::generator
        MDWriter["markdown_writer.py"]:::generator
        HTMLExp["html_exporter.py"]:::generator
        LLWriter["llm_writer.py"]:::generator
    end

    %% Output Artifacts
    Reports(["outputs/reports/\nMarkdown & HTML"]):::document
    Diagrams(["outputs/diagrams/\nPNG Diagrams"]):::document
    Logs(["outputs/logs/"]):::document

    %% Workflow
    CLI -->|"parse CLI & drive workflow"| Config
    CLI -->|"invoke fetchers"| AI
    CLI --> Compute
    CLI --> Costs
    CLI --> Database
    CLI --> Governance
    CLI --> Identity
    CLI --> KeyVault
    CLI --> Monitor
    CLI --> Network
    CLI --> Resources
    CLI --> Scaling
    CLI --> Security
    CLI --> Storage
    CLI --> Web

    AI -->|"Fetch AI Services"| Azure
    Compute -->|"Fetch Compute"| Azure
    Costs -->|"Fetch Costs"| Azure
    Database -->|"Fetch Database"| Azure
    Governance -->|"Fetch Governance"| Azure
    Identity -->|"Fetch Identity"| Azure
    KeyVault -->|"Fetch Key Vault"| Azure
    Monitor -->|"Fetch Monitor"| Azure
    Network -->|"Fetch Network"| Azure
    Resources -->|"Fetch Resources"| Azure
    Scaling -->|"Fetch Scaling"| Azure
    Security -->|"Fetch Security"| Azure
    Storage -->|"Fetch Storage"| Azure
    Web -->|"Fetch Web"| Azure

    AI -->|"return JSON"| DataStore
    Compute --> DataStore
    Costs --> DataStore
    Database --> DataStore
    Governance --> DataStore
    Identity --> DataStore
    KeyVault --> DataStore
    Monitor --> DataStore
    Network --> DataStore
    Resources --> DataStore
    Scaling --> DataStore
    Security --> DataStore
    Storage --> DataStore
    Web --> DataStore

    DataStore -->|"--mode Default|Consume JSON"| Helpers
    DataStore -->|"--mode Compare"| DeltaReport

    Helpers -->|aggregate & summarize| DeltaReport
    Helpers -->|aggregate & summarize| DesignDoc
    DeltaReport -->|write diff reports| Reports
    DesignDoc -->|write design docs| Reports

    DataStore --> DiagramGen
    DiagramGen -->|generate diagrams| Diagrams

    Helpers --> MDWriter
    MDWriter -->|write Markdown| Reports

    Helpers --> HTMLExp
    HTMLExp -->|write HTML| Reports

    Helpers --> LLWriter
    LLWriter -->|AI summaries| Reports
    LLWriter -->|"call LLM"| LLM

    %% Logging
    CLI --> Logs
    Config --> Logs
    AI --> Logs
    Helpers --> Logs
    DeltaReport --> Logs
    DiagramGen --> Logs
    MDWriter --> Logs
    HTMLExp --> Logs
    LLWriter --> Logs

    %% Click Events
    click CLI "https://github.com/inabubblewithyou/azure-documenter-tool/blob/main/azure_documenter/main.py"
    click Config "https://github.com/inabubblewithyou/azure-documenter-tool/blob/main/azure_documenter/config.py"
    click AI "https://github.com/inabubblewithyou/azure-documenter-tool/blob/main/azure_documenter/fetchers/ai_services.py"
    click Compute "https://github.com/inabubblewithyou/azure-documenter-tool/blob/main/azure_documenter/fetchers/compute.py"
    click Costs "https://github.com/inabubblewithyou/azure-documenter-tool/blob/main/azure_documenter/fetchers/costs.py"
    click Database "https://github.com/inabubblewithyou/azure-documenter-tool/blob/main/azure_documenter/fetchers/database.py"
    click Governance "https://github.com/inabubblewithyou/azure-documenter-tool/blob/main/azure_documenter/fetchers/governance.py"
    click Identity "https://github.com/inabubblewithyou/azure-documenter-tool/blob/main/azure_documenter/fetchers/identity.py"
    click KeyVault "https://github.com/inabubblewithyou/azure-documenter-tool/blob/main/azure_documenter/fetchers/keyvault.py"
    click Monitor "https://github.com/inabubblewithyou/azure-documenter-tool/blob/main/azure_documenter/fetchers/monitor.py"
    click Network "https://github.com/inabubblewithyou/azure-documenter-tool/blob/main/azure_documenter/fetchers/network.py"
    click Resources "https://github.com/inabubblewithyou/azure-documenter-tool/blob/main/azure_documenter/fetchers/resources.py"
    click Scaling "https://github.com/inabubblewithyou/azure-documenter-tool/blob/main/azure_documenter/fetchers/scaling.py"
    click Security "https://github.com/inabubblewithyou/azure-documenter-tool/blob/main/azure_documenter/fetchers/security.py"
    click Storage "https://github.com/inabubblewithyou/azure-documenter-tool/blob/main/azure_documenter/fetchers/storage.py"
    click Web "https://github.com/inabubblewithyou/azure-documenter-tool/blob/main/azure_documenter/fetchers/web.py"
    click Helpers "https://github.com/inabubblewithyou/azure-documenter-tool/blob/main/azure_documenter/generators/analysis_helpers.py"
    click DeltaReport "https://github.com/inabubblewithyou/azure-documenter-tool/blob/main/azure_documenter/generators/delta_report_writer.py"
    click DesignDoc "https://github.com/inabubblewithyou/azure-documenter-tool/blob/main/azure_documenter/generators/design_document_writer.py"
    click DiagramGen "https://github.com/inabubblewithyou/azure-documenter-tool/blob/main/azure_documenter/generators/diagram_generator.py"
    click MDWriter "https://github.com/inabubblewithyou/azure-documenter-tool/blob/main/azure_documenter/generators/markdown_writer.py"
    click HTMLExp "https://github.com/inabubblewithyou/azure-documenter-tool/blob/main/azure_documenter/generators/html_exporter.py"
    click LLWriter "https://github.com/inabubblewithyou/azure-documenter-tool/blob/main/azure_documenter/generators/llm_writer.py"

    %% Styles
    classDef external fill:#cce5ff,stroke:#3399ff,color:#004085,stroke-width:1px;
    classDef orchestrator fill:#e2e3e5,stroke:#d6d8db,color:#383d41,stroke-width:1px;
    classDef config fill:#f8f9fa,stroke:#ced4da,color:#6c757d,stroke-width:1px;
    classDef fetcher fill:#d4edda,stroke:#28a745,color:#155724,stroke-width:1px;
    classDef generator fill:#fff3cd,stroke:#ffc107,color:#856404,stroke-width:1px;
    classDef datastore fill:#ffffff,stroke:#6c757d,color:#343a40,stroke-width:1px,stroke-dasharray: 5 5;
    classDef document fill:#f5e6ff,stroke:#bf5fff,color:#6f42c1,stroke-width:1px;
```
