# dasharo/docs architecture

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

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

## Overview

##### Main components
- Documentation Content Sources – the extensive “docs” directory structure (with subfolders for variants, unified documentation, guides, and more) represents the raw Markdown that forms the content.
- Static Site Generator – MkDocs, driven by the mkdocs.yml configuration file, is responsible for converting Markdown files into a static HTML site.
- Build & Local Development Environment – a Python virtual environment set up via requirements.txt and commands outlined in the README (e.g. “mkdocs serve”, with options for address changes and the “--dirty” flag for live previews).
- Quality and Consistency Tools – pre-commit hooks, linters (.yamllint, .markdownlint.yaml, .pre-commit-config.yaml), and link checking utilities (lychee; also available as a Docker image).
- CI/CD & Deployment – GitHub workflows defined in the .github/workflows directory (for example, deploy.yml and seo.yml) which automatically trigger on pushes/PRs. These ensure continuous integration, link validation, and deployment of the freshly built site.

##### Relationships and interactions
- The “docs” folder feeds directly into the MkDocs build process. The MkDocs engine reads the configuration (mkdocs.yml), parses subdirectories, and generates a static site.
- The build process (invoked locally or on a CI server via GitHub Actions) integrates the quality tools (pre-commit, linters, lychee link checker) before site generation.
- GitHub Actions take the updated source (Markdown content, configuration files, assets, etc.), run automated tests and validations, and then trigger a deploy workflow that pushes the generated site to production.
- The local development process (using virtualenv and pip) isolates dependencies and allows a quick preview of changes through “mkdocs serve.”

##### Important architectural patterns or design principles
- Separation of Concerns – content is separated into manageable directories (e.g. hardware variants, guides, unified project pages) with the build system (MkDocs) handling compilation.
- Automation and QA Integration – use of pre-commit hooks, linters, and CI workflows maintains content quality and prevents broken links (via lychee).
- Modularity – the repo organizes each documentation type (and even each hardware platform variant) into its own subdirectory, promoting a modular structure.
- Static Site Generation – emphasizes reproducible builds and fast, static output that can be hosted anywhere.

##### Relevant technologies and libraries
- MkDocs (Python-based static site generator)
- Python virtualenv and pip (dependency management)
- Pre-commit framework (with several hooks such as codespell, markdownlint, yamllint)
- GitHub Actions workflows (for automated deployment and SEO validation)
- lychee (Rust-based link checker, used via Docker if necessary)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Documentation Components
    DCS["Documentation Sources"]:::source
    DA["Documentation Assets (UML)"]:::assets

    %% Build & Development Components
    MKB["MkDocs Build Process"]:::build
    LD1["VirtualEnv & Dependencies"]:::dev
    LD2["Local Dev Server (README)"]:::dev

    %% Quality & Consistency Tools
    PC["Pre-commit Config"]:::qa
    ML["Markdown Lint"]:::qa
    YL["YAML Lint"]:::qa
    CS["Codespell Config"]:::qa
    CX["Codespell Extra"]:::qa
    LY["Lychee Ignore"]:::qa

    %% CI/CD Pipeline Components
    DEP["Deploy Workflow"]:::cicd
    SEO["SEO Workflow"]:::cicd

    %% Relationships
    DCS -->|"feeds"| MKB
    DA -->|"assetsIncluded"| MKB
    LD1 -->|"setup"| MKB
    LD2 -->|"serve"| MKB

    MKB -->|"triggerDeploy"| DEP
    MKB -->|"triggerDeploy"| SEO

    DCS -->|"sourceUpdate"| DEP
    DCS -->|"sourceUpdate"| SEO

    PC -->|"qualityCheck"| DEP
    ML -->|"qualityCheck"| DEP
    YL -->|"qualityCheck"| DEP
    CS -->|"qualityCheck"| DEP
    CX -->|"qualityCheck"| DEP
    LY -->|"qualityCheck"| DEP

    PC -->|"qualityCheck"| SEO
    ML -->|"qualityCheck"| SEO
    YL -->|"qualityCheck"| SEO
    CS -->|"qualityCheck"| SEO
    CX -->|"qualityCheck"| SEO
    LY -->|"qualityCheck"| SEO

    LD1 -->|"editPreview"| DCS
    LD2 -->|"editPreview"| DCS

    %% Styles
    classDef source fill:#cce5ff,stroke:#004085,stroke-width:2px,color:#002752;
    classDef assets fill:#d4edda,stroke:#155724,stroke-width:2px,color:#0c5460;
    classDef build fill:#fff3cd,stroke:#856404,stroke-width:2px,color:#856404;
    classDef dev fill:#f8d7da,stroke:#721c24,stroke-width:2px,color:#721c24;
    classDef qa fill:#d1ecf1,stroke:#0c5460,stroke-width:2px,color:#0c5460;
    classDef cicd fill:#d6d8d9,stroke:#343a40,stroke-width:2px,color:#343a40;

    %% Click Events
    click DCS "https://github.com/dasharo/docs/tree/master/docs/"
    click DA "https://github.com/dasharo/docs/tree/master/uml/"
    click MKB "https://github.com/dasharo/docs/blob/master/mkdocs.yml"
    click LD1 "https://github.com/dasharo/docs/blob/master/requirements.txt"
    click LD2 "https://github.com/dasharo/docs/blob/master/README.md"
    click PC "https://github.com/dasharo/docs/blob/master/.pre-commit-config.yaml"
    click ML "https://github.com/dasharo/docs/blob/master/.markdownlint.yaml"
    click YL "https://github.com/dasharo/docs/blob/master/.yamllint"
    click CS "https://github.com/dasharo/docs/blob/master/.codespellrc"
    click CX "https://github.com/dasharo/docs/blob/master/.codespellx"
    click LY "https://github.com/dasharo/docs/blob/master/.lycheeignore"
    click DEP "https://github.com/dasharo/docs/blob/master/.github/workflows/deploy.yml"
    click SEO "https://github.com/dasharo/docs/blob/master/.github/workflows/seo.yml"
```
