[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-92392":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":15,"stars7d":15,"stars30d":15,"stars90d":15,"forks30d":15,"starsTrendScore":15,"compositeScore":16,"rankGlobal":9,"rankLanguage":9,"license":17,"archived":18,"fork":18,"defaultBranch":19,"hasWiki":20,"hasPages":18,"topics":21,"createdAt":9,"pushedAt":9,"updatedAt":38,"readmeContent":39,"aiSummary":40,"trendingCount":15,"starSnapshotCount":15,"syncStatus":13,"lastSyncTime":41,"discoverSource":42},92392,"iso-topology","MarkovWangRR\u002Fiso-topology","MarkovWangRR","Isometric architecture diagrams as code — text DSL in, design-grade 2.5D SVG out. Agent-first: LLMs can discover, generate, and validate the DSL.",null,"Go",51,1,2,9,0,40.9,"Apache License 2.0",false,"main",true,[22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37],"agent","ai-agents","architecture-diagram","d2","diagram","diagram-as-code","diagramming","dsl","go","golang","iso","isometric","llm-tools","svg","topology","yaml","2026-07-22 04:02:06","\u003Cdiv align=\"center\">\n\n\u003Cimg src=\"docs\u002Fassets\u002Flogo.jpg\" alt=\"iso-topology logo — text DSL flowing into an isometric block diagram\" width=\"440\">\n\n# iso-topology — isometric architecture diagrams as code\n\n[![License: Apache 2.0](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-Apache_2.0-blue.svg)](LICENSE)\n[![Go 1.25](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FGo-1.25-00ADD8?logo=go&logoColor=white)](https:\u002F\u002Fgo.dev)\n[![Go Reference](https:\u002F\u002Fpkg.go.dev\u002Fbadge\u002Fgithub.com\u002FMarkovWangRR\u002Fiso-topology.svg)](https:\u002F\u002Fpkg.go.dev\u002Fgithub.com\u002FMarkovWangRR\u002Fiso-topology)\n\n### Figma-grade isometric architecture diagrams — as code, agent-native.\n\n**Ask your agent in plain language. Refine the same way. Commit the result.**\n\n![ClickHouse real-time analytics — dark frosted-glass isometric architecture rendered by iso-topology](docs\u002Fassets\u002Fclickhouse-hub.png)\n\n\u003Csub>↑ Built by asking — *“draw a ClickHouse real-time analytics architecture, dark glass style”* — then a few plain-language tweaks (*“thicker dashed gradient connectors,” “add a diagonal grid,” “lime accent”*). No Figma, no coordinates; it's text you diff.\u003C\u002Fsub>\n\n`single binary` · `zero runtime deps` · `renders in ms` · `200+ icons incl. real brand logos` · `every sample golden-tested`\n\nEnglish · [简体中文](README.zh-CN.md)\n\n\u003C\u002Fdiv>\n\n---\n\nThe only diagram-as-code tool where the output is design-grade **isometric**, the DSL is\na machine-checkable contract your agent self-corrects against, and it runs deterministically\n**offline in one static binary**. The alternative is an afternoon in Figma (not diffable,\ndead the moment the infra changes) or Mermaid\u002FD2 (flat flowcharts). This gives you the\nFigma look from text — generated by your agent, validated before render, committed next to\nyour code.\n\n## Prefer to write it yourself? It's just text.\n\nPresets define the look once; `layout` \u002F `place` relations do the positioning — never\npixel coordinates. From this:\n\n```yaml\ntheme:\n  presets:\n    heroBlue:                                  # the one glowing accent, reused by name\n      stroke: { color: \"#6FA8E0\", width: 1.6 }\n      faces: { top: { fill: { kind: linearGradient, stops: [ {offset: 0, color: \"#1A3550\"}, {offset: 1, color: \"#0E1C30\"} ] } } }\n      effects: { faceSplit: true, backglow: { color: \"#6BA8E8\", radius: 70 } }\nnodes:\n  scene:\n    parts:\n      - id: runtime\n        shape: group\n        layout: { mode: column }               # ← auto-arranged, no coordinates\n        parts:\n          - { id: agent,  preset: heroBlue, icon: \"iso:\u002F\u002Fsi\u002Flangchain\u002F8FBEEF\", label: \"LangGraph Agent\" }\n          - { id: memory, icon: \"iso:\u002F\u002Fglyph\u002Fdatabase\", label: \"Memory · State\" }\n    connectors:\n      - { from: client, to: runtime, routing: orthogonal,\n          stroke: { gradient: { from: \"#3B6FD4\", to: \"#8FBEEF\" } } }   # glowing flow\n```\n\n…renders to this — a typical LangChain agent app, in LangChain's own dark\u002Fcool-blue style:\n\n![LangChain agent application architecture — deep navy stage, glowing cool-blue LangGraph runtime wired to client, models, retrieval, tools, with LangSmith observability](docs\u002Fassets\u002Flangchain-app.png)\n\nA deterministic solver turns relations into geometry — every scene here is coordinate-free.\n[Source](samples\u002Ftopology\u002Flangchain-app\u002Finput.yaml).\n\n## Start in 60 seconds\n\n**By hand** — one static binary, no browser or fonts needed:\n\n```bash\ngo install github.com\u002FMarkovWangRR\u002Fiso-topology\u002Fcmd\u002Fisotopo@latest\necho 'user -> api -> db' > scene.d2     # any d2 graph → auto-layout\nisotopo render scene.d2 .\u002Fout           # → out\u002Ftopology.svg (+ html + per-node SVGs)\nisotopo serve  scene.d2                 # → localhost:8731 — drag, restyle, export\n```\n\n**With your agent** (Claude Code, Cursor, …) — wire it up once (commands below are tested):\n\n```bash\ngo install github.com\u002FMarkovWangRR\u002Fiso-topology\u002Fcmd\u002Fisotopo@latest      # the renderer\ngo install github.com\u002FMarkovWangRR\u002Fiso-topology\u002Fcmd\u002Fisotopo-mcp@latest  # MCP server\nclaude mcp add isotopo -- isotopo-mcp                                   # register with Claude Code\n```\n\nThen just ask in plain language and refine the same way — the agent runs the\n`capabilities → validate → render` loop for you:\n\n> *\"draw a ClickHouse real-time analytics architecture, dark glass style\"*\n> *\"make the connectors thicker, dashed, with a gradient\"*\n> *\"add a diagonal grid to the background and brighten the node borders\"*\n\nThat's the whole workflow: **ask → tweak**. Prefer a Claude Code skill over MCP?\n`git clone` the repo and run `scripts\u002Finstall-skill.sh`. The full system prompt is in\n[PROMPT_TEMPLATE.md](docs\u002Fagent\u002FPROMPT_TEMPLATE.md); [`llms.txt`](llms.txt) covers other runtimes.\n\n## The loop your agent runs\n\niso-topology speaks contract, not vibes — your agent discovers the DSL, emits a\nscene, gets machine-checkable feedback, and converges with no human in the loop:\n\n```bash\nisotopo capabilities          # machine-readable DSL inventory — read once\nisotopo validate scene.yaml   # JSONPath-located issues + \"did you mean\" fixes (exit 0\u002F2\u002F3)\nisotopo evaluate scene.yaml   # scorecard: crossings \u002F overlaps \u002F tunnelling + composition score\nisotopo repair   scene.yaml --compose --write   # persist auto-fixes: occlusion, overlap,\n                                                # contrast + bounded alignment snapping\nisotopo render   scene.yaml out\nisotopo snapshot scene.yaml out                 # + faithful topology.png for visual self-review\nisotopo preview  scene.yaml out.svg core edge:3   # crop ONE node \u002F group \u002F edge\n```\n\n`validate` is a JSON-schema lint with fix suggestions; `evaluate` scores defects\n*and* composition (balance \u002F alignment \u002F rhythm \u002F hero dominance \u002F accent discipline)\nfrom a deterministic plan view; `repair` acts on both — fixing defects and snapping\noff-track parts onto their neighbours' alignment tracks, persisted back into the\nsource with comments intact. All of it lets an agent self-correct before it ever\nlooks at pixels. Output is byte-deterministic — same input, same SVG — which is what\nmakes the golden-file tests and clean git diffs work.\n\n## MCP server\n\n`isotopo-mcp` exposes the whole loop to any MCP client (Claude Code, Claude\nDesktop, Cursor, …) as seven stdio tools — `iso_capabilities`, `iso_validate`,\n`iso_evaluate`, `iso_repair`, `iso_render`, `iso_snapshot`, `iso_preview` — so\nan agent draws, self-corrects, *and* visually reviews its own output\n(validate → repair → render → snapshot) without shelling out to the CLI:\n\n```bash\ngo install github.com\u002FMarkovWangRR\u002Fiso-topology\u002Fcmd\u002Fisotopo-mcp@latest\nclaude mcp add isotopo -- isotopo-mcp        # Claude Code\n```\n\nClaude Desktop \u002F Cursor \u002F any generic client — add to its MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"isotopo\": { \"command\": \"isotopo-mcp\" }\n  }\n}\n```\n\nFull tool reference + the MCP-shaped loop: [docs\u002Fagent\u002FMCP.md](docs\u002Fagent\u002FMCP.md).\n\n## Studio — point, drag, restyle\n\n```bash\nisotopo serve input.yaml        # → http:\u002F\u002Flocalhost:8731\n```\n\n![isotopo Studio — rendered isometric scene on the left, editable YAML on the right](docs\u002Fassets\u002Fstudio.png)\n\nThe rendered scene on the left, its YAML on the right, sub-second feedback between.\n**Drag to lay out**, drag a node in\u002Fout of a group, **right-click to restyle**,\nadd \u002F delete \u002F duplicate \u002F connect nodes, toggle ◳ iso \u002F ◰ plan, undo\u002Fredo, and\nexport SVG \u002F PNG \u002F YAML. Every edit is an in-browser copy — the file on disk is never\ntouched until you hit save. Tour: [docs\u002Fguides\u002Fstudio.md](docs\u002Fguides\u002Fstudio.md).\n\n## What you can draw\n\n- **18 iso primitives** — boxes, cylinders, prisms (tri\u002Fhex\u002Foct), racks, arrays\n  (1D\u002F2D\u002F3D), clouds, people, boundaries (VPC\u002Fzone), wedges, custom polygons —\n  picked by *role*, not all rectangles.\n- **Coordinate-free layout** — `place: {rightOf|behind|above…, gap}` relations and\n  `layout: {mode: row|column|grid|ring|auto}` containers (auto = connector-driven\n  DAG). A solver computes positions, validates references, and warns on overlap.\n- **Design-grade styling** — per-face solid or gradient fills, translucent **glass**,\n  **grain**, `faceSplit` lighting, dot\u002Fhatch patterns (iso-projected), drop shadows,\n  backglow, rounded corners, wireframe.\n- **Connectors that read as systems** — `orthogonal` (rides the iso grid) \u002F `straight`\n  \u002F `bezier`, with dashes, gradients, waypoints, and labels.\n- **Two projections from one source** — the design-grade **isometric** view (default),\n  or a flat **2D top-down** \"documentation\" view when you want maximum legibility over\n  visual flair. Switch per-render with `--projection top` or per-scene with\n  `canvas: { projection: top }` — same DSL, same layout solver, no rewrite.\n  See [`samples\u002Ftopology\u002Fplan-view-2d`](samples\u002Ftopology\u002Fplan-view-2d\u002Finput.yaml).\n- **Named themes + semantic roles** — write pure topology (`role: hero | tray | chip`)\n  and pick a look: `--theme clickhouse-dark | navy-glass | handdrawn-paper | clean-light`\n  (or `theme: { use: \u003Cname> }` in the DSL). The theme supplies the design system —\n  role styles, sizing rhythm, text, canvas, even icon ink adapted to dark fills — so\n  the same scene re-skins coherently, and a plain `.d2` graph gets the full look from\n  one flag.\n- **One-flag readability** — `isotopo render --readable` layers a legibility-first\n  \"documentation\" profile over any scene: upright screen labels with a canvas-aware\n  contrast chip and a padding floor. Opt-in and non-destructive — it only fills gaps\n  you left blank, so hand-tuned scenes keep their look.\n- **200+ recolorable icons** — 150+ real brand logos (Simple Icons, CC0) plus 35\n  concept glyphs; tint any with `\u002FRRGGBB` or `\u002Flight`.\n- **Reusable looks** — `theme.presets` plus 28 ready-to-copy\n  [style references](samples\u002Fstyle_refer): pick a visual language by mood, copy\n  its `theme.presets` + `canvas`, then layer your topology on top.\n\nFull machine-readable inventory: `isotopo capabilities` (or\n[CAPABILITIES.md](docs\u002Fagent\u002FCAPABILITIES.md)).\n\n## Gallery\n\n**ClickHouse ecosystem** — dark frosted-glass hub-and-spoke, one neon accent. [Source](samples\u002Ftopology\u002Fclickhouse-hub\u002Finput.yaml)\n\n![ClickHouse ecosystem isometric diagram](docs\u002Fassets\u002Fclickhouse-hub.png)\n\n**DuckDB data architecture** — hand-drawn: warm paper, iso grid, film grain. [Source](samples\u002Ftopology\u002Fduckdb-handdrawn\u002Finput.yaml)\n\n![DuckDB hand-drawn isometric diagram](docs\u002Fassets\u002Fduckdb-handdrawn.png)\n\n**Databricks Lakehouse + LLM agent** — brand-faithful, single lava accent on a warm canvas. [Source](samples\u002Ftopology\u002Flakehouse-agent\u002Finput.yaml)\n\n![Databricks Lakehouse and LLM agent isometric diagram](docs\u002Fassets\u002Flakehouse-agent.png)\n\n**Training compute** — light canvas, dashed budget \"ghost\" volumes. [Source](samples\u002Ftopology\u002Ftraining-compute\u002Finput.yaml)\n\n![Isometric training-compute bar chart](docs\u002Fassets\u002Ftraining-compute.png)\n\n## Why isometric, and why this tool\n\nFlat 2D reads as a list of boxes; iso reads as a **system** — the depth axis\nseparates edge \u002F mid-tier \u002F data layers at a glance, and stacked nodes express\nreplicas and HA. Hand-drawing that in Figma scales to ~ten elements and zero people\non the diff.\n\n| | Mermaid \u002F D2 | Figma \u002F draw.io | **iso-topology** |\n|---|---|---|---|\n| Visual register | flat flowchart | design-grade | **design-grade isometric** |\n| Text source, git-diffable | ✓ | ✗ | ✓ |\n| Agent discovers + validates the DSL | ✗ | ✗ | **✓ (`capabilities` + `validate`)** |\n| Layout without hand-tuned coordinates | ✓ | ✗ | ✓ (`place` \u002F `layout` solver) |\n| Offline single binary | partial | ✗ | ✓ |\n\n## Use as a Go library\n\n```go\nimport isotopo \"github.com\u002FMarkovWangRR\u002Fiso-topology\"\n\nsvg, issues, _ := isotopo.RenderSource(\"yaml\", yamlBytes)            \u002F\u002F DSL → one SVG\n\nop := isotopo.EditOp{Kind: \"move\", Target: \"node\", ID: \"api\", DWX: 50}\nnewSrc, svg, issues, _ := isotopo.ApplyOp(\"yaml\", yamlBytes, op)     \u002F\u002F stateless canvas edit, comments preserved\n```\n\nThe stateless edit contract powers Studio and client-side WASM editors. Full surface:\nthe [API reference](docs\u002Freference\u002Fapi.md) ([godoc](https:\u002F\u002Fpkg.go.dev\u002Fgithub.com\u002FMarkovWangRR\u002Fiso-topology)).\n\n## Docs\n\nFull index at [docs\u002FREADME.md](docs\u002FREADME.md).\n\n- **Start:** [Tutorial](docs\u002Fgetting-started\u002F01-install.md) · [Recipes](docs\u002Fagent\u002FRECIPES.md) · [Scene design](docs\u002Fguides\u002Fscene-design.md)\n- **Reference:** [API](docs\u002Freference\u002Fapi.md) · [CLI](docs\u002Freference\u002Fcli.md) · [YAML DSL](docs\u002Freference\u002Fdsl-yaml.md) · [d2 DSL](docs\u002Freference\u002Fdsl-d2.md) · [Style\u002FTheme](docs\u002Freference\u002Fdsl-theme.md)\n- **Agents:** [CAPABILITIES](docs\u002Fagent\u002FCAPABILITIES.md) · [PROMPT_TEMPLATE](docs\u002Fagent\u002FPROMPT_TEMPLATE.md) · [SAMPLES](docs\u002Fagent\u002FSAMPLES.md) · [schema](docs\u002Fagent\u002Fschema\u002Fdsl.schema.json) · [MCP](docs\u002Fagent\u002FMCP.md) · [skills](skills\u002FREADME.md)\n\n## Status & contributing\n\nSingle-author project, moving fast — pin a tag if you depend on it (the `d2`\ndependency is locked at `v0.7.1`). Issues and PRs welcome; run `go test .\u002F...` first —\n`samples\u002F*\u002F*\u002Fexpected.svg` are golden files that catch output drift. Drew something\ncool? Open an issue with your scene + SVG and the best ones get linked here. ⭐ helps\nothers find it.\n\n## License\n\nApache License 2.0 — see [LICENSE](LICENSE). Rendered output is yours to use\ncommercially; bundled brand logos are CC0 from [Simple Icons](https:\u002F\u002Fsimpleicons.org).\n\u003C\u002Fcontent>\n","iso-topology 是一个将文本 DSL 编译为高质量等距（isometric）架构图的命令行工具。它采用 YAML 风格的领域特定语言描述系统拓扑，支持自动布局、品牌图标库（200+）、渐变\u002F阴影等设计级 SVG 渲染，并内置 LLM 友好型语法校验机制，确保 DSL 可被 AI 代理发现、生成与验证。项目以单二进制分发，零运行时依赖，离线执行，输出可版本控制、可 diff。适用于云原生系统文档、SRE 架构看板、AI 工程化部署图等需兼顾设计表现力与代码可维护性的场景。","2026-07-08 04:30:16","CREATED_QUERY"]