Skip to content

Commit be0a9cc

Browse files
lweberrulweberru
committed
docs(diagrams): regenerate Mermaid artifacts and workflow docs
Closes #7
1 parent 59faa22 commit be0a9cc

8 files changed

Lines changed: 1383 additions & 0 deletions

‎.vscode/extensions.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{
2+
"recommendations": [
3+
"bierner.markdown-mermaid",
4+
"d8aware.vscode-mermaid-extension"
5+
]
6+
}

‎.vscode/settings.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{
2+
"files.associations": {
3+
"*.mmd": "mermaid",
4+
"*.mmd.md": "markdown"
5+
}
6+
}

‎docs/diagram-generation.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Terraform Example Diagram Generation (MVP)
2+
3+
This repository includes a small MVP generator that creates Mermaid architecture diagrams from Terraform module usage in the examples.
4+
5+
## Generate diagrams
6+
7+
Run from repository root:
8+
9+
```bash
10+
python3 scripts/generate_example_architecture.py
11+
```
12+
13+
Default behavior:
14+
15+
- scans all `main.tf` files under `examples/**`
16+
- generates one Mermaid markdown file per discovered example
17+
18+
Generate for one specific example folder only:
19+
20+
```bash
21+
python3 scripts/generate_example_architecture.py --example-folder examples/02-hub-spoke
22+
```
23+
24+
Use overview mode (default, recommended for readability):
25+
26+
```bash
27+
python3 scripts/generate_example_architecture.py --example-folder examples/02-hub-spoke --detail-level theme
28+
```
29+
30+
Use full resource-level details:
31+
32+
```bash
33+
python3 scripts/generate_example_architecture.py --example-folder examples/02-hub-spoke --detail-level full
34+
```
35+
36+
You can also point to another examples root:
37+
38+
```bash
39+
python3 scripts/generate_example_architecture.py --examples-root examples
40+
```
41+
42+
Generated files:
43+
44+
- `docs/diagrams/01-standalone-architecture.mmd.md`
45+
- `docs/diagrams/02-hub-spoke-architecture.mmd.md`
46+
- `docs/diagrams/01-standalone-architecture.mmd`
47+
- `docs/diagrams/02-hub-spoke-architecture.mmd`
48+
49+
## Preview `.md` and `.mmd` directly in VS Code
50+
51+
This repository is configured to preview Mermaid without converting to HTML or SVG first.
52+
53+
1. Install the recommended workspace extensions when VS Code prompts you:
54+
- `bierner.markdown-mermaid`
55+
- `d8aware.vscode-mermaid-extension`
56+
2. Open a Markdown diagram file (for example `docs/diagrams/02-hub-spoke-architecture.mmd.md`) and run `Markdown: Open Preview to the Side` (`Cmd+K V`).
57+
3. Open a raw Mermaid file (for example `docs/diagrams/02-hub-spoke-architecture.mmd`) and run the Mermaid preview command from the Command Palette (`Cmd+Shift+P`, then search for `Mermaid` + `Preview`).
58+
59+
Notes:
60+
61+
- `.mmd` is mapped to Mermaid language in `.vscode/settings.json`.
62+
- `.mmd.md` is mapped to Markdown and rendered by the built-in Markdown preview.
63+
64+
## What is modeled
65+
66+
- Module blocks from the example `main.tf` files
67+
- Module dependencies inferred from `module.<name>` references inside module blocks
68+
- Module-internal Terraform resources (derived from `modules/*/*.tf`) as child elements
69+
- Two levels are available:
70+
- `theme` (default): grouped architecture themes per module (better overview)
71+
- `full`: all detected resource types per module
72+
- High-level grouping into:
73+
- Resource Manager
74+
- Connectivity
75+
- Projects
76+
77+
This is intentionally a fast MVP. It can later be extended with richer semantics from Terragrunt and additional rules.
78+
79+
Generated diagrams now include semantic styling (colors/icons) and a legend to distinguish architecture domains such as Networking, Compute, Kubernetes, Storage, and Access/RBAC.

‎docs/diagrams/01-standalone-architecture.mmd‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
flowchart TB
2+
%% STACKIT architecture from 01-standalone
3+
4+
org["🏢 Organization"]
5+
folders["🗂️ Folder Hierarchy"]
6+
shared_network_area["🌐 Shared Network Area"]
7+
8+
subgraph resource_manager["Resource Manager"]
9+
governance["Governance"]
10+
end
11+
12+
subgraph projects["Projects"]
13+
devops["DevOps"]
14+
management["Management"]
15+
sandboxes["Sandboxes"]
16+
landing_zone["Landing Zones"]
17+
end
18+
19+
governance -->|provisions| devops
20+
governance -->|provisions| landing_zone
21+
governance -->|provisions| management
22+
governance -->|provisions| sandboxes
23+
24+
org -->|contains| folders
25+
org -->|scope| shared_network_area
26+
folders -->|managed by| governance
27+
folders -->|contains project| devops
28+
folders -->|contains project| management
29+
folders -->|contains project| sandboxes
30+
folders -->|contains project| landing_zone
31+
shared_network_area -.->|optional attachment| landing_zone
32+
33+
subgraph governance_details["Governance details"]
34+
direction TB
35+
governance__folder_hierarchy["🗂️ Folder Hierarchy"]
36+
governance__access_rbac["🔐 Access & RBAC"]
37+
end
38+
governance -.->|organizes| governance__folder_hierarchy
39+
governance -.->|settings| governance__access_rbac
40+
subgraph devops_details["DevOps details"]
41+
direction TB
42+
devops__git["🛠️ Git"]
43+
devops__access_rbac["🔐 Access & RBAC"]
44+
end
45+
devops -.->|enables| devops__git
46+
devops -.->|settings| devops__access_rbac
47+
subgraph management_details["Management details"]
48+
direction TB
49+
management__object_storage["🪣 Object Storage"]
50+
management__secrets["🗝️ Secrets"]
51+
management__service_accounts["👤 Service Accounts"]
52+
management__platform_observability["📈 Platform Observability"]
53+
management__access_rbac["🔐 Access & RBAC"]
54+
end
55+
management -.->|hosts| management__object_storage
56+
management -.->|secures| management__secrets
57+
management -.->|auth| management__service_accounts
58+
management -.->|observes| management__platform_observability
59+
management -.->|settings| management__access_rbac
60+
subgraph sandboxes_details["Sandboxes details"]
61+
direction TB
62+
sandboxes__sandbox_projects["🧪 Sandbox Projects"]
63+
sandboxes__access_rbac["🔐 Access & RBAC"]
64+
end
65+
sandboxes -.->|contains| sandboxes__sandbox_projects
66+
sandboxes -.->|settings| sandboxes__access_rbac
67+
subgraph landing_zone_details["Landing Zones details"]
68+
direction TB
69+
landing_zone__project_network["🌐 Project Network"]
70+
landing_zone__kubernetes["☸️ Kubernetes"]
71+
landing_zone__object_storage["🪣 Object Storage"]
72+
landing_zone__secrets["🗝️ Secrets"]
73+
landing_zone__service_accounts["👤 Service Accounts"]
74+
landing_zone__access_rbac["🔐 Access & RBAC"]
75+
end
76+
landing_zone -.->|connects| landing_zone__project_network
77+
landing_zone -.->|hosts| landing_zone__kubernetes
78+
landing_zone -.->|hosts| landing_zone__object_storage
79+
landing_zone -.->|secures| landing_zone__secrets
80+
landing_zone -.->|auth| landing_zone__service_accounts
81+
landing_zone -.->|settings| landing_zone__access_rbac
82+
83+
subgraph legend["Legend"]
84+
direction TB
85+
lg_network["🌐 Networking"]
86+
lg_compute["🖥️ Compute"]
87+
lg_k8s["☸️ Kubernetes"]
88+
lg_storage["🪣 Storage"]
89+
lg_access["🔐 Access & RBAC"]
90+
end
91+
92+
classDef module_foundation fill:#e8f1ff,stroke:#2f6feb,stroke-width:2px,color:#102a43;
93+
classDef module_connectivity fill:#e9fbff,stroke:#00758f,stroke-width:2px,color:#073642;
94+
classDef module_projects fill:#f5f0ff,stroke:#6f42c1,stroke-width:2px,color:#2d1b4e;
95+
classDef module_other fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#111827;
96+
classDef sem_foundation fill:#edf5ff,stroke:#3b82f6,color:#0f172a;
97+
classDef sem_access fill:#fef3c7,stroke:#d97706,color:#4a2f00;
98+
classDef sem_network fill:#cffafe,stroke:#0891b2,color:#083344;
99+
classDef sem_compute fill:#fee2e2,stroke:#ef4444,color:#7f1d1d;
100+
classDef sem_kubernetes fill:#ede9fe,stroke:#7c3aed,color:#2e1065;
101+
classDef sem_storage fill:#dcfce7,stroke:#16a34a,color:#14532d;
102+
classDef sem_secrets fill:#ffe4e6,stroke:#e11d48,color:#4a0719;
103+
classDef sem_identity fill:#fef9c3,stroke:#ca8a04,color:#422006;
104+
classDef sem_observability fill:#e0e7ff,stroke:#6366f1,color:#1e1b4b;
105+
classDef sem_devops fill:#ffedd5,stroke:#ea580c,color:#431407;
106+
classDef sem_supporting fill:#f3f4f6,stroke:#6b7280,color:#111827;
107+
classDef sem_other fill:#f9fafb,stroke:#9ca3af,color:#1f2937;
108+
class org sem_foundation;
109+
class folders sem_foundation;
110+
class shared_network_area sem_network;
111+
class governance module_foundation;
112+
class devops module_projects;
113+
class management module_projects;
114+
class sandboxes module_projects;
115+
class landing_zone module_projects;
116+
class governance__folder_hierarchy sem_foundation;
117+
class governance__access_rbac sem_access;
118+
class devops__git sem_devops;
119+
class devops__access_rbac sem_access;
120+
class management__object_storage sem_storage;
121+
class management__secrets sem_secrets;
122+
class management__service_accounts sem_identity;
123+
class management__platform_observability sem_observability;
124+
class management__access_rbac sem_access;
125+
class sandboxes__sandbox_projects sem_foundation;
126+
class sandboxes__access_rbac sem_access;
127+
class landing_zone__project_network sem_network;
128+
class landing_zone__kubernetes sem_kubernetes;
129+
class landing_zone__object_storage sem_storage;
130+
class landing_zone__secrets sem_secrets;
131+
class landing_zone__service_accounts sem_identity;
132+
class landing_zone__access_rbac sem_access;
133+
class lg_network sem_network;
134+
class lg_compute sem_compute;
135+
class lg_k8s sem_kubernetes;
136+
class lg_storage sem_storage;
137+
class lg_access sem_access;

‎docs/diagrams/01-standalone-architecture.mmd.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
# Architecture Diagram: 01-standalone
2+
3+
Generated from `examples/01-standalone/main.tf`.
4+
```mermaid
5+
flowchart TB
6+
%% STACKIT architecture from 01-standalone
7+
8+
org["🏢 Organization"]
9+
folders["🗂️ Folder Hierarchy"]
10+
shared_network_area["🌐 Shared Network Area"]
11+
12+
subgraph resource_manager["Resource Manager"]
13+
governance["Governance"]
14+
end
15+
16+
subgraph projects["Projects"]
17+
devops["DevOps"]
18+
management["Management"]
19+
sandboxes["Sandboxes"]
20+
landing_zone["Landing Zones"]
21+
end
22+
23+
governance -->|provisions| devops
24+
governance -->|provisions| landing_zone
25+
governance -->|provisions| management
26+
governance -->|provisions| sandboxes
27+
28+
org -->|contains| folders
29+
org -->|scope| shared_network_area
30+
folders -->|managed by| governance
31+
folders -->|contains project| devops
32+
folders -->|contains project| management
33+
folders -->|contains project| sandboxes
34+
folders -->|contains project| landing_zone
35+
shared_network_area -.->|optional attachment| landing_zone
36+
37+
subgraph governance_details["Governance details"]
38+
direction TB
39+
governance__folder_hierarchy["🗂️ Folder Hierarchy"]
40+
governance__access_rbac["🔐 Access & RBAC"]
41+
end
42+
governance -.->|organizes| governance__folder_hierarchy
43+
governance -.->|settings| governance__access_rbac
44+
subgraph devops_details["DevOps details"]
45+
direction TB
46+
devops__git["🛠️ Git"]
47+
devops__access_rbac["🔐 Access & RBAC"]
48+
end
49+
devops -.->|enables| devops__git
50+
devops -.->|settings| devops__access_rbac
51+
subgraph management_details["Management details"]
52+
direction TB
53+
management__object_storage["🪣 Object Storage"]
54+
management__secrets["🗝️ Secrets"]
55+
management__service_accounts["👤 Service Accounts"]
56+
management__platform_observability["📈 Platform Observability"]
57+
management__access_rbac["🔐 Access & RBAC"]
58+
end
59+
management -.->|hosts| management__object_storage
60+
management -.->|secures| management__secrets
61+
management -.->|auth| management__service_accounts
62+
management -.->|observes| management__platform_observability
63+
management -.->|settings| management__access_rbac
64+
subgraph sandboxes_details["Sandboxes details"]
65+
direction TB
66+
sandboxes__sandbox_projects["🧪 Sandbox Projects"]
67+
sandboxes__access_rbac["🔐 Access & RBAC"]
68+
end
69+
sandboxes -.->|contains| sandboxes__sandbox_projects
70+
sandboxes -.->|settings| sandboxes__access_rbac
71+
subgraph landing_zone_details["Landing Zones details"]
72+
direction TB
73+
landing_zone__project_network["🌐 Project Network"]
74+
landing_zone__kubernetes["☸️ Kubernetes"]
75+
landing_zone__object_storage["🪣 Object Storage"]
76+
landing_zone__secrets["🗝️ Secrets"]
77+
landing_zone__service_accounts["👤 Service Accounts"]
78+
landing_zone__access_rbac["🔐 Access & RBAC"]
79+
end
80+
landing_zone -.->|connects| landing_zone__project_network
81+
landing_zone -.->|hosts| landing_zone__kubernetes
82+
landing_zone -.->|hosts| landing_zone__object_storage
83+
landing_zone -.->|secures| landing_zone__secrets
84+
landing_zone -.->|auth| landing_zone__service_accounts
85+
landing_zone -.->|settings| landing_zone__access_rbac
86+
87+
subgraph legend["Legend"]
88+
direction TB
89+
lg_network["🌐 Networking"]
90+
lg_compute["🖥️ Compute"]
91+
lg_k8s["☸️ Kubernetes"]
92+
lg_storage["🪣 Storage"]
93+
lg_access["🔐 Access & RBAC"]
94+
end
95+
96+
classDef module_foundation fill:#e8f1ff,stroke:#2f6feb,stroke-width:2px,color:#102a43;
97+
classDef module_connectivity fill:#e9fbff,stroke:#00758f,stroke-width:2px,color:#073642;
98+
classDef module_projects fill:#f5f0ff,stroke:#6f42c1,stroke-width:2px,color:#2d1b4e;
99+
classDef module_other fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#111827;
100+
classDef sem_foundation fill:#edf5ff,stroke:#3b82f6,color:#0f172a;
101+
classDef sem_access fill:#fef3c7,stroke:#d97706,color:#4a2f00;
102+
classDef sem_network fill:#cffafe,stroke:#0891b2,color:#083344;
103+
classDef sem_compute fill:#fee2e2,stroke:#ef4444,color:#7f1d1d;
104+
classDef sem_kubernetes fill:#ede9fe,stroke:#7c3aed,color:#2e1065;
105+
classDef sem_storage fill:#dcfce7,stroke:#16a34a,color:#14532d;
106+
classDef sem_secrets fill:#ffe4e6,stroke:#e11d48,color:#4a0719;
107+
classDef sem_identity fill:#fef9c3,stroke:#ca8a04,color:#422006;
108+
classDef sem_observability fill:#e0e7ff,stroke:#6366f1,color:#1e1b4b;
109+
classDef sem_devops fill:#ffedd5,stroke:#ea580c,color:#431407;
110+
classDef sem_supporting fill:#f3f4f6,stroke:#6b7280,color:#111827;
111+
classDef sem_other fill:#f9fafb,stroke:#9ca3af,color:#1f2937;
112+
class org sem_foundation;
113+
class folders sem_foundation;
114+
class shared_network_area sem_network;
115+
class governance module_foundation;
116+
class devops module_projects;
117+
class management module_projects;
118+
class sandboxes module_projects;
119+
class landing_zone module_projects;
120+
class governance__folder_hierarchy sem_foundation;
121+
class governance__access_rbac sem_access;
122+
class devops__git sem_devops;
123+
class devops__access_rbac sem_access;
124+
class management__object_storage sem_storage;
125+
class management__secrets sem_secrets;
126+
class management__service_accounts sem_identity;
127+
class management__platform_observability sem_observability;
128+
class management__access_rbac sem_access;
129+
class sandboxes__sandbox_projects sem_foundation;
130+
class sandboxes__access_rbac sem_access;
131+
class landing_zone__project_network sem_network;
132+
class landing_zone__kubernetes sem_kubernetes;
133+
class landing_zone__object_storage sem_storage;
134+
class landing_zone__secrets sem_secrets;
135+
class landing_zone__service_accounts sem_identity;
136+
class landing_zone__access_rbac sem_access;
137+
class lg_network sem_network;
138+
class lg_compute sem_compute;
139+
class lg_k8s sem_kubernetes;
140+
class lg_storage sem_storage;
141+
class lg_access sem_access;
142+
```

0 commit comments

Comments
 (0)