# dell/azurestack-docs architecture

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

- Interactive diagram: https://gitdiagram.com/dell/azurestack-docs
- Repository: https://github.com/dell/azurestack-docs

## Overview

##### Project Type and Purpose
- This is a static site generator project built on Hugo (a Go-based framework) that produces documentation for Azure Stack Hub and Azure Local.
- The repository contains content (Markdown), templates, styling assets (SCSS/JS), configuration, and CI/CD workflows for automated deployment.

##### File Structure
Top-level components:
- .github/workflows/deploy.yml – GitHub Actions pipeline to build & deploy
- config/ – Hugo configuration (default, development, production)
- content/ – Markdown pages (internationalized docs tree under content/en)
- layouts/ – Hugo templates (partials, shortcodes)
- i18n/ – Localization files (en.toml)
- go.mod / go.sum – Hugo (and possibly custom Go modules) dependencies
- package.json / package-lock.json – npm-based tooling for frontend (if any)
- README.md – high-level project description
- .gitmodules – submodule references (if any)

##### Read README for Additional Insight
- Confirms open-source, community-driven documentation site under Apache 2.0

A. Developer Workspace
1. Content (Markdown in content/)
2. Templates & Shortcodes (layouts/)
4. Static assets (static/)
5. Config (config/)
B. Build Engine
1. Hugo CLI (Go application invoked locally or in CI)
2. npm (optional – for Sass compilation or JS bundling if used)
C. CI/CD Pipeline
1. GitHub Actions (deploy.yml)
2. Build container or runner (pulls code, invokes Hugo, npm)
3. Deployment step (push public/ to Azure Static Web Hosting, GitHub Pages, or CDN)
D. Hosting & Delivery
1. Azure (or chosen host) serving the generated HTML/CSS/JS
2. CDN (optional) for caching
E. End Users
- Browsers that consume the static site

##### Relationships and Data Flow
1. Developer commits Markdown, templates, assets → GitHub repo.
2. GitHub Actions triggers on push → Checkout code.
3. Build step: install Hugo (from go.mod), run `hugo --environment production`.
4. Hugo reads config/, content/, layouts/, assets/, i18n/.
5. Hugo Pipes or npm compile SCSS → CSS, process JS.
6. Output directory (public/) contains final HTML/CSS/JS/static files.
7. CI deploys public/ to Azure Storage or GitHub Pages.
8. CDN (if configured) pulls from origin.
9. End users request pages → CDN/host serves static assets.

##### Architectural Patterns & Design Principles
- Static Site Generation (SSG) – content separation from presentation
- “Write once, deploy anywhere” – portable static output
- CI/CD Automation – reproducible builds
- Single Repo Monorepo – all content, configuration, and assets versioned together
- Internationalization – i18n folder supplies translations

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Developer Workspace"
        direction TB
        Content["Developer Content (Markdown)"]:::developer
        click Content "https://github.com/dell/azurestack-docs/tree/main/content/"
        Templates["Developer Templates & Shortcodes"]:::developer
        click Templates "https://github.com/dell/azurestack-docs/tree/main/layouts/"
        SCSS["Developer SCSS & Icon Assets"]:::developer
        click SCSS "https://github.com/dell/azurestack-docs/tree/main/assets/"
        StaticAssets["Developer Static Assets (CSS/JS/Favicons)"]:::developer
        click StaticAssets "https://github.com/dell/azurestack-docs/tree/main/static/"
        ConfigDefault["Hugo Config (default)"]:::developer
        click ConfigDefault "https://github.com/dell/azurestack-docs/blob/main/config/_default/config.toml"
        ConfigDev["Hugo Config (development)"]:::developer
        click ConfigDev "https://github.com/dell/azurestack-docs/blob/main/config/development/config.toml"
        ConfigProd["Hugo Config (production)"]:::developer
        click ConfigProd "https://github.com/dell/azurestack-docs/blob/main/config/production/config.toml"
        I18n["Localization Files (en.toml)"]:::developer
        click I18n "https://github.com/dell/azurestack-docs/blob/main/i18n/en.toml"
        GoMod["go.mod"]:::developer
        click GoMod "https://github.com/dell/azurestack-docs/blob/main/go.mod"
        GoSum["go.sum"]:::developer
        click GoSum "https://github.com/dell/azurestack-docs/blob/main/go.sum"
        Npm["Frontend Tooling (npm)"]:::developer
        click Npm "https://github.com/dell/azurestack-docs/blob/main/package.json"
        click Npm "https://github.com/dell/azurestack-docs/blob/main/package-lock.json"
        Submodule["Submodule Config (.gitmodules)"]:::developer
        click Submodule "https://github.com/dell/azurestack-docs/blob/main/.gitmodules"
        Readme["README.md"]:::developer
        click Readme "https://github.com/dell/azurestack-docs/blob/main/README.md"
    end

    Developer["Developer Workstation"]:::external
    GitRepo["GitHub Repository"]:::external

    Developer -->|Commits| GitRepo
    GitRepo -->|Triggers| ActionsRunner

    subgraph "CI/CD Pipeline"
        direction TB
        ActionsRunner["GitHub Actions Runner"]:::process
        click ActionsRunner "https://github.com/dell/azurestack-docs/blob/main/.github/workflows/deploy.yml"
        Checkout["Checkout Code"]:::process
    end

    ActionsRunner --> Checkout

    subgraph "Build Engine"
        direction TB
        Hugo["Hugo CLI"]:::process
        NpmBuild["npm (Sass/JS Bundling)"]:::process
    end

    Checkout --> Hugo
    Checkout --> NpmBuild

    Hugo --> Public["public/ (Generated Site)"]:::output
    NpmBuild --> Public

    subgraph "Hosting & Delivery"
        direction TB
        Azure["Azure Static Hosting"]:::external
        CDN["CDN"]:::external
    end

    Public -->|"Deploy"| Azure
    Azure -->|"Cache"| CDN

    subgraph "End Users"
        Browser["Web Browsers"]:::external
    end

    CDN --> Browser

    classDef developer fill:#cce5ff,stroke:#004085
    classDef process fill:#d4edda,stroke:#155724
    classDef external fill:#fff3cd,stroke:#856404
    classDef output fill:#e2e3e5,stroke:#6c757d
```
