{"id":34123403,"url":"https://github.com/holydocs/messageflow","last_synced_at":"2025-12-14T22:42:37.547Z","repository":{"id":299129529,"uuid":"1002143991","full_name":"holydocs/messageflow","owner":"holydocs","description":"System-architecture documentation and diagrams from AsyncAPI specifications","archived":false,"fork":false,"pushed_at":"2025-12-06T08:56:17.000Z","size":408,"stargazers_count":10,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-10T02:18:43.617Z","etag":null,"topics":["asyncapi","d2","diagram"],"latest_commit_sha":null,"homepage":"","language":"Go","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/holydocs.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":"2025-06-14T20:08:59.000Z","updated_at":"2025-12-06T08:56:21.000Z","dependencies_parsed_at":"2025-06-14T21:26:32.002Z","dependency_job_id":"bb9dda81-7870-494a-a456-c817858b6574","html_url":"https://github.com/holydocs/messageflow","commit_stats":null,"previous_names":["denchenko/messageflow","holydocs/messageflow"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/holydocs/messageflow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holydocs%2Fmessageflow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holydocs%2Fmessageflow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holydocs%2Fmessageflow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holydocs%2Fmessageflow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/holydocs","download_url":"https://codeload.github.com/holydocs/messageflow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holydocs%2Fmessageflow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27738275,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-14T02:00:11.348Z","response_time":56,"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":["asyncapi","d2","diagram"],"created_at":"2025-12-14T22:42:33.143Z","updated_at":"2025-12-14T22:42:37.542Z","avatar_url":"https://github.com/holydocs.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MessageFlow\n\n[![Run Tests](https://github.com/holydocs/messageflow/actions/workflows/go.yml/badge.svg?branch=main)](https://github.com/holydocs/messageflow/actions/workflows/go.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/holydocs/messageflow)](https://goreportcard.com/report/github.com/holydocs/messageflow)\n[![GoDoc](https://godoc.org/github.com/holydocs/messageflow?status.svg)](https://godoc.org/github.com/holydocs/messageflow)\n\nMessageFlow is a Go library and CLI tool for visualizing AsyncAPI specifications. It provides tools to parse AsyncAPI documents and transform them into visual formats, making it easier to understand message flows and service interactions in asynchronous systems.\n\nIt is part of the [HolyDOCs](https://github.com/holydocs/holydocs) umbrella project, which creates unified, interactive documentation for microservices architectures.\n\n## Use Cases\n\n### Single Service\n\nExample of visualizing a Notification service using [this](pkg/schema/source/asyncapi/testdata/notification.yaml) AsyncAPI specification. It can be useful to display service communication with a message bus without requiring detailed knowledge about other services in the ecosystem. Message payloads are displayed as thumbnails when hovering over specific queues. This approach was chosen to keep the schema clean and uncluttered.\n\n![schema](pkg/schema/target/d2/testdata/service_channels_notification.svg)\n\n### Multiple Services\n\nWhen you have AsyncAPI specifications for all services in your system, MessageFlow can generate comprehensive documentation showing the complete service ecosystem. See [examples/docs](examples/docs) for a complete multi-service documentation example. For instance, in the generated documentation, the same service now appears like this:\n\n![schema](examples/docs/diagrams/service_notification-service.svg)\n\n### Automatic Docs Generation Using Github Actions\n\nYou can also set up your own centralized documentation hub that automatically generates documentation with changelog whenever source repositories are updated.\n\n```\nSource Repo A ──┐\nSource Repo B ──┼──\u003e MessageFlow Aggregator ──\u003e Generated Docs\nSource Repo C ──┘\n```\n\nReview [messageflow-aggregator-workflow-example](https://github.com/holydocs/messageflow-aggregator-workflow-example) for detailed instructions.\n\n## Usage\n\nMessageFlow provides a command-line interface and can be used via Docker.\n\n### Using Go Binary\n\nInstall the binary directly:\n\n```bash\ngo install github.com/holydocs/messageflow/cmd/messageflow@latest\n```\n\n### Generate Schema\n\nThe `gen-schema` command processes AsyncAPI files and generates formatted schemas or rendered diagrams:\n\n```bash\n# Generate and render a diagram\nmessageflow gen-schema --target d2 --render-to-file schema.svg --asyncapi-files asyncapi.yaml\n\n# Generate formatted schema only\nmessageflow gen-schema --format-to-file schema.d2 --asyncapi-files asyncapi.yaml\n\n# Process multiple AsyncAPI files\nmessageflow gen-schema --render-to-file combined.svg --asyncapi-files \"file1.yaml,file2.yaml,file3.yaml\"\n```\n\n### Generate Documentation\n\nThe `gen-docs` command generates comprehensive markdown documentation from AsyncAPI files, including diagrams and changelog tracking:\n\n```bash\n# Generate documentation for multiple services\nmessageflow gen-docs --asyncapi-files \"service1.yaml,service2.yaml,service3.yaml\" --output ./docs\n```\n\nThe generated documentation includes:\n- **Context diagram**: Overview of all services and their interactions\n- **Service diagrams**: Individual diagrams showing each service's channels and operations\n- **Channel diagrams**: Detailed views of message flows through specific channels\n- **Changelog tracking**: Automatic detection and documentation of schema changes between runs\n- **Message payloads**: JSON schemas for all message types\n\n### Using Docker\n\nPull and run the latest version:\n\n```bash\n# Pull the image\ndocker pull ghcr.io/holydocs/messageflow:latest\n\n# Generate documentation\ndocker run --rm -v $(pwd):/work -w /work ghcr.io/holydocs/messageflow:latest gen-docs --asyncapi-files \"service1.yaml,service2.yaml\" --output ./docs\n```\n\n## Known Limitations\n\n* One kind of server protocol per spec.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fholydocs%2Fmessageflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fholydocs%2Fmessageflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fholydocs%2Fmessageflow/lists"}