architecture-diagram

Name: architecture-diagram
Author: konraddzbik

34stars4forks

How to install architecture-diagram?

konraddzbik/architecture-diagram-skill/architecture-diagram

$npx -y skills add konraddzbik/architecture-diagram-skill --skill architecture-diagram

Installs into the current project.

Summary

Build interactive, click-through architecture diagrams for software systems — a self-contained single HTML file with animated step-by-step flows, mode toggles (dev/prod, offline/online, v1/v2), dark/light theme, and a side panel with payload details, plus a companion markdown des

Files · 1

View on GitHub

SKILL.md

1	# Interactive Architecture Diagrams
2
3	Build single-file, drop-in HTML pages that let workshop attendees, clients, or new team members click through how a system works — step by step, with animated data packets flowing between nodes, payload details on a side panel, and toggleable modes (offline/online, dev/prod, v1/v2). The aesthetic is dark and didactic-first: bounded nodes, gentle quadratic wires, packets that glow only on the active step — no rainbow gradients. Rebrand via the CSS tokens in `assets/css-tokens.css`.
4
5	---
6
7	## When to reach for this skill
8
9	\| Situation \| Use this skill? \|
10	\|---\|---\|
11	\| "Show me how the auth flow works" (interactive, for a workshop) \| Yes \|
12	\| "Design the RAG pipeline before we build it" (planning new service) \| Yes \|
13	\| "Map our microservices and how they communicate" \| Yes \|
14	\| "Visualize the CI/CD pipeline for onboarding docs" \| Yes \|
15	\| "Show the data flow through our ETL pipeline" \| Yes \|
16	\| "Draw an agentic multi-agent system with tool calls" \| Yes \|
17	\| "Build me an architecture mockup we can iterate on with the team" \| Yes \|
18	\| "Draw a sequence diagram for the PR" (static, goes in markdown) \| No — a Mermaid sequence diagram inline is simpler \|
19	\| "Add a diagram to a slide deck or PDF" (static, not interactive) \| No — this produces interactive HTML, not images or slides \|
20	\| "I just need a static boxes-and-arrows topology" (no flows/steps) \| No — a Mermaid flowchart is enough \|
21
22	The differentiator is interactivity + sequenced data flow: if the value is "click through it and watch what happens", use this skill; if you need a static image, a slide, or an inline diagram, use Mermaid instead.
23
24	---
25
26	## The mental model
27
28	Every diagram has four things:
29
30	1. Nodes — services, datastores, users, queues, external systems. Each has a role (color) and metadata (tech stack, port, deployment target).
31	2. Flows — named scenarios the user can pick (e.g. `RAG Query`, `Direct Query`, `Ingest`, `Auth`). Each flow is an ordered list of steps.
32	3. Steps — `{from, to, color, title, route, payload, desc, chips}`. Each step lights up one wire and one target node. (`color` and `title` are required — a missing `color` leaves the wire uncolored, a missing `title` leaves the panel header blank.)
33	4. Modes — orthogonal toggle (offline/online, dev/prod, v1/v2). Modes can:
34	- hide/show entire nodes (e.g. Seed only exists offline)
35	- rename a node (Qdrant → BigQuery)
36	- swap payload bodies, ports, auth headers, latency chips
37
38	Modes are NOT alternative flows. Flows describe scenarios ("user asks a question"); modes describe deployment shape ("on Docker" vs "on Cloud Run").
39
40	---
41
42	## Workflow when invoked
43
44	### Step 1 — Capture intent
45
46	If the user has uploaded a SOLUTION.md, README, OpenAPI spec, or any architecture description, read it first before asking questions. Extract:
47
48	- Service names + tech stack + ports
49	- Deployment modes (if any)
50	- Named endpoints/operations and what they do (these become flows)
51	- For each operation, the chain of internal service calls (these become steps)
52
53	Then ask ONLY the gaps. Don't ask things already in the doc.
54
55	If there's no doc, ask the user briefly:
56	- "What system are we drawing?"
57	- "What are the main flows you want to show? (e.g. login, search, checkout)"
58	- "Any mode toggles? (offline/online, dev/prod, v1/v2)"
59	- "Who's the audience? Workshop attendees? Engineers? Clients?"
60
61	### Step 2 — Plan the topology on paper first
62
63	Before writing code, sketch on paper (literally in your head or a scratch file) WHICH services exist, WHERE they sit relative to each other, and WHICH flows connect WHICH nodes. Avoid wire crossings — this is the single biggest readability win. See `references/flow-design-patterns.md` for layout heuristics.
64
65	Quick rules:
66	- Orchestrator/API gateway in the middle, dependencies fanning out
67	- User on the far left (entry point), datastores on the right (exit), services in between
68	- **Read-only services abov

People who liked this also viewed

6 picks

Type

architecture-diagram

34stars4forks

View on GitHub

How to install architecture-diagram?

konraddzbik/architecture-diagram-skill/architecture-diagram

$npx -y skills add konraddzbik/architecture-diagram-skill --skill architecture-diagram

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Interactive Architecture Diagrams
2
3	Build single-file, drop-in HTML pages that let workshop attendees, clients, or new team members click through how a system works — step by step, with animated data packets flowing between nodes, payload details on a side panel, and toggleable modes (offline/online, dev/prod, v1/v2). The aesthetic is dark and didactic-first: bounded nodes, gentle quadratic wires, packets that glow only on the active step — no rainbow gradients. Rebrand via the CSS tokens in `assets/css-tokens.css`.
4
5	---
6
7	## When to reach for this skill
8
9	\| Situation \| Use this skill? \|
10	\|---\|---\|
11	\| "Show me how the auth flow works" (interactive, for a workshop) \| Yes \|
12	\| "Design the RAG pipeline before we build it" (planning new service) \| Yes \|
13	\| "Map our microservices and how they communicate" \| Yes \|
14	\| "Visualize the CI/CD pipeline for onboarding docs" \| Yes \|
15	\| "Show the data flow through our ETL pipeline" \| Yes \|
16	\| "Draw an agentic multi-agent system with tool calls" \| Yes \|
17	\| "Build me an architecture mockup we can iterate on with the team" \| Yes \|
18	\| "Draw a sequence diagram for the PR" (static, goes in markdown) \| No — a Mermaid sequence diagram inline is simpler \|
19	\| "Add a diagram to a slide deck or PDF" (static, not interactive) \| No — this produces interactive HTML, not images or slides \|
20	\| "I just need a static boxes-and-arrows topology" (no flows/steps) \| No — a Mermaid flowchart is enough \|
21
22	The differentiator is interactivity + sequenced data flow: if the value is "click through it and watch what happens", use this skill; if you need a static image, a slide, or an inline diagram, use Mermaid instead.
23
24	---
25
26	## The mental model
27
28	Every diagram has four things:
29
30	1. Nodes — services, datastores, users, queues, external systems. Each has a role (color) and metadata (tech stack, port, deployment target).
31	2. Flows — named scenarios the user can pick (e.g. `RAG Query`, `Direct Query`, `Ingest`, `Auth`). Each flow is an ordered list of steps.
32	3. Steps — `{from, to, color, title, route, payload, desc, chips}`. Each step lights up one wire and one target node. (`color` and `title` are required — a missing `color` leaves the wire uncolored, a missing `title` leaves the panel header blank.)
33	4. Modes — orthogonal toggle (offline/online, dev/prod, v1/v2). Modes can:
34	- hide/show entire nodes (e.g. Seed only exists offline)
35	- rename a node (Qdrant → BigQuery)
36	- swap payload bodies, ports, auth headers, latency chips
37
38	Modes are NOT alternative flows. Flows describe scenarios ("user asks a question"); modes describe deployment shape ("on Docker" vs "on Cloud Run").
39
40	---
41
42	## Workflow when invoked
43
44	### Step 1 — Capture intent
45
46	If the user has uploaded a SOLUTION.md, README, OpenAPI spec, or any architecture description, read it first before asking questions. Extract:
47
48	- Service names + tech stack + ports
49	- Deployment modes (if any)
50	- Named endpoints/operations and what they do (these become flows)
51	- For each operation, the chain of internal service calls (these become steps)
52
53	Then ask ONLY the gaps. Don't ask things already in the doc.
54
55	If there's no doc, ask the user briefly:
56	- "What system are we drawing?"
57	- "What are the main flows you want to show? (e.g. login, search, checkout)"
58	- "Any mode toggles? (offline/online, dev/prod, v1/v2)"
59	- "Who's the audience? Workshop attendees? Engineers? Clients?"
60
61	### Step 2 — Plan the topology on paper first
62
63	Before writing code, sketch on paper (literally in your head or a scratch file) WHICH services exist, WHERE they sit relative to each other, and WHICH flows connect WHICH nodes. Avoid wire crossings — this is the single biggest readability win. See `references/flow-design-patterns.md` for layout heuristics.
64
65	Quick rules:
66	- Orchestrator/API gateway in the middle, dependencies fanning out
67	- User on the far left (entry point), datastores on the right (exit), services in between
68	- **Read-only services abov

People who liked this also viewed

6 picks

Type