Skip to content

Commit 90d2195

Browse files
lbajsarowiczlbajsarowicz
committed
feat: add architecture overview page with Mermaid diagram
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.
1 parent 5422dde commit 90d2195

5 files changed

Lines changed: 87 additions & 2 deletions

File tree

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,3 @@
11
/_build
2+
/d2lang_svg
3+
/.venv

‎architecture.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Architecture Overview
2+
3+
Warden runs three layers of services on your development machine:
4+
5+
```{mermaid}
6+
flowchart TB
7+
classDef default fill:#ffffff,stroke:#3f51b5,stroke-width:1.5px,color:#000000,font-weight:bold,font-size:12px;
8+
9+
subgraph DevSys ["Developer's System"]
10+
direction TB
11+
12+
subgraph Host ["Host Services"]
13+
direction LR
14+
h1["Warden CLI"] ~~~ h2["Docker Engine"] ~~~ h3["Mutagen File Sync"] ~~~ h4["Trusted SSL Root CA"]
15+
end
16+
17+
subgraph Global ["Global Docker Services — warden svc up"]
18+
direction LR
19+
g1["Traefik<br>Reverse Proxy + SSL"] ~~~ g2["DNSmasq"] ~~~ g3["Mailpit<br>Email Catcher"] ~~~ g4["SSH Tunnel"] ~~~ g5["phpMyAdmin"] ~~~ g6["Portainer"]
20+
end
21+
22+
subgraph Project ["Per-Project Docker Services — warden env up"]
23+
direction LR
24+
p1["Nginx"] ~~~ p2["PHP-FPM"] ~~~ p3["MariaDB / MySQL"] ~~~ p4["Redis / Valkey"] ~~~ p5["Elasticsearch /<br>OpenSearch"] ~~~ p6["RabbitMQ"] ~~~ p7["Varnish"]
25+
end
26+
27+
Host ~~~ Global ~~~ Project
28+
end
29+
30+
style DevSys fill:#f5f5f5,stroke:#666666,stroke-width:1px,rx:8,ry:8
31+
style Host fill:transparent,stroke:none
32+
style Global fill:#fff3e0,stroke:#FF9800,stroke-width:1px,rx:8,ry:8
33+
style Project fill:#e8f5e9,stroke:#4CAF50,stroke-width:1px,stroke-dasharray: 5 5,rx:8,ry:8
34+
```
35+
36+
## Host Services
37+
38+
The Warden CLI orchestrates everything via Docker Compose. On your host machine:
39+
40+
- **Warden CLI** — Bash tool that manages all Docker services
41+
- **Docker Engine** — Runs all containers
42+
- **Mutagen** — Bi-directional file sync between host and containers (macOS)
43+
- **Trusted SSL Root CA** — Local certificate authority for `*.test` HTTPS domains
44+
45+
## Global Docker Services
46+
47+
Started once with `warden svc up`, shared across all projects:
48+
49+
| Service | Purpose | URL |
50+
|---------|---------|-----|
51+
| Traefik | Reverse proxy + SSL termination | traefik.warden.test |
52+
| DNSmasq | DNS resolver for `*.test` domains | — |
53+
| Mailpit | Email catcher (SMTP) | webmail.warden.test |
54+
| SSH Tunnel | Database access for GUI clients (:2222) | — |
55+
| phpMyAdmin | Database management UI | phpmyadmin.warden.test |
56+
| Portainer | Container management UI (opt-in) | portainer.warden.test |
57+
58+
## Per-Project Docker Services
59+
60+
Started per project with `warden env up`, each on an isolated Docker network:
61+
62+
| Service | Default | Toggle Flag |
63+
|---------|---------|-------------|
64+
| Nginx | All types | `WARDEN_NGINX` |
65+
| PHP-FPM | All types | — |
66+
| MariaDB / MySQL | All types | `WARDEN_DB` |
67+
| Redis / Valkey | All types | `WARDEN_REDIS` / `WARDEN_VALKEY` |
68+
| Elasticsearch / OpenSearch | Magento 2 | `WARDEN_ELASTICSEARCH` / `WARDEN_OPENSEARCH` |
69+
| RabbitMQ | Magento 2 | `WARDEN_RABBITMQ` |
70+
| Varnish | Magento 2 | `WARDEN_VARNISH` |
71+
72+
### Additional Optional Services
73+
74+
These can be enabled per-project via flags in your `.env` file:
75+
76+
- **Blackfire** / **SPX** — PHP profiling (`WARDEN_BLACKFIRE`, `WARDEN_PHP_SPX`)
77+
- **Selenium** — Browser automation testing with optional VNC (`WARDEN_SELENIUM`)
78+
- **Allure** — Test report dashboard (`WARDEN_ALLURE`)
79+
- **PHP-Debug** — Xdebug-enabled PHP-FPM (used via `warden debug`)
80+
- **ElasticHQ** — Elasticsearch management UI (`WARDEN_ELASTICHQ`)

‎conf.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@
2323
'sphinx_rtd_theme',
2424
'sphinx_copybutton',
2525
'sphinx_markdown_tables',
26+
'sphinxcontrib.mermaid',
2627
]
2728

2829
source_suffix = ['.rst', '.md']
@@ -34,7 +35,7 @@
3435
version = ''
3536
release = ''
3637

37-
exclude_patterns = ['_build']
38+
exclude_patterns = ['_build', '.venv']
3839

3940
html_theme = "sphinx_rtd_theme"
4041
html_show_sourcelink = False

‎index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ caption: Getting Started
2020
---
2121
2222
installing
23+
architecture
2324
services
2425
usage
2526
environments

‎requirements.txt‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,5 @@ sphinx-copybutton==0.5.2
44
sphinx-markdown-tables==0.0.17
55
sphinx-rtd-theme==3.0.2
66
myst-parser==4.0.0
7-
Jinja2==3.1.6
7+
Jinja2==3.1.6
8+
sphinxcontrib-mermaid

0 commit comments

Comments
 (0)