architecture-diagram
Skill0 starsChanged 18 days agoApache-2.0View on GitHub
Use at the start of any design, feature, or refactoring work in a repo to read the living architecture diagram, and whenever services, modules, data stores, or integrations change, to update it.
48 other projects use a version of this.
Adopted by
Most recently taken up by
- bharathgnana/archdiagramtheir own version, first seen Nov 16, 2026
- rodos4312/Meu-Agenttheir own version, first seen Nov 15, 2026
- ottuck/diagram-polishtheir own version, first seen Nov 15, 2026
- incredible404-rgb/zstacktheir own version, first seen Nov 15, 2026
- betoxf/universal-computer-usetheir own version, first seen Nov 15, 2026
- NousResearch/hermes-agenttheir own version, first seen Nov 13, 2026
Used with
Projects with it also use teams-meeting-pipeline, touchdesigner-mcp and 5 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
john-data-chenSkillteams-meeting-pipeline
Operate the Teams meeting summary pipeline via Hermes CLI — summarize meetings, inspect pipeline status, replay jobs, manage Microsoft Graph subscriptions.
Also in 8 projects that use this
john-data-chenSkilltouchdesigner-mcp
Control a running TouchDesigner instance via twozero MCP — create operators, set parameters, wire connections, execute Python, build real-time visuals. 36 native tools.
Also in 5 projects that use this
Tommy-ywSkillsongwriting-and-ai-music
Songwriting craft, AI music generation prompts (Suno focus), parody/adaptation techniques, phonetic tricks, and lessons learned. These are tools and ideas, not rules. Break any of them when the art calls for it.
Also in 9 projects that use this
mae616Skillp5js
p5.js(クリエイティブコーディング)のProcessing由来「コードでスケッチ」思想を軸に、setup/drawループ・座標系・インタラクション・パフォーマンス最適化を整理する。p5.js、Processing、クリエイティブコーディング、ジェネラティブアート、インタラクティブ表現、ビジュアルプログラミング、Canvas描画、パーティクル、フラクタル、ノイズ表現に関する相談で必ず使うこと。ユーザーが「コードでアート」「動くビジュアル」「インタラクティブな描画」と言った場合にも適用する。
Also in 9 projects that use this
Tommy-ywSkillpopular-web-designs
54 production-quality design systems extracted from real websites. Load a template to generate HTML/CSS that matches the visual identity of sites like Stripe, Linear, Vercel, Notion, Airbnb, and more. Each template includes colors, typography, components, layout rules, and ready-to-use CSS values.
Also in 9 projects that use this
math-incSkillfindmy
Track Apple devices and AirTags via FindMy.app on macOS using AppleScript and screen capture.
Also in 9 projects that use this
- +1 more from Tommy-yw
Other versions48 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 48
- NousResearch/hermes-agent★ 264ksame name
- lahfir/agent-desktop★ 24ksame name
- vercel-labs/agent-desktop★ 24ksame name
- Cocoon-AI/architecture-diagram-generator★ 7.4ksame name
- Tommy-yw/RunbookHermes★ 546same name
- Mathews-Tom/armory★ 340same name
- konraddzbik/architecture-diagram-skill★ 143same name
- proyecto26/system-design-skills★ 118same name
- microsoft/github-copilot-modernization★ 48same name
- wundercorp/loki★ 28same name
38 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository5 other files it gives its agents.
- clean-codeSkill
- refactor-proposalSkill
- software-architectureSkill
- software-designSkill
- tddSkill
The file
We split this skill into the rules it gives an agent
10 rules. 0 are common, 8 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 45 edited versions we read keep these.
8
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 11
Before any design, feature, or refactoring work, read docs/architecture.md.
- Distinctive: line 12
Use it to locate where the change belongs and which boundaries and contracts it touches.
- Distinctive: line 13
If the file and the code disagree, trust the code.
- Distinctive: line 14
If the file doesn't exist, offer to create it by surveying the codebase, using the build files, package structure, configs, and …
- Distinctive: line 17
Update the file in the same change set whenever any of these change:
- Distinctive: line 45
Commit the HTML with the markdown.
- Distinctive: line 69
Use Mermaid only, so the diagrams diff cleanly in version control and render on GitHub and GitLab.
- Very specific: line 70
No second colon in a stateDiagram-v2 transition label (A --> B : at day 30: purge breaks the parser).
- Distinctive: line 72
Keep each diagram readable, at roughly 15 nodes or fewer.
- Distinctive: line 73
Use the same names as the code (service names, module names, topic names).
“Common” is measured: kept by at least 6 in 10 of the 45 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Living Architecture Diagram
Maintain one source-of-truth file, docs/architecture.md, that describes the system's structure. Read it for context and keep it current. It works with the software-architecture skill.
Reading (start of a task)
- Before any design, feature, or refactoring work, read
docs/architecture.md. - Use it to locate where the change belongs and which boundaries and contracts it touches.
- If the file and the code disagree, trust the code. Flag the drift and fix the file as part of the task.
- If the file doesn't exist, offer to create it by surveying the codebase, using the build files, package structure, configs, and docker-compose or k8s manifests.
Updating (end of a task)
Update the file in the same change set whenever any of these change:
- services or modules are added, removed, or renamed
- a dependency between them is added, removed, or renamed
- data stores or data ownership change
- sync or async integrations change: REST, gRPC, topics, or queues
- external systems or the auth flow change
Internal refactors that leave boundaries intact don't need an update. When you update the file, bump Last updated and add a one-line entry to the changelog.
The zoomable HTML viewer
GitHub renders Mermaid small and does not zoom, so every repo also keeps one HTML page that shows
all of its architecture diagrams with pan and zoom: docs/architecture/diagrams/viewer.html.
A generator builds it from the markdown; the markdown stays the source of truth.
- First time in a repo: copy
scripts/build-viewer.pyfrom this skill's folder todocs/architecture/diagrams/build-viewer.py, so the repo can rebuild the page without the skill. After every diagram change, in the same change set as the markdown, run from the repo root:
python3 docs/architecture/diagrams/build-viewer.pyIt scans
docs/architecture.mdand every markdown file underdocs/architecture/, skipping the blueprint'sdecomposition-*proposals (history, not the living design). Pass paths to scan something else,--outfor another output file,--exclude TEXTto skip more files.- Check the count it prints against the number of
```mermaidblocks you expect, then open the page in a browser and click through the diagrams you touched. A diagram that Mermaid cannot parse shows its error and the source in the page; fix the markdown, not the HTML. - Commit the HTML with the markdown. Tell the user the page exists when you first create it.
The page loads Mermaid from jsDelivr, so it needs the network the first time it opens. Each diagram has a sidebar entry, keyboard navigation, a source pane and an SVG download.
File structure
The file has these sections, in order:
- Overview: two or three sentences on what the system does.
- Context diagram (C4 level 1): Mermaid
flowchartshowing users, the system, and external systems. - Container diagram (C4 level 2): Mermaid
flowchartshowing services and apps, their databases, and the message broker. Label every edge with its protocol and purpose, for exampleREST: create orderorevent: OrderPlaced. - Components: for any complex service, a level-3 diagram of its modules, ports, and adapters.
- Service catalog: a table with these columns:
- service
- responsibility (one line)
- owns data
- exposes APIs
- publishes events
- consumes events
- Key flows: Mermaid
sequenceDiagrams for two to five critical flows. - Decisions: links to ADRs.
- Last updated: a date, plus a short changelog.
Rules
- Use Mermaid only, so the diagrams diff cleanly in version control and render on GitHub and GitLab.
- No second colon in a
stateDiagram-v2transition label (A --> B : at day 30: purgebreaks the parser). Use a dash or a comma inside the label. - One fact lives in one place. Keep the diagram and the service catalog consistent with each other.
- Keep each diagram readable, at roughly 15 nodes or fewer. Split by level of detail rather than cramming.
- Use the same names as the code (service names, module names, topic names).
- Describe the system as it is. Put planned changes in a clearly marked Proposed section, never mixed into the current state.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

