{"id":38413210,"url":"https://github.com/localgod/catalyst","last_synced_at":"2026-01-18T11:11:13.414Z","repository":{"id":215459951,"uuid":"655698495","full_name":"localgod/catalyst","owner":"localgod","description":"Convert C4 diagrams in PlantUML to Draw.io","archived":false,"fork":false,"pushed_at":"2025-12-15T09:00:52.000Z","size":2530,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-18T07:34:09.923Z","etag":null,"topics":["c4-model","drawio","plantuml"],"latest_commit_sha":null,"homepage":"https://catalyst.mindfield.dk","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/localgod.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","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":"2023-06-19T12:18:46.000Z","updated_at":"2025-12-15T09:00:53.000Z","dependencies_parsed_at":"2024-03-25T09:54:23.892Z","dependency_job_id":"4ba07c6c-b5ae-4392-ab24-93774d3857ef","html_url":"https://github.com/localgod/catalyst","commit_stats":null,"previous_names":["localgod/catalyst"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/localgod/catalyst","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localgod%2Fcatalyst","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localgod%2Fcatalyst/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localgod%2Fcatalyst/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localgod%2Fcatalyst/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/localgod","download_url":"https://codeload.github.com/localgod/catalyst/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localgod%2Fcatalyst/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28494251,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T02:39:23.645Z","status":"ssl_error","status_checked_at":"2026-01-17T02:34:19.649Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["c4-model","drawio","plantuml"],"created_at":"2026-01-17T04:05:13.886Z","updated_at":"2026-01-17T04:05:14.426Z","avatar_url":"https://github.com/localgod.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Catalyst\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"logo.svg\" width=\"100\" height=\"100\" alt=\"Catalyst Logo\"\u003e\n\u003c/div\u003e\n\n[![CI](https://github.com/localgod/catalyst/actions/workflows/ci.yml/badge.svg)](https://github.com/localgod/catalyst/actions/workflows/ci.yml)\n\n## Overview\n\nCatalyst is a JavaScript library designed to facilitate the conversion of\nC4 diagrams written in [PlantUML](https://plantuml.com/) format into [draw.io](https://draw.io)\nC4 diagrams. While PlantUML itself is not required as a runtime dependency,\nthe library parses diagrams written in PlantUML's C4 syntax (.puml files).\nThis project uses the Dagre layout engine for fast, pure JavaScript\nlayout calculation without external dependencies.\n\n## Installation\n\nInstall Catalyst as a dependency in your project:\n\n```bash\nnpm install catalyst\n```\n\n## Requirements\n\n- [NodeJS](https://nodejs.org) (ES2024+ support)\n\n## Input Format\n\nCatalyst processes C4 diagrams written in PlantUML syntax (.puml files). While the PlantUML\nruntime is not required, the input files should follow PlantUML's C4 diagram syntax including:\n\n- `System()`, `Container()`, `Component()` declarations\n- `Rel()` relationship definitions\n- Standard PlantUML C4 includes and formatting\n\nExample input file structure:\n\n```plantuml\n@startuml\n!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml\n\nSystem(systemA, \"System A\", \"Description\")\nContainer(containerA, \"Container A\", \"Technology\", \"Description\")\nComponent(componentA, \"Component A\", \"Technology\", \"Description\")\n\nRel(systemA, containerA, \"Uses\")\n@enduml\n```\n\n## Usage\n\n### Basic Usage\n\n```javascript\nimport { Catalyst } from 'catalyst'\nimport fs from 'fs'\n\n// Read PlantUML content\nconst pumlContent = await fs.promises.readFile('diagram.puml', 'utf-8')\n\n// Convert to draw.io XML\nconst drawioXml = await Catalyst.convert(pumlContent)\n\n// Save the result\nawait fs.promises.writeFile('output.drawio', drawioXml)\n```\n\n### Advanced Usage with Options\n\n```javascript\nimport { Catalyst } from 'catalyst'\n\nconst drawioXml = await Catalyst.convert(pumlContent, {\n  layoutDirection: 'LR',  // 'TB', 'BT', 'LR', 'RL'\n  nodesep: 50,           // Node separation\n  edgesep: 10,           // Edge separation\n  ranksep: 50,           // Rank separation\n  marginx: 20,           // X margin\n  marginy: 20            // Y margin\n})\n```\n\n### Utility Methods\n\n```javascript\n// Parse entities only\nconst entities = Catalyst.parseEntities(pumlContent)\n\n// Parse relations only\nconst relations = Catalyst.parseRelations(pumlContent)\n```\n\n## Try it out\n\n- Checkout this repo\n- Run `npm install` to install dependencies\n- Run `npm run build` to compile the library\n- Run `npm run example` to test the sample usage\n\nThe sample output is written to `sample/output.drawio`.\n\n## Purpose\n\n### Bridging Standards\n\nPlantUML C4 format and draw.io are widely used diagramming approaches, each with unique\nstrengths. While PlantUML C4 format excels in creating architectural diagrams using textual\ndescriptions, draw.io offers a more visual and intuitive diagramming\nexperience. This project seeks to bridge the gap between these two approaches,\nallowing users to harness the power of both tools without requiring PlantUML runtime.\n\n### Supporting C4 Modelling\n\nThe primary goal of this project is to support the [C4](https://c4model.com)\nmodelling standard. C4 (Context, Containers, Components, and Code) is a popular\narchitectural modeling approach for visualizing and documenting software\narchitecture. By enabling the conversion of PlantUML C4 diagrams to draw.io,\nthis library facilitates the adoption of C4 modelling by providing a smooth\ntransition from PlantUML's text-based format to draw.io's graphical capabilities.\n\n## Key Features\n\n- **PlantUML C4 Format Support:** The library parses and converts C4 diagrams\nwritten in PlantUML syntax (.puml files) without requiring PlantUML runtime.\n\n- **Fast Layout Engine:** Uses Dagre for pure JavaScript layout calculation,\neliminating external dependencies and providing fast performance.\n\n- **draw.io Integration:** The resulting draw.io diagrams are seamlessly\nintegrated with draw.io's native features, allowing users to further enhance and\nrefine their diagrams.\n\n## Getting Started\n\n1. **Installation:** Install the library using npm:\n\n   ```bash\n   npm install catalyst\n   ```\n\n2. **Usage:** Import and use the library in your project:\n\n   ```javascript\n   import { Catalyst } from 'catalyst'\n   const drawioXml = await Catalyst.convert(pumlContent)\n   ```\n\n3. **Documentation:** Refer to the documentation for detailed instructions on how to use\nthe converter. Examples and usage scenarios are provided to assist you.\n\n4. **Contribute:** We welcome contributions from the community. Feel free to\nsubmit bug reports, feature requests, or pull requests on our GitHub repository.\n\n## Testing and Coverage\n\nThe project includes comprehensive test coverage with automated reporting:\n\n- **Run tests:** `npm run test:run`\n- **Run with coverage:** `npm run test:coverage`\n- **Coverage thresholds:** 85% for branches, functions, lines, and statements\n- **Automated coverage reports** are generated on every PR via GitHub Actions\n\nCurrent coverage: **89.35%** overall with 106 passing tests.\n\n## Why Convert?\n\n### Flexibility and Collaboration\n\n- **Textual vs. Visual:** PlantUML C4 format allows you to describe diagrams using text,\nwhich can be convenient for version control and collaboration. However, draw.io\noffers a more visual and interactive approach, making it easier to create\ncomplex diagrams.\n\n- **Team Collaboration:** Converting PlantUML diagrams to draw.io format can\nenhance team collaboration. Team members can work on diagrams using the\nuser-friendly draw.io interface, even if they are not familiar with PlantUML.\n\n### C4 Modelling Adoption\n\n- **C4 Modelling:** C4 is a widely adopted standard for software architecture\nmodeling. By supporting C4 modelling in draw.io, this converter facilitates the\nadoption of this powerful approach.\n\n- **Better Visualization:** draw.io's graphical capabilities enable the creation\nof more visually appealing and informative C4 diagrams, enhancing the\ncommunication of architectural concepts.\n\n## License\n\nThis project is released under the [MIT License](LICENSE). You are free to use,\nmodify, and distribute the software as per the terms of the license.\n\n## Feedback and Support\n\nIf you have any questions, feedback, or encounter issues with the converter,\nplease open an issue.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocalgod%2Fcatalyst","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flocalgod%2Fcatalyst","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocalgod%2Fcatalyst/lists"}