{"id":50548580,"url":"https://github.com/buffden/diagram-sync","last_synced_at":"2026-06-08T02:01:44.067Z","repository":{"id":361779052,"uuid":"1255471670","full_name":"Buffden/diagram-sync","owner":"Buffden","description":"diagram-sync is a developer tooling project for keeping architecture diagrams synchronized with source-controlled diagram definitions.","archived":false,"fork":false,"pushed_at":"2026-06-04T00:49:37.000Z","size":89,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-04T01:02:44.473Z","etag":null,"topics":["architecture","ci-cd","cli","developer-tools","diagram","diagrams-as-code","documentation-as-code","github-actions","plantuml","svg"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/Buffden.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-05-31T21:40:14.000Z","updated_at":"2026-06-04T00:49:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Buffden/diagram-sync","commit_stats":null,"previous_names":["buffden/diagram-sync"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/Buffden/diagram-sync","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Buffden%2Fdiagram-sync","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Buffden%2Fdiagram-sync/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Buffden%2Fdiagram-sync/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Buffden%2Fdiagram-sync/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Buffden","download_url":"https://codeload.github.com/Buffden/diagram-sync/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Buffden%2Fdiagram-sync/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34044919,"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-06-08T02:00:07.615Z","response_time":111,"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","ci-cd","cli","developer-tools","diagram","diagrams-as-code","documentation-as-code","github-actions","plantuml","svg"],"created_at":"2026-06-04T01:01:20.151Z","updated_at":"2026-06-08T02:01:44.048Z","avatar_url":"https://github.com/Buffden.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# diagram-sync\n\n\u003e Keep architecture diagrams synchronized with source code.\n\n[![npm version](https://img.shields.io/npm/v/diagram-sync)](https://www.npmjs.com/package/diagram-sync)\n[![npm downloads](https://img.shields.io/npm/dw/diagram-sync)](https://www.npmjs.com/package/diagram-sync)\n[![license](https://img.shields.io/npm/l/diagram-sync)](./LICENSE)\n\n`diagram-sync` is a CLI tool that automatically generates images from diagram source files. Drop it into any repo and run `npx diagram-sync` — it finds every supported diagram file, renders it to an image, and mirrors the output under a `diagrams/` folder. No config required.\n\n```bash\nnpx diagram-sync\n```\n\n---\n\n## The Problem\n\nEngineering teams update code but forget to re-export architecture diagrams. The result is stale documentation — READMEs, wikis, and onboarding docs that no longer reflect reality.\n\n`diagram-sync` eliminates the manual export step entirely. You edit the diagram source file. It generates the image automatically — locally or in CI/CD.\n\n\u003e **Honest note:** This tool removes export friction. It does not force developers to keep source diagrams accurate. That is a people problem, not a tooling problem.\n\n---\n\n## Install\n\n```bash\n# one-off, no install required\nnpx diagram-sync\n\n# or install globally\nnpm install -g diagram-sync\n\n# or as a dev dependency\nnpm install --save-dev diagram-sync\n```\n\n---\n\n## Quick Start\n\n1. Add a supported diagram source file anywhere in your repo\n2. Run `npx diagram-sync` from the project root\n3. Find the generated image in `diagrams/` mirroring the source path\n\n```text\nsrc/services/payment/flow.puml       →  diagrams/src/services/payment/flow.png\ndocs/architecture/system.puml        →  diagrams/docs/architecture/system.png\ndocs/flows/auth.mmd                  →  diagrams/docs/flows/auth.png\n```\n\nReference in your README:\n\n```markdown\n![System Architecture](diagrams/docs/architecture/system.png)\n```\n\n---\n\n## How It Works\n\n- Recursively scans your repo for diagram source files\n- Skips `node_modules`, `.git`, `dist`, `build`, `diagrams`\n- Derives the output path from the source file location — no input/output directories to configure\n- Generates images using the installed diagram tool for each provider — defaults to PNG, configurable via `--format` flag or config file\n\n---\n\n## Configuration\n\nConfig is optional. By default `diagram-sync` discovers all supported source files and generates images.\n\nOptionally add `diagram-sync.config.json` to your project root:\n\n```json\n{\n  \"format\": \"svg\",\n  \"jobs\": [\n    {\n      \"name\": \"architecture\",\n      \"type\": \"plantuml\",\n      \"format\": \"pdf\"\n    }\n  ]\n}\n```\n\nLoad the config file:\n\n```bash\nnpx diagram-sync --config diagram-sync.config.json\n```\n\nOverride format at runtime:\n\n```bash\nnpx diagram-sync --format svg\n```\n\nFormat resolution order: `--format` flag → job `format` → global `format` → default `png`.\n\n### Job Options\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `name` | `string` | Label for the job (used in logs) |\n| `type` | `string` | Diagram provider (e.g. `plantuml`, `mermaid`) — see Supported Providers for all values |\n| `format` | `string` | Output format for this job (e.g. `png`, `svg`, `pdf`) — overrides global format |\n\n---\n\n## Supported Providers\n\n`diagram-sync` supports any diagram source that is committed to Git, maintained as a file, and can be converted to an image via a CLI — regardless of whether it was created by hand, a GUI tool, or AI.\n\n| Provider | Extensions | Status | Guide |\n| --- | --- | --- | --- |\n| PlantUML | `.puml`, `.plantuml` | Supported | [Setup \u0026 CI/CD](https://github.com/Buffden/diagram-sync/tree/main/docs/providers/plantuml) |\n| Mermaid | `.mmd`, `.mermaid` | Supported | [Setup \u0026 CI/CD](https://github.com/Buffden/diagram-sync/tree/main/docs/providers/mermaid) |\n| Graphviz | `.dot`, `.gv` | Planned | — |\n| Draw.io | `.drawio`, `.dio` | Planned | — |\n| D2 | `.d2` | Planned | — |\n| Excalidraw | `.excalidraw` | Planned | — |\n| BPMN | `.bpmn` | Planned | — |\n| Structurizr DSL | `.dsl` | Planned | — |\n| Vega / Vega-Lite | `.vg.json`, `.vl.json` | Planned | — |\n| Gnuplot | `.gp`, `.gnuplot` | Planned | — |\n| Svgbob | `.bob` | Planned | — |\n| WaveDrom | `.waveform` | Planned | — |\n| Ditaa | `.ditaa` | Planned | — |\n| Pikchr | `.pikchr` | Planned | — |\n| Nomnoml | `.nomnoml` | Planned | — |\n| Mscgen | `.msc` | Planned | — |\n| Asymptote | `.asy` | Planned | — |\n| ERD | `.er` | Planned | — |\n\n---\n\n## Usage Options\n\n### 1. One-off local generation\n\n```bash\nnpx diagram-sync\n```\n\n### 2. npm script\n\n```json\n\"scripts\": {\n  \"diagrams\": \"diagram-sync\"\n}\n```\n\n```bash\nnpm run diagrams\n```\n\n### 3. CI/CD\n\nGenerates and commits diagram images on every push:\n\n```yaml\nname: Generate and Commit Diagrams\n\non:\n  push:\n    paths:\n      - '**/*.puml'\n      - '**/*.plantuml'\n      - '**/*.mmd'\n      - '**/*.mermaid'\n  workflow_dispatch:\n\njobs:\n  generate:\n    runs-on: ubuntu-latest\n\n    steps:\n      - uses: actions/checkout@v5\n        with:\n          token: ${{ secrets.PAT_TOKEN }}\n\n      - name: Install PlantUML\n        run: |\n          sudo apt-get update\n          sudo apt-get install -y --no-install-recommends default-jre-headless plantuml\n\n      - name: Install Mermaid CLI\n        run: npm install -g @mermaid-js/mermaid-cli\n\n      - name: Generate diagrams\n        run: npx diagram-sync\n        # add --format svg or --format pdf to override the default png output\n\n      - name: Commit generated diagrams\n        run: |\n          git config user.name \"github-actions[bot]\"\n          git config user.email \"github-actions[bot]@users.noreply.github.com\"\n          git add diagrams/\n          if git diff --staged --quiet; then\n            echo \"No diagram changes to commit.\"\n          else\n            git commit -m \"chore: auto-export diagrams [skip ci]\"\n            git push\n          fi\n```\n\nRequires a PAT with `contents: write` saved as `PAT_TOKEN` in your repo secrets. See the **[Provider Guides](https://github.com/Buffden/diagram-sync/tree/main/docs/providers)** for the ready-to-use workflow file.\n\n---\n\n## Requirements\n\n- Node.js 20+\n- Each provider requires its own CLI tool — install only what you need:\n  - **PlantUML:** Java 11+ and PlantUML — see [PlantUML guide](https://github.com/Buffden/diagram-sync/tree/main/docs/providers/plantuml)\n  - **Mermaid:** see [Mermaid guide](https://github.com/Buffden/diagram-sync/tree/main/docs/providers/mermaid)\n  - **Other providers:** see [Provider Guides](https://github.com/Buffden/diagram-sync/tree/main/docs/providers)\n\nProviders are detected at runtime and missing ones are skipped with a warning.\n\n---\n\n## Common Use Cases\n\n- **How to automate PlantUML diagram generation in CI/CD**\n- **How to automate Mermaid diagram generation in CI/CD**\n- **How to automate Graphviz diagram generation in CI/CD**\n- **How to convert Draw.io files to images automatically**\n- **How to export Excalidraw diagrams in CI/CD**\n- **How to keep README architecture diagrams up to date automatically**\n- **How to sync architecture diagrams from source files**\n- **How to generate architecture diagrams on GitHub Actions**\n- **How to treat architecture diagrams as code**\n- **Documentation-as-code workflow for PlantUML, Mermaid, and more**\n\n---\n\n## Links\n\n- **npm:** [https://www.npmjs.com/package/diagram-sync](https://www.npmjs.com/package/diagram-sync)\n- **GitHub:** [https://github.com/Buffden/diagram-sync](https://github.com/Buffden/diagram-sync)\n- **Provider Guides:** [https://github.com/Buffden/diagram-sync/tree/main/docs/providers](https://github.com/Buffden/diagram-sync/tree/main/docs/providers)\n\n---\n\n## License\n\nMIT — [Buffden](https://buffden.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuffden%2Fdiagram-sync","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbuffden%2Fdiagram-sync","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuffden%2Fdiagram-sync/lists"}