{"id":50338772,"url":"https://github.com/wyofalcon/daemonstrate","last_synced_at":"2026-05-29T15:30:30.599Z","repository":{"id":353011344,"uuid":"1217572049","full_name":"wyofalcon/daemonstrate","owner":"wyofalcon","description":"Claude Code skill that auto-generates dark-themed draw.io architecture diagrams for any codebase","archived":false,"fork":false,"pushed_at":"2026-04-22T04:53:09.000Z","size":32,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-22T05:41:31.060Z","etag":null,"topics":["architecture-diagram","claude-code","claude-skill","developer-tools","drawio"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wyofalcon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-22T02:42:01.000Z","updated_at":"2026-04-22T04:53:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/wyofalcon/daemonstrate","commit_stats":null,"previous_names":["wyofalcon/daemonstrate"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/wyofalcon/daemonstrate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wyofalcon%2Fdaemonstrate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wyofalcon%2Fdaemonstrate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wyofalcon%2Fdaemonstrate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wyofalcon%2Fdaemonstrate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wyofalcon","download_url":"https://codeload.github.com/wyofalcon/daemonstrate/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wyofalcon%2Fdaemonstrate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33659872,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["architecture-diagram","claude-code","claude-skill","developer-tools","drawio"],"created_at":"2026-05-29T15:30:29.570Z","updated_at":"2026-05-29T15:30:30.592Z","avatar_url":"https://github.com/wyofalcon.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Daemonstrate\n\nA [Claude Code](https://claude.ai/code) skill that generates polished, light-theme `.drawio` architecture diagrams for any codebase — and keeps them current via an optional post-commit hook.\n\n```\n/daemonstrate\n```\n\n---\n\n## What it produces\n\n| File | Pages | Audience | Contents |\n|---|---|---|---|\n| `docs/architecture-portfolio.drawio` | 1 | Recruiters, stakeholders | Single-page poster. Dashed pastel container per layer with capability pills + tech badges. Headline data flows. Scannable in ~10 seconds. |\n| `docs/architecture-detailed.drawio` | 1 + N | Collaborators, AI agents | Multi-page drill-down. Overview page (lane headers + tech badges + headline node teasers) + one detail page per layer (full key-nodes grid + internal edges + clickable \"Connects to\" sidebar). |\n| `docs/architecture-journey.drawio` *(opt-in)* | 1 | Family, non-technical reviewers, end users | Single-page vertical user-flow spine. User actions on the left, app actions on the right, numbered badges down the middle. Hover any step for the rich detail (description / what you'll see / tips). |\n\nAll three diagrams use the same visual language — dashed pastel group containers, orthogonal labeled edges, dark text on white, drop shadows. Modeled after a clean architecture flowchart, so a reader switching between them never has to re-orient. GitHub renders `.drawio` files inline when a companion `.svg` export exists.\n\n---\n\n## When is this worth the tokens?\n\nFirst run on a fresh repo is the expensive one — scope discovery, per-scope exploration, and Plain-English translation of every label all happen once. Incremental runs (driven by the post-commit hook) are much cheaper: three-level caching means most commits only re-explore the scopes whose files changed and re-translate a handful of labels.\n\nThe cost earns its keep when:\n\n- **You're onboarding a collaborator.** Drop them into `architecture-detailed.drawio` and let the diagram carry the context you'd otherwise spend most of a meeting explaining.\n- **You're sharing with a non-technical stakeholder.** The Plain-English tab renders *\"the website asks the server to save a note\"* instead of `POST /api/notes` — no separate deck to maintain, no translation drift.\n- **You think visually.** The diagrams become external working memory; teaching-mode drill-down lets you zoom into whichever part of the system you're currently reasoning about, on demand.\n\nIf none of those apply, a one-time hand-drawn diagram is probably the better call. See [ROADMAP.md](./ROADMAP.md) for work in flight around *opportunistic* generation — deferring the expensive passes to session windows where the tokens would otherwise go unused.\n\n---\n\n## Installation\n\nDaemonstrate is a Claude Code skill. Clone this repo into your skills directory:\n\n```bash\n# Claude Code looks for skills in ~/.claude/skills/ by default\ngit clone https://github.com/wyofalcon/daemonstrate ~/.claude/skills/daemonstrate\n```\n\nThen in Claude Code, invoke it:\n\n```\n/daemonstrate\n```\n\nThat's it. Claude will detect your stack, classify layers, explore the codebase, and write both diagrams into `docs/`.\n\n---\n\n## How it works\n\n```\n1. Detect tech stack      package.json, pyproject.toml, go.mod, Cargo.toml, …\n2. Classify layers        Frontend / Mobile / Backend / Data / Jobs / Integrations / Infra\n3. Explore each layer     Glob + Grep to find routes, services, tables, jobs\n4. Generate graph spec    Intermediate JSON describing all diagrams\n5. Run drawio_builder.py  Emits valid .drawio XML — single-page portfolio,\n                          multi-page detailed (overview + 1 page per layer),\n                          and (optionally) single-page journey.\n6. Write state sidecar    .daemonstrate-state.json tracks lastSha for incremental runs\n```\n\nOn subsequent runs, only layers whose files changed since `lastSha` are re-explored. The builder preserves node IDs across generations so PR diffs stay minimal.\n\n---\n\n## Customizing with a graph spec\n\nDrop a `docs/graph-spec.json` in your repo to drive the diagrams directly — useful when you want a curated story instead of (or alongside) the auto-detected architecture.\n\n### Minimal spec\n\n```json\n{\n  \"title\": \"My Project\",\n  \"subtitle\": \"One-line pitch\",\n  \"layers\": [\n    {\n      \"layer_name\": \"backend\",\n      \"display_name\": \"Backend\",\n      \"accent\": \"#A6E3A1\",\n      \"tech_badges\": [\"Node.js\", \"Express 5\"],\n      \"capabilities\": [\"REST API\", \"Auth middleware\"],\n      \"key_nodes\": [\n        { \"id\": \"be-routes\", \"label\": \"POST /api/notes\", \"file_path\": \"src/routes/notes.js\" }\n      ],\n      \"internal_edges\": [],\n      \"external_edges\": []\n    }\n  ]\n}\n```\n\n### Adding the journey diagram\n\nAdd a `user_flow` array (and run with `--out-journey`) to also produce the single-page user-journey spine:\n\n```json\n{\n  \"title\": \"My Project\",\n  \"subtitle\": \"One-line pitch\",\n  \"layers\": [...],\n\n  \"user_flow\": [\n    {\n      \"id\": \"uf-spot\",\n      \"actor\": \"user\",\n      \"label\": \"Spot it\",\n      \"detail\": \"a bug, idea, or design problem\",\n      \"description\": \"Longer explanation, surfaced as a hover tooltip.\",\n      \"what_you_see\": \"What the UI looks like at this moment.\",\n      \"tips\": [\"Tip one\", \"Tip two\"]\n    }\n  ]\n}\n```\n\n`actor` is either `\"user\"` (renders left, sky blue) or `\"app\"` (renders right, mint green). The rich `description` / `what_you_see` / `tips` fields all merge into the step's hover tooltip so the page stays scannable.\n\n---\n\n## Running the builder standalone\n\n`scripts/drawio_builder.py` has no external dependencies — pure Python 3.8+ stdlib.\n\n```bash\npython scripts/drawio_builder.py \\\n  --spec docs/graph-spec.json \\\n  --out-portfolio docs/architecture-portfolio.drawio \\\n  --out-detailed  docs/architecture-detailed.drawio \\\n  --out-journey   docs/architecture-journey.drawio   # optional\n```\n\nPipe a spec from stdin:\n\n```bash\necho '{\"title\":\"Demo\",\"layers\":[...]}' | python scripts/drawio_builder.py \\\n  --out-portfolio out/portfolio.drawio \\\n  --out-detailed  out/detailed.drawio\n```\n\n---\n\n## Color palette\n\nCatppuccin-inspired accents on a white canvas. Each accent renders as a pastel fill (22% accent + 78% white) for containers and nodes, with the saturated accent for borders, badges, and capability pills.\n\n| Layer | Accent |\n|---|---|\n| Frontend | `#89B4FA` sky blue |\n| Mobile | `#B4BEFE` periwinkle |\n| Backend / API | `#A6E3A1` mint |\n| Data | `#F9E2AF` warm yellow |\n| Jobs / Workers | `#FAB387` peach |\n| Integrations | `#F38BA8` rose |\n| Infra | `#CBA6F7` lavender |\n\nFull palette + contrast rules in `references/light-theme-palette.md`.\n\n---\n\n## Post-commit hook\n\nDuring an interactive run, Daemonstrate will offer to install a post-commit hook that re-runs in incremental mode after each commit. Cost per commit is low — only changed layers are re-explored.\n\nTo install manually:\n\n```bash\nbash scripts/install-hooks.sh /path/to/your/repo\n```\n\n---\n\n## Requirements\n\n- **Claude Code** (for the `/daemonstrate` skill invocation)\n- **Python 3.8+** (stdlib only, for `drawio_builder.py`)\n- **diagrams.net** / **draw.io desktop** to view and edit the output\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwyofalcon%2Fdaemonstrate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwyofalcon%2Fdaemonstrate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwyofalcon%2Fdaemonstrate/lists"}