agentleFS
nohemi20231nohemi20231/design-skills/skills/architecture-diagram/SKILL.md

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

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-chenSkill

    teams-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-chenSkill

    touchdesigner-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-ywSkill

    songwriting-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

  • mae616Skill

    p5js

    p5.js(クリエイティブコーディング)のProcessing由来「コードでスケッチ」思想を軸に、setup/drawループ・座標系・インタラクション・パフォーマンス最適化を整理する。p5.js、Processing、クリエイティブコーディング、ジェネラティブアート、インタラクティブ表現、ビジュアルプログラミング、Canvas描画、パーティクル、フラクタル、ノイズ表現に関する相談で必ず使うこと。ユーザーが「コードでアート」「動くビジュアル」「インタラクティブな描画」と言った場合にも適用する。

    Also in 9 projects that use this

  • Tommy-ywSkill

    popular-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-incSkill

    findmy

    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

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
  1. Very specific:

    Before any design, feature, or refactoring work, read docs/architecture.md.

    line 11
  2. Distinctive:

    Use it to locate where the change belongs and which boundaries and contracts it touches.

    line 12
  3. Distinctive:

    If the file and the code disagree, trust the code.

    line 13
  4. Distinctive:

    If the file doesn't exist, offer to create it by surveying the codebase, using the build files, package structure, configs, and …

    line 14
  5. Distinctive:

    Update the file in the same change set whenever any of these change:

    line 17
  6. Distinctive:

    Commit the HTML with the markdown.

    line 45
  7. Distinctive:

    Use Mermaid only, so the diagrams diff cleanly in version control and render on GitHub and GitLab.

    line 69
  8. Very specific:

    No second colon in a stateDiagram-v2 transition label (A --> B : at day 30: purge breaks the parser).

    line 70
  9. Distinctive:

    Keep each diagram readable, at roughly 15 nodes or fewer.

    line 72
  10. Distinctive:

    Use the same names as the code (service names, module names, topic names).

    line 73

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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)

  1. Before any design, feature, or refactoring work, read docs/architecture.md.
  2. Use it to locate where the change belongs and which boundaries and contracts it touches.
  3. If the file and the code disagree, trust the code. Flag the drift and fix the file as part of the task.
  4. 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.

  1. First time in a repo: copy scripts/build-viewer.py from this skill's folder to docs/architecture/diagrams/build-viewer.py, so the repo can rebuild the page without the skill.
  2. After every diagram change, in the same change set as the markdown, run from the repo root:

    python3 docs/architecture/diagrams/build-viewer.py

    It scans docs/architecture.md and every markdown file under docs/architecture/, skipping the blueprint's decomposition-* proposals (history, not the living design). Pass paths to scan something else, --out for another output file, --exclude TEXT to skip more files.

  3. Check the count it prints against the number of ```mermaid blocks 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.
  4. 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:

  1. Overview: two or three sentences on what the system does.
  2. Context diagram (C4 level 1): Mermaid flowchart showing users, the system, and external systems.
  3. Container diagram (C4 level 2): Mermaid flowchart showing services and apps, their databases, and the message broker. Label every edge with its protocol and purpose, for example REST: create order or event: OrderPlaced.
  4. Components: for any complex service, a level-3 diagram of its modules, ports, and adapters.
  5. Service catalog: a table with these columns:
    • service
    • responsibility (one line)
    • owns data
    • exposes APIs
    • publishes events
    • consumes events
  6. Key flows: Mermaid sequenceDiagrams for two to five critical flows.
  7. Decisions: links to ADRs.
  8. 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-v2 transition label (A --> B : at day 30: purge breaks 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.