From 01b7048c10ee3981467020ad2e16f0f3fb433806 Mon Sep 17 00:00:00 2001 From: Joshua Temple Date: Fri, 12 Jun 2026 20:30:18 -0400 Subject: [PATCH] docs: add cascade-themed mermaid diagrams to readme and docs Signed-off-by: Joshua Temple --- README.md | 58 +++++++++--------- docs/astro.config.mjs | 21 +++++++ docs/src/content/docs/architecture.md | 85 +++++++++++---------------- docs/src/content/docs/workflows.md | 70 +++++++--------------- 4 files changed, 106 insertions(+), 128 deletions(-) diff --git a/README.md b/README.md index 8e6853cf..3bc04e5d 100644 --- a/README.md +++ b/README.md @@ -36,36 +36,36 @@ The **manifest** (`.github/manifest.yaml`) is the single source of truth. It holds both the pipeline configuration and the live deployment state for every environment. You run `cascade generate-workflow` once; after that the generated workflows own their own execution. -``` -Merge to trunk - │ - ▼ -┌─────────────────────────────────────────────────────────────┐ -│ Orchestrate workflow (generated) │ -│ Setup → Validate → Build(s) → Deploy(s) → Finalize │ -│ │ -│ • Change detection: only run what changed │ -│ • Version computation: next semver RC from commits │ -│ • State written to manifest.yaml on every run │ -└─────────────────────────────────────────────────────────────┘ - │ - ▼ state[dev] updated, draft release created - │ - │ workflow_dispatch (promote) - ▼ -┌─────────────────────────────────────────────────────────────┐ -│ Promote workflow (generated) │ -│ Preflight → Deploy(s) → Publish callback → Finalize │ -│ │ -│ • Same artifacts, never rebuilt on promote │ -│ • Breaking-change gate at prerelease → release boundary │ -│ • Per-deploy change detection: skip unchanged │ -│ • Release published, RC tags cleaned up │ -└─────────────────────────────────────────────────────────────┘ -``` +```mermaid +%%{init: {'theme':'base','themeVariables':{'fontFamily':'ui-sans-serif, system-ui, sans-serif','primaryColor':'#0E8B82','primaryBorderColor':'#36D0C4','primaryTextColor':'#F4FBFA','lineColor':'#1F9B92','clusterBkg':'transparent','clusterBorder':'#36D0C4','tertiaryColor':'#B87333'}}}%% +flowchart TD + M[".github/manifest.yaml
config + live state"] --> G["cascade generate-workflow"] + G --> WF["Generated GitHub Actions
orchestrate.yaml + promote.yaml"] + + WF -- "merge to trunk" --> O + + subgraph O["Orchestrate (on merge)"] + direction LR + O1["Setup"] --> O2["Validate"] --> O3["Build"] --> O4["Deploy first env"] --> O5["Finalize"] + end + + O -- "workflow_dispatch · same artifacts, never rebuilt" --> P - - + subgraph P["Promote (cascade through environments)"] + direction LR + dev["dev"] --> test["test"] --> staging["staging"] --> prod["prod"] + end + + P --> R + + subgraph R["Release lifecycle"] + direction LR + draft["draft"] --> pre["prerelease"] --> pub["published
RC tags cleaned"] + end + + classDef accent fill:#B87333,stroke:#E8702A,color:#FFF7F0; + class M accent; +``` --- diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 1a163dc9..77eac4c7 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -15,7 +15,28 @@ export default defineConfig({ // mermaid auto-syncs when the reader toggles the theme. mermaid({ theme: 'dark', + // Mermaid follows the Starlight light/dark toggle. We keep autoTheme so + // node fills and text stay legible in both modes, and brand only the + // accent surfaces (edges, borders, cluster outlines, active accent) with + // cascade teal/copper - colors that read on both the dark slate and the + // light gray Starlight backgrounds. autoTheme: true, + mermaidConfig: { + themeVariables: { + fontFamily: 'ui-sans-serif, system-ui, sans-serif', + // Cascade cyan-teal: drives edges, focus accents, and active states. + primaryColor: '#0E8B82', + primaryBorderColor: '#36D0C4', + lineColor: '#36D0C4', + // Cluster (subgraph) outline in teal; transparent fill keeps the + // Starlight surface showing through in either mode. + clusterBorder: '#36D0C4', + clusterBkg: 'transparent', + // Copper/ember secondary accent for highlighted nodes. + tertiaryColor: '#B87333', + tertiaryBorderColor: '#E8702A', + }, + }, }), starlight({ title: 'Cascade', diff --git a/docs/src/content/docs/architecture.md b/docs/src/content/docs/architecture.md index 19def778..16e7c19a 100644 --- a/docs/src/content/docs/architecture.md +++ b/docs/src/content/docs/architecture.md @@ -15,39 +15,34 @@ System design and internals of cascade. ## System Overview -``` -┌─────────────────────────────────────────────────────────────────────┐ -│ cascade │ -├─────────────────────────────────────────────────────────────────────┤ -│ │ -│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ -│ │ CLI Tool │ │ Workflows │ │ Actions │ │ -│ │ (cascade) │ │ (reusable) │ │ (composite) │ │ -│ └───────────────┘ └───────────────┘ └───────────────┘ │ -│ │ │ │ │ -│ └────────────────────┼────────────────────┘ │ -│ │ │ -│ ┌───────────────────────────────────────────────────────────────┐ │ -│ │ Go Packages │ │ -│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ -│ │ │ config │ │ changes │ │changelog│ │generate │ │ release │ │ │ -│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ -│ │ ┌───────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ -│ │ │orchestrate│ │ promote │ │ version │ │ reset │ │ │ -│ │ └───────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ -│ │ ┌─────────┐ │ │ -│ │ │ git │ │ │ -│ │ └─────────┘ │ │ -│ └───────────────────────────────────────────────────────────────┘ │ -│ │ -└─────────────────────────────────────────────────────────────────────┘ - │ - ┌───────────┴───────────┐ - ▼ ▼ - ┌───────────────┐ ┌───────────────┐ - │Adopting Repos │ │ GitHub API │ - │ (callbacks) │ │ (releases) │ - └───────────────┘ └───────────────┘ +```mermaid +flowchart TD + subgraph cascade["cascade"] + direction TB + subgraph surfaces[" "] + direction LR + cli["CLI Tool
(cascade)"] + wf["Workflows
(reusable)"] + act["Actions
(composite)"] + end + subgraph pkgs["Go Packages"] + direction LR + config["config"] + changes["changes"] + changelog["changelog"] + generate["generate"] + release["release"] + orchestrate["orchestrate"] + promote["promote"] + version["version"] + reset["reset"] + git["git"] + end + surfaces --> pkgs + end + + cascade --> repos["Adopting Repos
(callbacks)"] + cascade --> api["GitHub API
(releases)"] ``` ## Directory Structure @@ -482,23 +477,13 @@ For deployments spanning multiple repositories (e.g., backend + CDK + K8s), the ### Primary/Satellite Model -``` - ┌───────────────────────────────────────────┐ - │ Primary Repo (Backend) │ - │ - Owns environment state machine │ - │ - Coordinates all promotions │ - │ - Tracks external deploy state │ - └───────────────────────────────────────────┘ - ▲ - ┌───────────────────┼───────────────────┐ - │ │ │ - ┌───────┴────────┐ ┌───────┴────────┐ ┌───────┴────────┐ - │ Satellite A │ │ Satellite B │ │ Satellite C │ - │ (CDK Infra) │ │ (K8s Manifests)│ │ (Terraform) │ - │ │ │ │ │ │ - │ Notifies after │ │ Notifies after │ │ Notifies after │ - │ dev deploy │ │ dev deploy │ │ dev deploy │ - └────────────────┘ └────────────────┘ └────────────────┘ +```mermaid +flowchart BT + satA["Satellite A
(CDK Infra)"] -- "notify after dev deploy" --> primary + satB["Satellite B
(K8s Manifests)"] -- "notify after dev deploy" --> primary + satC["Satellite C
(Terraform)"] -- "notify after dev deploy" --> primary + + primary["Primary Repo (Backend)
Owns environment state machine
Coordinates all promotions
Tracks external deploy state"] ``` ### Communication Flow diff --git a/docs/src/content/docs/workflows.md b/docs/src/content/docs/workflows.md index b3cf471a..f0909413 100644 --- a/docs/src/content/docs/workflows.md +++ b/docs/src/content/docs/workflows.md @@ -11,33 +11,17 @@ Triggered on every merge to trunk. Handles the full CI/CD pipeline for the first ### Flow -``` -Merge to Trunk - │ - ▼ -┌──────────┐ -│ Setup │ ← Parse config, detect changes, compute version -└──────────┘ - │ - ▼ -┌──────────┐ -│ Validate │ ← Optional pre-build validation -└──────────┘ - │ - ▼ -┌──────────┐ -│ Build │ ← Matrix: triggered builds only -└──────────┘ - │ - ▼ -┌──────────┐ -│ Deploy │ ← Matrix: triggered deploys with dependency ordering -└──────────┘ - │ - ▼ -┌──────────┐ -│ Finalize │ ← Update state, generate changelog, draft pre-release -└──────────┘ +```mermaid +flowchart TD + M["Merge to trunk"] --> S["Setup"] --> V["Validate"] --> B["Build"] --> D["Deploy"] --> F["Finalize"] + S -.-> sn["Parse config, detect changes,
compute version"] + V -.-> vn["Optional pre-build validation"] + B -.-> bn["Matrix: triggered builds only"] + D -.-> dn["Matrix: triggered deploys,
dependency-ordered"] + F -.-> fn["Update state, generate changelog,
draft pre-release"] + + classDef note fill:none,stroke:none,color:#8A929C; + class sn,vn,bn,dn,fn note; ``` ### Triggering @@ -109,28 +93,16 @@ Manual workflow to promote between environments. ### Flow -``` -Default mode (one step at a time) - │ - ▼ -┌──────────┐ -│ Preflight│ ← Validate source/target, check ancestry, gate breaking changes -└──────────┘ - │ - ▼ -┌──────────┐ -│ Deploy │ ← Matrix: per-deploy with change detection -└──────────┘ - │ - ▼ -┌──────────┐ -│ Publish │ ← (only at prerelease → release boundary, if publish: configured) -└──────────┘ - │ - ▼ -┌──────────┐ -│ Finalize │ ← Update state, publish release, dispatch Release workflow -└──────────┘ +```mermaid +flowchart TD + M["Default mode
(one step at a time)"] --> P["Preflight"] --> D["Deploy"] --> Pub["Publish"] --> F["Finalize"] + P -.-> pn["Validate source/target, check ancestry,
gate breaking changes"] + D -.-> dn["Matrix: per-deploy with change detection"] + Pub -.-> pubn["Only at prerelease to release boundary,
if publish: configured"] + F -.-> fn["Update state, publish release,
dispatch Release workflow"] + + classDef note fill:none,stroke:none,color:#8A929C; + class pn,dn,pubn,fn note; ``` A cascade mode (e.g., `dev-to-prod`) walks the chain step by step, running deploy/finalize for each intermediate environment, with the breaking-change gate enforced at the prerelease->release boundary.