From 9576dcb3157e6946d6158aedf847a7a44e22d3b5 Mon Sep 17 00:00:00 2001
From: geoffsee <>
Date: Sat, 16 Aug 2025 10:32:17 -0400
Subject: [PATCH] improve diagraming again

---
 README.md | 125 +++++++++++++++++-------------------------------------
 1 file changed, 39 insertions(+), 86 deletions(-)

diff --git a/README.md b/README.md
index 5dace46..08d81ba 100644
--- a/README.md
+++ b/README.md
@@ -23,90 +23,61 @@ packages/
 ## Architecture
 
 ```mermaid
-%%{init: {
-  'theme': 'default',
-  'flowchart': { 'rankSpacing': 60, 'nodeSpacing': 60, 'diagramPadding': 48, 'htmlLabels': true },
-  'themeVariables': { 'fontSize': '18px', 'fontFamily': 'Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Helvetica, Arial, Noto Sans, sans-serif' }
-}}%%
-flowchart TB
+flowchart LR
 
-%% =========================
-%% Local Machine (Entry Path)
-%% =========================
-subgraph local[Local Machine]
+%% ===== Local Machine =====
+subgraph L[Local Machine]
 direction TB
-user[Developer Browser]
-proxy[localhost-proxy<br/>HTTP → HTTPS]
-host[localhost Port<br/>Mapping Layer]
-registry[Local Docker Registry<br/>localhost:5001]
-user -->|HTTP :3000| proxy
-proxy -->|HTTPS :443| host
+  user[Developer Browser]
+  proxy[localhost-proxy HTTP]
+  host[Port Mapping Layer]
+  registry[Local Docker Registry]
+
+  user -->|HTTP 3000| proxy
+  proxy -->|HTTPS 443| host
 end
 
-%% =========================
-%% Kind Cluster (Platform)
-%% =========================
-subgraph clusterSG[Kind Cluster — Local Kubernetes]
+%% ===== Kind Cluster =====
+subgraph K[Kind Cluster]
 direction TB
+  ingress[Ingress Controller]
+  exampleApp[Example Web App]
+  apps[Backend Services]
+  zitadel[ZITADEL IAM]
+  pg[(PostgreSQL Identity Store)]
+  cert[Cert-Manager]
 
-%% Edge / Entry
-ingress[Ingress Controller<br/>Kubernetes Entry Point]
+  %% Routing
+  ingress --> exampleApp
+  ingress --> apps
 
-%% Workloads behind ingress
-subgraph workloads[Workloads]
-direction LR
-exampleApp[Example Web App<br/>Frontend UI]
-apps[Backend Services<br/>Microservices API]
+  %% OIDC
+  exampleApp -->|OIDC: /authorize, /callback| zitadel
+  apps -->|Validate OIDC tokens| zitadel
+  zitadel --> pg
+
+  %% TLS automation (dotted)
+  cert -.-> ingress
+  cert -.-> exampleApp
+  cert -.-> apps
+  cert -.-> zitadel
 end
 
-%% Identity & Data
-subgraph iam[Identity & Access]
-direction TB
-zitadel[ZITADEL IAM<br/>OIDC Provider]
-pg[(PostgreSQL<br/>Identity Store)]
-zitadel --> pg
-end
+%% ===== Local ⇄ Cluster =====
+host -->|80 -> 30080, 443 -> 30443| ingress
 
-%% Cluster automation
-cert[Cert-Manager<br/>Automated TLS]
-
-%% Ingress routing to services
-ingress --> exampleApp
-ingress --> apps
-
-%% OIDC flows
-exampleApp -->|OIDC: /authorize, /callback| zitadel
-apps -->|Validate OIDC tokens| zitadel
-
-%% Cert-manager relationships (dotted = automation/control)
-cert -.-> ingress
-cert -.-> exampleApp
-cert -.-> apps
-cert -.-> zitadel
-end
-
-%% =========================
-%% Image pulls into the cluster
-%% =========================
+%% ===== Images into the cluster =====
 registry -->|image pulls| exampleApp
 registry -->|image pulls| apps
 
-%% =========================
-%% Local → Cluster networking
-%% =========================
-host -->|80 → 30080<br/>443 → 30443| ingress
-
-%% =========================
-%% CDKTF Stacks (Provision & Configure)
-%% =========================
-subgraph cdk[CDKTF Stacks]
+%% ===== CDKTF Stacks =====
+subgraph T[CDKTF Stacks]
 direction TB
-clusterStack[cluster — Provisions K8s]
-componentsStack[components — Ingress, Cert-Manager, ZITADEL]
-configurationsStack[configurations — App Deployments & Config]
+  clusterStack[cluster]
+  componentsStack[components]
+  configurationsStack[configurations]
 end
 
-%% Show where each stack applies
 clusterStack --> ingress
 componentsStack --> ingress
 componentsStack --> cert
@@ -114,24 +85,6 @@ componentsStack --> zitadel
 configurationsStack --> exampleApp
 configurationsStack --> apps
 
-%% =========================
-%% Visual styling
-%% =========================
-classDef external fill:#E8F1FF,stroke:#3B82F6,color:#111,stroke-width:1px;
-classDef service  fill:#F8FAFC,stroke:#64748B,color:#111,stroke-width:1px;
-classDef identity fill:#FFF7E6,stroke:#F59E0B,color:#111,stroke-width:1px;
-classDef data     fill:#FDEDED,stroke:#EF4444,color:#111,stroke-width:1px;
-classDef ops      fill:#ECFDF5,stroke:#10B981,color:#111,stroke-width:1px;
-classDef infra    fill:#EEF2FF,stroke:#6366F1,color:#111,stroke-width:1px;
-
-class user,proxy,host,registry external
-class ingress,workloads infra
-class exampleApp,apps service
-class zitadel identity
-class pg data
-class cert ops
-class clusterStack,componentsStack,configurationsStack infra
-
 ```
 
 Access the dev UI at http://localhost:3000. The localhost-proxy accepts HTTP on port 3000 and forwards HTTPS to localhost:443; the Kind cluster maps host ports 80 -> 30080 and 443 -> 30443 to the ingress controller inside the cluster. Traffic is routed through ingress to services secured by ZITADEL and PostgreSQL, with Cert-Manager handling TLS. CDKTF provisions the cluster, core components, and app configs, using a local Docker registry for images.