{"id":13567286,"url":"https://github.com/ddd-crew/domain-message-flow-modelling","last_synced_at":"2026-02-13T11:51:40.817Z","repository":{"id":37702380,"uuid":"261289221","full_name":"ddd-crew/domain-message-flow-modelling","owner":"ddd-crew","description":"Design \u0026 visualise the flow of commands, events, and queries between your bounded contexts","archived":false,"fork":false,"pushed_at":"2023-12-27T16:02:01.000Z","size":2232,"stargazers_count":392,"open_issues_count":2,"forks_count":35,"subscribers_count":31,"default_branch":"master","last_synced_at":"2025-09-05T11:40:29.770Z","etag":null,"topics":["architecture","domain-driven-design","software-design","tactical-design-patterns"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc-by-sa-4.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ddd-crew.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2020-05-04T20:31:51.000Z","updated_at":"2025-09-02T07:13:13.000Z","dependencies_parsed_at":"2024-08-01T13:39:32.394Z","dependency_job_id":null,"html_url":"https://github.com/ddd-crew/domain-message-flow-modelling","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ddd-crew/domain-message-flow-modelling","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddd-crew%2Fdomain-message-flow-modelling","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddd-crew%2Fdomain-message-flow-modelling/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddd-crew%2Fdomain-message-flow-modelling/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddd-crew%2Fdomain-message-flow-modelling/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ddd-crew","download_url":"https://codeload.github.com/ddd-crew/domain-message-flow-modelling/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddd-crew%2Fdomain-message-flow-modelling/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29404136,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-13T06:24:03.484Z","status":"ssl_error","status_checked_at":"2026-02-13T06:23:12.830Z","response_time":78,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5: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":["architecture","domain-driven-design","software-design","tactical-design-patterns"],"created_at":"2024-08-01T13:02:27.644Z","updated_at":"2026-02-13T11:51:40.779Z","avatar_url":"https://github.com/ddd-crew.png","language":null,"funding_links":[],"categories":["others","Misc"],"sub_categories":[],"readme":"# Domain Message Flow Modelling\n\nDesigning loosely-coupled systems requires more than carefully designed boundaries. Carefully defined interactions between bounded contexts is equally important.\n\nA [bounded context](https://martinfowler.com/bliki/BoundedContext.html) is a sub-system in a software architecture aligned to a part of the domain. It can be implemented as a microservice or a module within a monolith.\n\nA Domain Message Flow Diagram is a simple visualisation showing the flow of messages (commands, events, queries) between actors, bounded contexts, and systems, for a single scenario.\n\n## Formats\n\nThere are 2 basic formats, but there is no formal specification so adjust the tool to suit your needs if the basic formats don't work for you.\n\n### Separate Message \u0026 Contents\n\nThe separate message \u0026 contents format uses 2 shapes for each message: 1 for the name and order of the message and a separate box to display the contents of the message (the information it carries).\n\nThe benefit of this format is that you can focus on the flow of messages without getting bogged down by the message contents at the start.\n\nStart by showing just the messages flowing between senders and receivers (with the order number on the message).\n\n![Message Flow Just Messages](resources/just-messages-no-contents.jpg)\n\nThen show the contents of each message in a separate box next to each message:\n\n![Message Flow Messages \u0026 Contents](resources/messages-and-contents.jpg)\n\n### Combined Message \u0026 Contents\n\nThe combined message \u0026 contents format uses a single shape to capture the message name, order, and contents.\n\n![Example Message Flow](resources/domain-message-flow.jpg \"An Example Domain Message Flow\")\n\nThis format is good when you want to focus on the contents of each message from the beginning.\n\n### Downloads\n\n- [Domain Message Flow Modelling (miro board backup)](resources/Domain-Message-Flow-Modelling-en-v1.rtb)\n\n## How to Use\n\nWhen you have an initial cut of your architecture - you have identified candidate bounded contexts - you can begin design the message flows.\n\nStart by creating a list of of scenarios to model. And then for each scenario create a diagram\n\nWhen creating a diagram, the typical flow is:\n\n1. Start with an actor/context/system\n2. Create the message they want to send\n3. Add the recipient of the message and a line connecting the sender and the receiver\n4. Place the message close to the line\n5. Repeat steps 1 - 4 until your scenario is complete\n\nThe message should contain 3 elements:\n\n1. The name of the message\n2. The significant data contained within the message\n3. The order in which the message occurs in the flow being modelled\n\n_Note:_ In case of a query, the response is just as important as the request. The information can be seen and represented as one unit, like this\n\u003cimg src=\"resources/query-req-resp.png\" alt=\"Message as a query\" width=\"250\" height=\"auto\"\u003e\n\n## Visualisation Tips\n\nThe number one problem with Domain Message Flow Diagrams, and diagrams in general, is too much information. [Miller's Law](https://en.wikipedia.org/wiki/Miller%27s_law) is a good heuristic to use here. Aim to have between 5 and 9 messages on your diagram.\n\nIf you find that adding the data to each message is breaking your flow of progress, you can defer the data section of each message it until you have placed all of your messages.\n\n### Time-Dependent Messages\nSometimes messages are time-driven. E.g. scenario: cancel an online order after 5 minutes of inactivity. A visualisation like this could work fine. Important is to pay attention to the semantics: **within** or **after** or **every** 5 minutes are very different conditions.\n\u003cimg src=\"resources/time-dependent-message.png\" alt=\"Time-dependent Message\" width=\"80%\" height=\"auto\"\u003e\n\n\n## Additional Resources\n\n- [DDD Pattern: Library Contexts](https://medium.com/nick-tune-tech-strategy-blog/ddd-pattern-library-contexts-d6ae81f462ef)\n- [Mapper Contexts \u0026 Supercontexts: Decoupling Domain-Specific and Domain-Generic Bounded Contexts](https://medium.com/nick-tune-tech-strategy-blog/mapper-contexts-supercontexts-decoupling-domain-specific-and-domain-generic-bounded-contexts-5eb6a1e7c5fc)\n- [Gateway Interchange Contexts](https://medium.com/nick-tune-tech-strategy-blog/gateway-interchange-contexts-899696e67848)\n\n## Contributors\n\nThanks to all [existing and future contributors](https://github.com/ddd-crew/domain-message-flow-modelling/graphs/contributors) and to the following individuals who have all contributed to Domain Message Flow Modelling:\n\n- [Kacper Gunia](https://github.com/cakper)\n- [Zsofia Herendi](https://twitter.com/zherendi)\n- [Nick Tune](https://github.com/ntcoding)\n\nDomain Message Flow Diagrams are heavily inspired by:\n\n- [Simon Brown's C4 Container Diagrams](https://c4model.com/)\n- [Domain Storytelling](https://domainstorytelling.org/)\n\n## Contributions and Feedback\n\nThe Domain Message Flow Modelling notation is freely available for you to use. In addition, your feedback and ideas are welcome to improve the technique or to create alternative versions.\n\nFeel free to also send us a pull request with your examples.\n\n[![CC BY 4.0][cc-by-shield]][cc-by]\n\nThis work is licensed under a [Creative Commons Attribution 4.0 International\nLicense][cc-by].\n\n[![CC BY 4.0][cc-by-image]][cc-by]\n\n[cc-by]: http://creativecommons.org/licenses/by/4.0/\n[cc-by-image]: https://i.creativecommons.org/l/by/4.0/88x31.png\n[cc-by-shield]: https://img.shields.io/badge/License-CC%20BY%204.0-lightgrey.svg\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fddd-crew%2Fdomain-message-flow-modelling","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fddd-crew%2Fdomain-message-flow-modelling","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fddd-crew%2Fdomain-message-flow-modelling/lists"}