Build an Architecture Map
Create an interactive architecture map for $ARGUMENTS.
The map must be self-contained HTML with inline CSS, Google Fonts only, Mermaid.js loaded from CDN (https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs), no build step. Target 800-1200 lines. Focus on clarity and navigability over exhaustive detail.
Subjects
Architecture maps can cover three types of subjects:
- Organizations (VA OIT, DoD, IRS, a bank) — org structure, major systems, integrations, data flows, modernization status
- Open source projects (Kubernetes, PostgreSQL, Linux kernel) — component architecture, module breakdown, data/control flow, extension points
- Tech platforms/stacks (Supabase, Vercel, AWS) — service architecture, API layers, infrastructure, how services compose
Phase 0 — Plan (interactive)
- Parse the argument: the main subject, and an optional style name.
- If no style was specified:
- Read the Style Guide Catalog table in
README.md to see which styles are available
- Suggest 3-4 unused styles that thematically fit the subject (e.g.,
blueprint for infrastructure, federal-night for government, circuit-board for tech)
- Ask the user to pick one
- Read the chosen style's HTML file from
styles/{name}.html to extract the design system (CSS variables, fonts, color palette).
- Read
architecture/va-oit/index.html as the reference template for structure, Mermaid config, and fullscreen viewer code.
- Propose an outline of 8-12 sections with a brief description of each, plus which diagram types suit each section:
graph TD — hierarchies, org charts, component treesgraph LR — data flows, request paths, pipelinesflowchart — decision flows, request routingtimeline — evolution, version history, modernizationblock-beta — layered architectures, stack diagramssequenceDiagram — API call flows, auth sequences
- Discuss with the user before proceeding.
Phase 1 — Research (2 parallel Sonnet subagents)
Launch 2 sonnet subagents in parallel. Each should use WebSearch extensively and WebFetch for documentation pages, GitHub READMEs, and architecture docs.
Agent 1 — Structure & Systems:
- Organizational/project structure (teams, divisions, maintainers, SIGs)
- Complete inventory of major systems, services, or components
- Technology stack details (languages, frameworks, databases, cloud)
- Budget/scale figures if applicable (public data only for orgs)
- Return a structured list with: name, acronym, category/domain, purpose, tech stack
Agent 2 — Connections & Status:
- System interconnections: what talks to what, data flows, API boundaries
- Integration patterns (REST, gRPC, message queues, shared DBs, event buses)
- Authentication/identity flows
- Modernization status, migration efforts, known pain points
- Public APIs, developer portals, open source repos
- Return a structured list of connections: source → target, protocol/method, data exchanged
Both agents should cite their sources for the appendix.
Phase 2 — Build (2 sequential Opus subagents)
Use 2 sequential opus subagents:
Agent 1 — Skeleton + Sections 01-07
Create the full HTML file with:
Infrastructure (copy from reference):
- Complete
<head> with Google Fonts from the chosen style
- All CSS adapted from the style guide's palette for: hero, jump nav, sections, diagram containers, info cards, data tables, callouts, stat rows, status indicators, domain badges, acronym grid, footer
- Fullscreen diagram viewer (overlay HTML + CSS + JS) — copy the pattern from
architecture/va-oit/index.html
- Mermaid initialization with
themeVariables mapped to the style's palette:
background, primaryColor, primaryTextColor, primaryBorderColor etc. all from style CSS varsfontFamily matching the style's body fontuseMaxWidth: false in flowchart config
- The
mermaid.run().then(...) expand-button injection code
Content — sections 01-07:
- Hero with title, tagline, meta badges (key stats)
- Sticky jump nav with ALL section anchors
- Overview section with stat row
- 6 more sections, each with:
- Section number + title + description
- 1-2 Mermaid diagrams with
diagram-label
- Supporting content (cards, tables, callouts as appropriate)
- Mermaid node styles using colors from the style's palette
Mermaid diagram rules:
- Every
<pre class="mermaid"> must be inside a <div class="diagram-container"> with a <div class="diagram-label">
- Use inline
style declarations on nodes for colors: style NODE fill:#hex,stroke:#hex,color:#hex
- Keep diagrams focused: 8-15 nodes max per diagram. Split complex systems across multiple diagrams.
- Use subgraphs to group related components
- Use
<br/> for multi-line node labels
Mermaid node text contrast (REQUIRED):
Mermaid's primaryTextColor theme variable overrides per-node color in style directives — the color doesn't propagate through foreignObject to HTML labels. You MUST include a post-render fixNodeLabelColors function that:
- Runs inside
mermaid.run().then() wrapped in requestAnimationFrame
- Iterates all
.node elements, reads the shape's fill via getComputedStyle(shape).fill
- Computes luminance:
(0.299*r + 0.587*g + 0.114*b) / 255
- Sets text color on
foreignObject * with !important: dark (#0a0010) if lum > 0.4, white (#ffffff) otherwise
- Also sets
fill attribute on text/tspan elements for SVG text fallback
- Is also called on cloned SVGs in the fullscreen viewer (
fixNodeLabelColors(clone))
Copy the implementation from architecture/openclaw/index.html.
Agent 2 — Sections 08-12 + Finish
Read the file, then append:
- Remaining sections (interconnections overview, modernization/status, acronym reference)
- The interconnection map: one large diagram showing the full system-to-system picture
- Modernization tracker table with status indicators
- Acronym grid
- Footer with source attribution
- Close all HTML tags
Critical rules for both build agents:
- Each agent MUST read the current file before writing
- Use Edit to append content — find closing
</body> or last </section> and insert before it
- Never rewrite the entire file
- All section
id attributes must match jump nav anchors
- Back link:
<a href="../index.html" class="back-link">Architecture Maps</a>
- File goes in
architecture/{kebab-case-name}/index.html
Phase 3 — Polish (1 Opus subagent)
One opus subagent reads the complete file and:
- Diagram audit: Verify every
<pre class="mermaid"> is valid syntax. Check node IDs don't collide across diagrams. Ensure all style declarations reference defined nodes.
- Navigation audit: Verify all jump nav
href anchors match section id attributes.
- Visual consistency: Check that node colors across diagrams use a consistent palette (same domain = same color family). Verify diagram labels are present.
- Content check: Look for placeholder text, incomplete sentences, or TODO markers. Verify acronym grid includes all acronyms used in the document.
- Responsive check: Ensure diagram containers have
overflow-x: auto. Verify mobile breakpoint styles exist.
- Fix any issues found.
Phase 4 — Index & Ship
- If
architecture/index.html exists, read it and add a card for the new map. If it doesn't exist, create a hub page following the project's index pattern (card grid linking to each map).
- Update the master
/index.html if there's no Architecture section link yet.
- Commit with message:
Add {subject} architecture map ({style-name} style)
- Push using:
git config --global credential.helper store && echo "https://GGPrompts:$(gh auth token --user GGPrompts)@github.com" > ~/.git-credentials && git push origin main
Reference
- Template:
architecture/va-oit/index.html (Federal Night style, ~1200 lines)
- Mermaid contrast fix reference:
architecture/openclaw/index.html (has fixNodeLabelColors implementation)
- Style guides:
styles/{name}.html
- Available styles: Style Guide Catalog table in
README.md
- Mermaid docs: https://mermaid.js.org/syntax/flowchart.html
1---2name: architecture-133description: Build an interactive architecture map for an organization, open source project, or tech platform4---5
6# Build an Architecture Map
7
8Create an interactive architecture map for **$ARGUMENTS**.
9
10The map must be self-contained HTML with inline CSS, Google Fonts only, Mermaid.js loaded from CDN (`https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs`), no build step. Target 800-1200 lines. Focus on clarity and navigability over exhaustive detail.
11
12## Subjects
13
14Architecture maps can cover three types of subjects:
15
161. **Organizations** (VA OIT, DoD, IRS, a bank) — org structure, major systems, integrations, data flows, modernization status
172. **Open source projects** (Kubernetes, PostgreSQL, Linux kernel) — component architecture, module breakdown, data/control flow, extension points
183. **Tech platforms/stacks** (Supabase, Vercel, AWS) — service architecture, API layers, infrastructure, how services compose
19
20## Phase 0 — Plan (interactive)
21
221. Parse the argument: the main subject, and an optional style name.
232. If no style was specified:
24 - Read the **Style Guide Catalog** table in `README.md` to see which styles are available
25 - Suggest 3-4 unused styles that thematically fit the subject (e.g., `blueprint` for infrastructure, `federal-night` for government, `circuit-board` for tech)
26 - Ask the user to pick one
273. Read the chosen style's HTML file from `styles/{name}.html` to extract the design system (CSS variables, fonts, color palette).
284. Read `architecture/va-oit/index.html` as the reference template for structure, Mermaid config, and fullscreen viewer code.
295. Propose an outline of 8-12 sections with a brief description of each, plus which diagram types suit each section:
30 - `graph TD` — hierarchies, org charts, component trees
31 - `graph LR` — data flows, request paths, pipelines
32 - `flowchart` — decision flows, request routing
33 - `timeline` — evolution, version history, modernization
34 - `block-beta` — layered architectures, stack diagrams
35 - `sequenceDiagram` — API call flows, auth sequences
366. Discuss with the user before proceeding.
37
38## Phase 1 — Research (2 parallel Sonnet subagents)
39
40Launch 2 **sonnet** subagents in parallel. Each should use WebSearch extensively and WebFetch for documentation pages, GitHub READMEs, and architecture docs.
41
42**Agent 1 — Structure & Systems:**
43- Organizational/project structure (teams, divisions, maintainers, SIGs)
44- Complete inventory of major systems, services, or components
45- Technology stack details (languages, frameworks, databases, cloud)
46- Budget/scale figures if applicable (public data only for orgs)
47- Return a structured list with: name, acronym, category/domain, purpose, tech stack
48
49**Agent 2 — Connections & Status:**
50- System interconnections: what talks to what, data flows, API boundaries
51- Integration patterns (REST, gRPC, message queues, shared DBs, event buses)
52- Authentication/identity flows
53- Modernization status, migration efforts, known pain points
54- Public APIs, developer portals, open source repos
55- Return a structured list of connections: source → target, protocol/method, data exchanged
56
57Both agents should cite their sources for the appendix.
58
59## Phase 2 — Build (2 sequential Opus subagents)
60
61Use 2 sequential **opus** subagents:
62
63### Agent 1 — Skeleton + Sections 01-07
64
65Create the full HTML file with:
66
67**Infrastructure (copy from reference):**
68- Complete `<head>` with Google Fonts from the chosen style
69- All CSS adapted from the style guide's palette for: hero, jump nav, sections, diagram containers, info cards, data tables, callouts, stat rows, status indicators, domain badges, acronym grid, footer
70- Fullscreen diagram viewer (overlay HTML + CSS + JS) — copy the pattern from `architecture/va-oit/index.html`
71- Mermaid initialization with `themeVariables` mapped to the style's palette:
72 - `background`, `primaryColor`, `primaryTextColor`, `primaryBorderColor` etc. all from style CSS vars
73 - `fontFamily` matching the style's body font
74 - `useMaxWidth: false` in flowchart config
75- The `mermaid.run().then(...)` expand-button injection code
76
77**Content — sections 01-07:**
78- Hero with title, tagline, meta badges (key stats)
79- Sticky jump nav with ALL section anchors
80- Overview section with stat row
81- 6 more sections, each with:
82 - Section number + title + description
83 - 1-2 Mermaid diagrams with `diagram-label`
84 - Supporting content (cards, tables, callouts as appropriate)
85 - Mermaid node styles using colors from the style's palette
86
87**Mermaid diagram rules:**
88- Every `<pre class="mermaid">` must be inside a `<div class="diagram-container">` with a `<div class="diagram-label">`
89- Use inline `style` declarations on nodes for colors: `style NODE fill:#hex,stroke:#hex,color:#hex`
90- Keep diagrams focused: 8-15 nodes max per diagram. Split complex systems across multiple diagrams.
91- Use subgraphs to group related components
92- Use `<br/>` for multi-line node labels
93
94**Mermaid node text contrast (REQUIRED):**
95Mermaid's `primaryTextColor` theme variable overrides per-node `color` in style directives — the `color` doesn't propagate through `foreignObject` to HTML labels. You MUST include a post-render `fixNodeLabelColors` function that:
961. Runs inside `mermaid.run().then()` wrapped in `requestAnimationFrame`
972. Iterates all `.node` elements, reads the shape's fill via `getComputedStyle(shape).fill`
983. Computes luminance: `(0.299*r + 0.587*g + 0.114*b) / 255`
994. Sets text color on `foreignObject *` with `!important`: dark (`#0a0010`) if lum > 0.4, white (`#ffffff`) otherwise
1005. Also sets `fill` attribute on `text`/`tspan` elements for SVG text fallback
1016. Is also called on cloned SVGs in the fullscreen viewer (`fixNodeLabelColors(clone)`)
102
103Copy the implementation from `architecture/openclaw/index.html`.
104
105### Agent 2 — Sections 08-12 + Finish
106
107Read the file, then append:
108- Remaining sections (interconnections overview, modernization/status, acronym reference)
109- The interconnection map: one large diagram showing the full system-to-system picture
110- Modernization tracker table with status indicators
111- Acronym grid
112- Footer with source attribution
113- Close all HTML tags
114
115**Critical rules for both build agents:**
116- Each agent MUST read the current file before writing
117- Use Edit to append content — find closing `</body>` or last `</section>` and insert before it
118- Never rewrite the entire file
119- All section `id` attributes must match jump nav anchors
120- Back link: `<a href="../index.html" class="back-link">Architecture Maps</a>`
121- File goes in `architecture/{kebab-case-name}/index.html`
122
123## Phase 3 — Polish (1 Opus subagent)
124
125One **opus** subagent reads the complete file and:
126
1271. **Diagram audit**: Verify every `<pre class="mermaid">` is valid syntax. Check node IDs don't collide across diagrams. Ensure all `style` declarations reference defined nodes.
1282. **Navigation audit**: Verify all jump nav `href` anchors match section `id` attributes.
1293. **Visual consistency**: Check that node colors across diagrams use a consistent palette (same domain = same color family). Verify diagram labels are present.
1304. **Content check**: Look for placeholder text, incomplete sentences, or TODO markers. Verify acronym grid includes all acronyms used in the document.
1315. **Responsive check**: Ensure diagram containers have `overflow-x: auto`. Verify mobile breakpoint styles exist.
1326. Fix any issues found.
133
134## Phase 4 — Index & Ship
135
1361. If `architecture/index.html` exists, read it and add a card for the new map. If it doesn't exist, create a hub page following the project's index pattern (card grid linking to each map).
1372. Update the master `/index.html` if there's no Architecture section link yet.
1383. Commit with message: `Add {subject} architecture map ({style-name} style)`
1394. Push using: `git config --global credential.helper store && echo "https://GGPrompts:$(gh auth token --user GGPrompts)@github.com" > ~/.git-credentials && git push origin main`
140
141## Reference
142
143- Template: `architecture/va-oit/index.html` (Federal Night style, ~1200 lines)
144- Mermaid contrast fix reference: `architecture/openclaw/index.html` (has `fixNodeLabelColors` implementation)
145- Style guides: `styles/{name}.html`
146- Available styles: **Style Guide Catalog** table in `README.md`
147- Mermaid docs: https://mermaid.js.org/syntax/flowchart.html
majiayu000