Skip to content

feat: add architecture overview page with Mermaid diagram#43

Open
lbajsarowicz wants to merge 1 commit intowardenenv:mainfrom
lbajsarowicz:feat/architecture-diagram
Open

feat: add architecture overview page with Mermaid diagram#43
lbajsarowicz wants to merge 1 commit intowardenenv:mainfrom
lbajsarowicz:feat/architecture-diagram

Conversation

@lbajsarowicz
Copy link
Contributor

Summary

  • Add new Architecture Overview page to the documentation with an interactive Mermaid diagram
  • Add sphinxcontrib-mermaid extension for rendering Mermaid diagrams during Sphinx build
  • Add page to the "Getting Started" toctree (between "Installing" and "Services")
  • Exclude .venv from Sphinx build in .gitignore and conf.py

The architecture page documents Warden's three service layers with:

  • A visual diagram (see preview below)
  • Service tables with URLs and toggle flags
  • Descriptions of all optional services (Blackfire, SPX, Selenium, Allure, etc.)

Architecture Diagram Preview

flowchart TB
    classDef default fill:#ffffff,stroke:#3f51b5,stroke-width:1.5px,color:#000000,font-weight:bold,font-size:12px;

    subgraph DevSys ["Developer's System"]
        direction TB

        subgraph Host ["Host Services"]
            direction LR
            h1["Warden CLI"] ~~~ h2["Docker Engine"] ~~~ h3["Mutagen File Sync"] ~~~ h4["Trusted SSL Root CA"]
        end

        subgraph Global ["Global Docker Services — warden svc up"]
            direction LR
            g1["Traefik<br>Reverse Proxy + SSL"] ~~~ g2["DNSmasq"] ~~~ g3["Mailpit<br>Email Catcher"] ~~~ g4["SSH Tunnel"] ~~~ g5["phpMyAdmin"] ~~~ g6["Portainer"]
        end

        subgraph Project ["Per-Project Docker Services — warden env up"]
            direction LR
            p1["Nginx"] ~~~ p2["PHP-FPM"] ~~~ p3["MariaDB / MySQL"] ~~~ p4["Redis / Valkey"] ~~~ p5["Elasticsearch /<br>OpenSearch"] ~~~ p6["RabbitMQ"] ~~~ p7["Varnish"]
        end

        Host ~~~ Global ~~~ Project
    end

    style DevSys fill:#f5f5f5,stroke:#666666,stroke-width:1px,rx:8,ry:8
    style Host fill:transparent,stroke:none
    style Global fill:#fff3e0,stroke:#FF9800,stroke-width:1px,rx:8,ry:8
    style Project fill:#e8f5e9,stroke:#4CAF50,stroke-width:1px,stroke-dasharray: 5 5,rx:8,ry:8
Loading

Test plan

  • Run pip install -r requirements.txt && make html — verify architecture.html renders the Mermaid diagram
  • Check the diagram renders correctly on the Architecture Overview page
  • Verify the toctree includes the new page between "Installing" and "Services"

⭐ Support my work

Do you like the fix? Remember to react with "👍🏻" to get it merged faster,
Then Sponsor me on Github so I can spend more time on fixing issues like this one.

Learn more at https://github.com/sponsors/lbajsarowicz

Add visual architecture diagram showing Warden's three service layers:
- Host Services (CLI, Docker Engine, Mutagen, SSL Root CA)
- Global Docker Services (Traefik, DNSmasq, Mailpit, SSH Tunnel, phpMyAdmin, Portainer)
- Per-Project Docker Services (Nginx, PHP-FPM, DB, Redis, ES, RabbitMQ, Varnish)

Uses Mermaid rendered via sphinxcontrib-mermaid during Sphinx build.
Includes service tables with toggle flags and optional service descriptions.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant