├── .github ├── ISSUE_TEMPLATE │ ├── bug-report.yml │ └── feature-request.yml ├── dependabot.yml └── workflows │ └── links-watcher-cron.yml ├── .lycheeignore ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── CONTRIBUTING_USING_GENAI.md ├── LICENSE ├── LICENSES └── Apache-2.0.txt ├── README.md ├── REUSE.toml ├── blog ├── 0001-ddd-introduction.md ├── 0002-core-concepts.md ├── 0003-how-to-model-aggregates.md ├── 0004-how-to-develop-aggregates.md ├── 0005-how-to-get-from-event-storming-to-user-stories.md └── images │ ├── .gitkeep │ └── part_of_BC.png ├── ddd-kata.md ├── detailedinfo ├── domainmessageflow.md ├── eventstorming.md └── images │ ├── .gitkeep │ ├── Restaurant DDD Kata Example Grammar.png │ ├── Restaurant DDD Kata Example_Chaotic_Exploration.png │ ├── Restaurant DDD Kata Example_DMF.png │ ├── Restaurant DDD Kata Example_Detailed_Design_I.png │ ├── Restaurant DDD Kata Example_Detailed_Design_II.png.png │ ├── Restaurant DDD Kata Example_Detailed_Design_III.png.png │ ├── Restaurant DDD Kata Example_Detailed_Design_IV.png │ ├── Restaurant DDD Kata Example_Enforce_Consistency.png │ ├── Restaurant DDD Kata Example_Enforce_Timeline.png │ └── Restaurant DDD Kata Example_Identify_Bounded_Contexts.png ├── images ├── ddd-starter-modelling-process-colored.png ├── ddd-starter-selected-tools.png ├── team-setup.png └── timeline-proposal.png └── knowledgebase ├── concepts ├── additional-concepts │ ├── antipatterns.md │ └── collaborativemodelling.md ├── architectual-concepts │ ├── architecture-modernization.md │ ├── cqrs.md │ ├── eda.md │ ├── event-sourcing.md │ ├── modular-monolith.md │ └── msa.md ├── best-practises │ ├── aligmentbusiness.md │ ├── bcsmallfocused.md │ ├── crossfunctionalteams.md │ ├── ddd-modelling-process.md │ ├── encapsulation.md │ ├── evolution.md │ ├── images │ │ └── ddd-starter-modeling-circular.svg │ ├── interfaces.md │ ├── responsibilities.md │ ├── robustdocument.md │ └── stranglerfigpattern.md ├── strategic-concepts │ ├── boundedcontext.md │ ├── domain.md │ └── ubiquitouslanguage.md └── tactical-concepts │ ├── aggregate.md │ ├── application-services.md │ ├── domain-events.md │ ├── domain-services.md │ ├── entities.md │ ├── factories.md │ ├── images │ ├── Aggregate Testing.png │ ├── Aggregates Roots.png │ ├── Aggregates and Boundaries.png │ ├── Aggregates.png │ ├── Best Practises.png │ ├── Domain Invariants.png │ └── Implementation.png │ ├── modules.md │ ├── repositories.md │ └── value-objects.md ├── index.md └── tools ├── bigpictureeventstorming.md ├── contextmapping.md ├── domain-message-flow.md ├── eventmodelling.md ├── eventstorming.md └── images ├── BigPicture EventStorming Example.png ├── BigPictureEventStorming Grammar.png ├── EventStorming Example Grammar.png ├── Restaurant DDD Kata Example Grammar.png ├── Restaurant DDD Kata Example_Chaotic_Exploration.png ├── Restaurant DDD Kata Example_DMF.png ├── Restaurant DDD Kata Example_Detailed_Design_I.png ├── Restaurant DDD Kata Example_Detailed_Design_II.png.png ├── Restaurant DDD Kata Example_Detailed_Design_III.png.png ├── Restaurant DDD Kata Example_Detailed_Design_IV.png ├── Restaurant DDD Kata Example_Enforce_Consistency.png ├── Restaurant DDD Kata Example_Enforce_Timeline.png ├── Restaurant DDD Kata Example_Identify_Bounded_Contexts.png └── messages-and-contents.jpg /.github/ISSUE_TEMPLATE/bug-report.yml: -------------------------------------------------------------------------------- 1 | name: 🐞 Bug 2 | description: File a bug/issue 3 | title: "[BUG] " 4 | labels: [bug] 5 | body: 6 | - type: checkboxes 7 | attributes: 8 | label: Is there an existing issue for this? 9 | description: Please search to see if an issue already exists for the bug you encountered. 10 | options: 11 | - label: I have searched the existing issues 12 | required: true 13 | - type: dropdown 14 | id: level 15 | attributes: 16 | label: Which area of the resources should be enhanced? 17 | options: 18 | - DDD & Event Storming 101 - Let's get things started 19 | - DDD & Event Storming 201 - Give me more 20 | - DDD & Event Storming 301 and beyond - Going all in 21 | - Courses 22 | - DDD and Legacy 23 | - DDD Community 24 | - Further DDD Goodies 25 | validations: 26 | required: true 27 | - type: textarea 28 | attributes: 29 | label: Bug description 30 | description: A concise description of what you've found. 31 | validations: 32 | required: true 33 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/feature-request.yml: -------------------------------------------------------------------------------- 1 | name: 🚀 Feature Request 2 | description: File a Feature Request 3 | title: "[FEATURE REQUEST] <title>" 4 | labels: [enhancement] 5 | body: 6 | - type: dropdown 7 | id: level 8 | attributes: 9 | label: Area of the resources that should be enhanced? 10 | options: 11 | - DDD & Event Storming 101 - Let's get things started 12 | - DDD & Event Storming 201 - Give me more 13 | - DDD & Event Storming 301 and beyond - Going all in 14 | - Courses 15 | - DDD and Legacy 16 | - DDD Community 17 | - Further DDD Goodies 18 | validations: 19 | required: true 20 | - type: input 21 | attributes: 22 | label: Link to resource 23 | description: Put here the link to the resource you would like to see as part of the repository. 24 | validations: 25 | required: true 26 | - type: textarea 27 | attributes: 28 | label: Description 29 | description: Describe why you think that this resource provides additional value for a DDD learner. 30 | validations: 31 | required: true 32 | -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | # To get started with Dependabot version updates, you'll need to specify which 2 | # package ecosystems to update and where the package manifests are located. 3 | # Please see the documentation for all configuration options: 4 | # https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates 5 | 6 | version: 2 7 | updates: 8 | 9 | - package-ecosystem: "github-actions" 10 | directory: "/" 11 | schedule: 12 | # Check for updates to GitHub Actions every weekday 13 | interval: "weekly" 14 | day: "monday" 15 | -------------------------------------------------------------------------------- /.github/workflows/links-watcher-cron.yml: -------------------------------------------------------------------------------- 1 | name: Periodic Link Checker 2 | 3 | on: 4 | schedule: 5 | - cron: "0 0 * * *" 6 | workflow_dispatch: 7 | 8 | permissions: 9 | contents: read 10 | pull-requests: write 11 | issues: write 12 | 13 | jobs: 14 | link-checker: 15 | runs-on: ubuntu-latest 16 | steps: 17 | - name: "Checkout source code" 18 | uses: actions/checkout@v4 19 | - name: Link Checker 20 | id: lychee 21 | uses: lycheeverse/lychee-action@v2.4.1 22 | with: 23 | args: --verbose --no-progress --exclude-loopback . 24 | output: ./lychee/out.md 25 | fail: true 26 | env: 27 | GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} 28 | - name: Find existing issue 29 | id: find_issue 30 | uses: micalevisk/last-issue-action@v2 31 | if: failure() 32 | with: 33 | state: open 34 | labels: | 35 | broken link 36 | automated issue 37 | - name: Create or update issue for broken links 38 | id: create_issue 39 | uses: peter-evans/create-issue-from-file@v5 40 | if: failure() 41 | with: 42 | title: Link Checker Report 43 | # If issue number is empty a new issue gets created 44 | issue-number: ${{ steps.find_issue.outputs.issue-number }} 45 | content-filepath: ./lychee/out.md 46 | labels: broken link, automated issue -------------------------------------------------------------------------------- /.lycheeignore: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/.lycheeignore -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Contributor Covenant Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | We as members, contributors, and leaders pledge to make participation in our 6 | community a harassment-free experience for everyone, regardless of age, body 7 | size, visible or invisible disability, ethnicity, sex characteristics, gender 8 | identity and expression, level of experience, education, socio-economic status, 9 | nationality, personal appearance, race, caste, color, religion, or sexual 10 | identity and orientation. 11 | 12 | We pledge to act and interact in ways that contribute to an open, welcoming, 13 | diverse, inclusive, and healthy community. 14 | 15 | ## Our Standards 16 | 17 | Examples of behavior that contributes to a positive environment for our 18 | community include: 19 | 20 | * Demonstrating empathy and kindness toward other people 21 | * Being respectful of differing opinions, viewpoints, and experiences 22 | * Giving and gracefully accepting constructive feedback 23 | * Accepting responsibility and apologizing to those affected by our mistakes, 24 | and learning from the experience 25 | * Focusing on what is best not just for us as individuals, but for the overall 26 | community 27 | 28 | Examples of unacceptable behavior include: 29 | 30 | * The use of sexualized language or imagery, and sexual attention or advances of 31 | any kind 32 | * Trolling, insulting or derogatory comments, and personal or political attacks 33 | * Public or private harassment 34 | * Publishing others' private information, such as a physical or email address, 35 | without their explicit permission 36 | * Other conduct which could reasonably be considered inappropriate in a 37 | professional setting 38 | 39 | ## Enforcement Responsibilities 40 | 41 | Community leaders are responsible for clarifying and enforcing our standards of 42 | acceptable behavior and will take appropriate and fair corrective action in 43 | response to any behavior that they deem inappropriate, threatening, offensive, 44 | or harmful. 45 | 46 | Community leaders have the right and responsibility to remove, edit, or reject 47 | comments, commits, code, wiki edits, issues, and other contributions that are 48 | not aligned to this Code of Conduct, and will communicate reasons for moderation 49 | decisions when appropriate. 50 | 51 | ## Scope 52 | 53 | This Code of Conduct applies within all community spaces, and also applies when 54 | an individual is officially representing the community in public spaces. 55 | Examples of representing our community include using an official e-mail address, 56 | posting via an official social media account, or acting as an appointed 57 | representative at an online or offline event. 58 | 59 | ## Enforcement 60 | 61 | Instances of abusive, harassing, or otherwise unacceptable behavior may be 62 | reported to the community leaders responsible for enforcement at 63 | [INSERT CONTACT METHOD]. 64 | All complaints will be reviewed and investigated promptly and fairly. 65 | 66 | All community leaders are obligated to respect the privacy and security of the 67 | reporter of any incident. 68 | 69 | ## Enforcement Guidelines 70 | 71 | Community leaders will follow these Community Impact Guidelines in determining 72 | the consequences for any action they deem in violation of this Code of Conduct: 73 | 74 | ### 1. Correction 75 | 76 | **Community Impact**: Use of inappropriate language or other behavior deemed 77 | unprofessional or unwelcome in the community. 78 | 79 | **Consequence**: A private, written warning from community leaders, providing 80 | clarity around the nature of the violation and an explanation of why the 81 | behavior was inappropriate. A public apology may be requested. 82 | 83 | ### 2. Warning 84 | 85 | **Community Impact**: A violation through a single incident or series of 86 | actions. 87 | 88 | **Consequence**: A warning with consequences for continued behavior. No 89 | interaction with the people involved, including unsolicited interaction with 90 | those enforcing the Code of Conduct, for a specified period of time. This 91 | includes avoiding interactions in community spaces as well as external channels 92 | like social media. Violating these terms may lead to a temporary or permanent 93 | ban. 94 | 95 | ### 3. Temporary Ban 96 | 97 | **Community Impact**: A serious violation of community standards, including 98 | sustained inappropriate behavior. 99 | 100 | **Consequence**: A temporary ban from any sort of interaction or public 101 | communication with the community for a specified period of time. No public or 102 | private interaction with the people involved, including unsolicited interaction 103 | with those enforcing the Code of Conduct, is allowed during this period. 104 | Violating these terms may lead to a permanent ban. 105 | 106 | ### 4. Permanent Ban 107 | 108 | **Community Impact**: Demonstrating a pattern of violation of community 109 | standards, including sustained inappropriate behavior, harassment of an 110 | individual, or aggression toward or disparagement of classes of individuals. 111 | 112 | **Consequence**: A permanent ban from any sort of public interaction within the 113 | community. 114 | 115 | ## Attribution 116 | 117 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], 118 | version 2.1, available at 119 | [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. 120 | 121 | Community Impact Guidelines were inspired by 122 | [Mozilla's code of conduct enforcement ladder][Mozilla CoC]. 123 | 124 | For answers to common questions about this code of conduct, see the FAQ at 125 | [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at 126 | [https://www.contributor-covenant.org/translations][translations]. 127 | 128 | [homepage]: https://www.contributor-covenant.org 129 | [v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html 130 | [Mozilla CoC]: https://github.com/mozilla/diversity 131 | [FAQ]: https://www.contributor-covenant.org/faq 132 | [translations]: https://www.contributor-covenant.org/translations 133 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing to an SAP Open Source Project 2 | 3 | ## General Remarks 4 | 5 | You are welcome to contribute content (code, documentation etc.) to this open source project. 6 | 7 | There are some important things to know: 8 | 9 | 1. You must **comply to the license of this project**, **accept the Developer Certificate of Origin** (see below) before being able to contribute. The acknowledgement to the DCO will usually be requested from you as part of your first pull request to this project. 10 | 2. Please **adhere to our [Code of Conduct](CODE_OF_CONDUCT.md)**. 11 | 3. If you plan to use **generative AI for your contribution**, please see our guideline below. 12 | 4. **Not all proposed contributions can be accepted**. Some features may fit another project better or doesn't fit the general direction of this project. Of course, this doesn't apply to most bug fixes, but a major feature implementation for instance needs to be discussed with one of the maintainers first. Possibly, one who touched the related code or module recently. The more effort you invest, the better you should clarify in advance whether the contribution will match the project's direction. The best way would be to just open an issue to discuss the feature you plan to implement (make it clear that you intend to contribute). We will then forward the proposal to the respective code owner. This avoids disappointment. 13 | 14 | ## Developer Certificate of Origin (DCO) 15 | 16 | Contributors will be asked to accept a DCO before they submit the first pull request to this projects, this happens in an automated fashion during the submission process. SAP uses [the standard DCO text of the Linux Foundation](https://developercertificate.org/). 17 | 18 | ## Contributing with AI-generated code 19 | 20 | As artificial intelligence evolves, AI-generated code is becoming valuable for many software projects, including open-source initiatives. While we recognize the potential benefits of incorporating AI-generated content into our open-source projects there a certain requirements that need to be reflected and adhered to when making contributions. 21 | 22 | Please see our [guideline for AI-generated code contributions to SAP Open Source Software Projects](CONTRIBUTING_USING_GENAI.md) for these requirements. 23 | 24 | ## How to Contribute 25 | 26 | 1. Make sure the change is welcome (see [General Remarks](#general-remarks)). 27 | 2. Create a branch by forking the repository and apply your change. 28 | 3. Commit and push your change on that branch. 29 | 4. Create a pull request in the repository using this branch. 30 | 5. Follow the link posted by the CLA assistant to your pull request and accept it, as described above. 31 | 6. Wait for our code review and approval, possibly enhancing your change on request. 32 | - Note that the maintainers have many duties. So, depending on the required effort for reviewing, testing, and clarification, this may take a while. 33 | 7. Once the change has been approved and merged, we will inform you in a comment. 34 | 8. Celebrate! 35 | -------------------------------------------------------------------------------- /CONTRIBUTING_USING_GENAI.md: -------------------------------------------------------------------------------- 1 | # Guideline for AI-generated code contributions to SAP Open Source Software Projects 2 | 3 | As artificial intelligence evolves, AI-generated code is becoming valuable for many software projects, including open-source initiatives. While we recognize the potential benefits of incorporating AI-generated content into our open-source projects there a certain requirements that need to be reflected and adhered to when making contributions. 4 | 5 | When using AI-generated code contributions in OSS Projects, their usage needs to align with Open-Source Software values and legal requirements. We have established these essential guidelines to help contributors navigate the complexities of using AI tools while maintaining compliance with open-source licenses and the broader [Open-Source Definition](https://opensource.org/osd). 6 | 7 | AI-generated code or content can be contributed to SAP Open Source Software projects if the following conditions are met: 8 | 9 | 1. **Compliance with AI Tool Terms and Conditions**: Contributors must ensure that the AI tool's terms and conditions do not impose any restrictions on the tool's output that conflict with the project's open-source license or intellectual property policies. This includes ensuring that the AI-generated content adheres to the [Open-Source Definition](https://opensource.org/osd). 10 | 2. **Filtering Similar Suggestions**: Contributors must use features provided by AI tools to suppress responses that are similar to third-party materials or flag similarities. We only accept contributions from AI tools with such filtering options. If the AI tool flags any similarities, contributors must review and ensure compliance with the licensing terms of such materials before including them in the project. 11 | 3. **Management of Third-Party Materials**: If the AI tool's output includes pre-existing copyrighted materials, including open-source code authored or owned by third parties, contributors must verify that they have the necessary permissions from the original owners. This typically involves ensuring that there is an open-source license or public domain declaration that is compatible with the project's licensing policies. Contributors must also provide appropriate notice and attribution for these third-party materials, along with relevant information about the applicable license terms. 12 | 4. **Employer Policies Compliance**: If AI-generated content is contributed in the context of employment, contributors must also adhere to their employer’s policies. This ensures that all contributions are made with proper authorization and respect for relevant corporate guidelines. 13 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright [yyyy] [name of copyright owner] 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /LICENSES/Apache-2.0.txt: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. 10 | 11 | "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. 12 | 13 | "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. 14 | 15 | "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. 16 | 17 | "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. 18 | 19 | "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. 20 | 21 | "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). 22 | 23 | "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. 24 | 25 | "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." 26 | 27 | "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 28 | 29 | 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 30 | 31 | 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 32 | 33 | 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: 34 | 35 | (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and 36 | 37 | (b) You must cause any modified files to carry prominent notices stating that You changed the files; and 38 | 39 | (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and 40 | 41 | (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. 42 | 43 | You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 44 | 45 | 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 46 | 47 | 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 48 | 49 | 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 50 | 51 | 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 52 | 53 | 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. 54 | 55 | END OF TERMS AND CONDITIONS 56 | 57 | APPENDIX: How to apply the Apache License to your work. 58 | 59 | To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. 60 | 61 | Copyright [yyyy] [name of copyright owner] 62 | 63 | Licensed under the Apache License, Version 2.0 (the "License"); 64 | you may not use this file except in compliance with the License. 65 | You may obtain a copy of the License at 66 | 67 | http://www.apache.org/licenses/LICENSE-2.0 68 | 69 | Unless required by applicable law or agreed to in writing, software 70 | distributed under the License is distributed on an "AS IS" BASIS, 71 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 72 | See the License for the specific language governing permissions and 73 | limitations under the License. 74 | -------------------------------------------------------------------------------- /REUSE.toml: -------------------------------------------------------------------------------- 1 | version = 1 2 | SPDX-PackageName = "curated-resources-for-domain-driven-design" 3 | SPDX-PackageSupplier = "christian.lechner@sap.com" 4 | SPDX-PackageDownloadLocation = "<https://github.com/sap/curated-resources-for-domain-driven-design>" 5 | SPDX-PackageComment = "The code in this project may include calls to APIs (\"API Calls\") of\n SAP or third-party products or services developed outside of this project\n (\"External Products\").\n \"APIs\" means application programming interfaces, as well as their respective\n specifications and implementing code that allows software to communicate with\n other software.\n API Calls to External Products are not licensed under the open source license\n that governs this project. The use of such API Calls and related External\n Products are subject to applicable additional agreements with the relevant\n provider of the External Products. In no event shall the open source license\n that governs this project grant any rights in or to any External Products,or\n alter, expand or supersede any terms of the applicable additional agreements.\n If you have a valid license agreement with SAP for the use of a particular SAP\n External Product, then you may make use of any API Calls included in this\n project's code for that SAP External Product, subject to the terms of such\n license agreement. If you do not have a valid license agreement for the use of\n a particular SAP External Product, then you may only make use of any API Calls\n in this project for that SAP External Product for your internal, non-productive\n and non-commercial test and evaluation of such API Calls. Nothing herein grants\n you any rights to use or access any SAP External Product, or provide any third\n parties the right to use of access any SAP External Product, through API Calls." 6 | 7 | [[annotations]] 8 | path = "**" 9 | precedence = "aggregate" 10 | SPDX-FileCopyrightText = "2022 SAP SE or an SAP affiliate company and curated-resources-for-domain-driven-design contributors" 11 | SPDX-License-Identifier = "Apache-2.0" 12 | -------------------------------------------------------------------------------- /blog/0001-ddd-introduction.md: -------------------------------------------------------------------------------- 1 | # An Introduction to Domain-Driven Design 2 | 3 | You’ve undoubtedly heard the phrase “Domain-Driven Design” (DDD) thrown around a lot recently as a software development architect. You might be pondering what it is and why it is gaining popularity in business. So, in this blog post, we’ll introduce you to Domain-Driven Design, describe its advantages, and show you how it can help teams create better software. First, let us describe the term "domain". A domain in software development describes a particular area or subject matter that a system is designed to address. If you were creating an e-commerce system, the domain would be "e-commerce". The domain is significant because it sets the system’s needs as well as the business principles that govern it. 4 | 5 | DDD puts the domain at the heart of the creative process. This indicates that figuring out the domain and modeling it in the software is the primary goal. Instead of forcing the business to conform to the constraints of the software, the objective is to develop a software system that represents the business area. 6 | 7 | One of the major advantages of DDD is that it aids in improving software development by fostering a common grasp of the domain. The development team can better grasp the business requirements and make sure the software satisfies those needs by involving subject specialists in the process. This should result in better software that is simpler to maintain and expand over time. 8 | 9 | DDD also aids teams in decomposing complicated systems into smaller, easier-to-manage components. This is accomplished through the idea of "bounded contexts," which are autonomous elements of the system with a clearly specified limit and well-defined interfaces for interacting with other contexts. Teams can escape the “big ball of mud” issue, where the system becomes too complicated to comprehend and manage, by using bound contexts. 10 | 11 | Another crucial aspect is that a “[Ubiquitous language](https://martinfowler.com/bliki/UbiquitousLanguage.html)” is defined and used by both coders and subject specialists as part of the DDD practice. The software will more closely represent the business domain as a result of everyone having a shared knowledge of the domain. 12 | 13 | Finally, DDD is a software design discipline that puts the domain at the center of the design process. By fostering a common understanding of the subject and decomposing complicated systems into simpler, more manageable components, it aids teams in producing better software. Understanding fundamental ideas like aggregates and bounded contexts, as well as ubiquitous language and other significant words and concepts, is crucial to getting started with DDD. So why not give it a shot and see if it can help in the development of improved software by you and your team? 14 | 15 | If you want start learning about DDD we can recommend the following books: 16 | 17 | 1. “Domain-Driven Design: Tackling Complexity in the Heart of Software” by Eric Evans 18 | 19 | 2. “Implementing Domain-Driven Design” by Vaughn Vernon 20 | 21 | 3. “Learning Domain-Driven Design” by Vlad Khononov 22 | 23 | 4. “Domain-Driven Design Distilled” by Vaughn Vernon 24 | 25 | Sources: 26 | 27 | (1) [11 Best Domain-Driven Design Books in 2023](https://realtoughcandy.com/domain-driven-design-books/) 28 | 29 | (2) [Learning Domain-Driven Design](https://www.oreilly.com/library/view/learning-domain-driven-design/9781098100124/) 30 | 31 | (3) [Domain Driven Design: A Comprehensive Beginner’s Guide to Learn](https://books.google.de/books/about/Domain_Driven_Design.html?id=q7OazAEACAAJ&redir_esc=y) 32 | -------------------------------------------------------------------------------- /blog/0003-how-to-model-aggregates.md: -------------------------------------------------------------------------------- 1 | # Aggregates: How to Model Complex Domains with Consistency and Cohesion 2 | 3 | ## Introduction 4 | 5 | Domain-Driven Design (DDD) places more emphasis on conceptual modeling of the issue domain than it does on implementation and technical specifics. 6 | The business logic and domain rules are captured in expressive, consistent, and coherent domain models. 7 | 8 | The aggregate is a collection of domain objects that is handled as a single unit. 9 | It is one of the essential (tactical) patterns in DDD. 10 | This blog article will explain what aggregates are and how to discover them. 11 | We present an example how you can implement an aggregate in [the next article](0004-how-to-develop-aggregates.md). 12 | 13 | ## What Are Domain Invariants, and Why Do They Matter? 14 | 15 | The business rules and restrictions that must always apply in the domain are known as domain invariants. 16 | They reflect the domain's fundamental logic and presumptions, ensuring the accuracy and integrity of the domain model and the data. 17 | For instance, a domain invariant in the banking domain may be that a bank account's balance may not be negative. 18 | Or, in e-commerce, there may be the invariant that an order cannot have a negative total amount. 19 | 20 | Domain invariants are significant, since they help in defining the boundaries and behaviors of the domain objects and aggregates. 21 | Also, they help us to prevent our system from entering faulty or inconsistent states. 22 | Any action that would contradict, for instance, the domain invariant that an order cannot have a negative total amount should be blocked or rejected by the order aggregate. 23 | 24 | The expression of domain invariants can take many forms, including preconditions, postconditions, assertions, validations, exceptions, etc. 25 | Making them clear and enforcing them inside the domain model is crucial. 26 | Depending on the degree of consistency and performance demanded by the domain, domain invariants may also differ in their extent and amount of detail. 27 | While certain domain invariants may only apply to a single entity or value object, others may span an entire aggregate or even several aggregates. 28 | It is important to figure out which invariants are truly invariant, i.e. must never be violated, and for which invariants temporal inconsistencies can be tolerated by the business. 29 | If an invariant may never be violated, we must protect it with an aggregate. 30 | Otherwise, we can use domain events to communicate state changes between aggregates and live with the system being eventually consistent. 31 | 32 | ## How to Discover Aggregates and Their Limits? 33 | 34 | One of the hardest and most crucial jobs in DDD is identifying aggregates and their bounds. 35 | Aggregates are significant clusters of domain items that change collectively and provide a consistency boundary, not merely random groupings of domain objects. 36 | Aggregates should be built to safeguard and enforce domain invariants while allowing for eventual or asynchronous consistency of other aggregates. 37 | 38 | There are different techniques and heuristics that can help to identify aggregates and their boundaries. 39 | 40 | Using the ubiquitous language and the domain experts' knowledge to identify the main concepts and relationships in the domain. 41 | The ubiquitous language is the common and expressive language that is used by the domain experts and the developers to communicate about the domain. 42 | It can help to discover the nouns and verbs of the domain, which can be mapped to entities, value objects, and behaviors. 43 | Domain experts can also provide valuable insights and feedback on how the domain works and what are the important rules and constraints. 44 | 45 | Identifying the interactions and behaviors of domain objects using scenarios and use cases. 46 | Use cases and scenarios both describe how domain objects work together to complete a task or deal with a problem. 47 | The people, activities, inputs, outputs, and consequences of the domain may be identified with the use of scenarios and use cases. 48 | Also, they can aid in locating the causal and temporal relationships between domain items, which may point to prospective aggregates. 49 | 50 | Finding groups of domain objects that change collectively and build aggregates using domain invariants. 51 | The business laws and restrictions that must always apply in the domain are known as domain invariants. 52 | By assembling domain objects that have common invariants and must always be consistent, domain invariants can aid in the identification of aggregates. 53 | For instance, if a domain invariant of an order states that it cannot have a negative total amount, then all of the order's line items must be a part of the same aggregate. 54 | 55 | Reducing the complexity and size of aggregates using qualifiers and restrictions. 56 | Additional criteria or conditions, like constraints and qualifiers, can be used to restrict or filter the associations between domain items. 57 | By removing pointless or superfluous linkages or dependencies, qualifiers and constraints can aid in reducing the complexity and size of aggregates. 58 | A qualifier like "active" might be used to lower the size of the team aggregate, for instance, if a team has numerous staff members affiliated with it but only part of them are active at any one moment. 59 | 60 | Using these techniques and heuristics, we may find aggregates and their limitations in a variety of domains. 61 | Yet, since aggregates and their bounds depend on the circumstances and requirements of each domain, there is no precise or standardized way to identify them. 62 | Thus it's essential to test out several designs and evaluate them based on things like expressiveness, consistency, performance, scalability, etc. 63 | 64 | ## How to Design Aggregates and Their Roots? 65 | 66 | Each aggregate has a single, designated root entity. 67 | The aggregate root is responsible for encapsulating the aggregate's state and behavior, and ensuring its consistency and validity. 68 | That means that the domain model should make it impossible to modify an aggregate's state except via the public API exposed by the aggregate. 69 | Aggregates can only be referenced to by the identity of the aggregate root. 70 | 71 | The aggregate root's interface and methods should reflect the language and domain concepts, follow the principle of least astonishment, and the command-query separation principle. 72 | Relationships with other aggregates should be modelled using references or identifiers. 73 | References or identifiers are simple values that represent the identity of another aggregate, without exposing its internal structure or state. 74 | 75 | Other criteria like expressiveness, consistency, performance, scalability, etc. can be relevant for aggregate design, but are beyond the scope of this blog post. 76 | 77 | ## Conclusion 78 | 79 | Aggregates are groups of domain objects that can be handled as a single entity and can protect and enforce the domain invariants. 80 | They are designed using the ubiquitous language, the ideas and laws of the domain, the scenarios and use cases, and the domain invariants. 81 | They can help build expressive, coherent domain models, reduce complexity, and improve efficiency. 82 | 83 | ## Further References and Resources 84 | 85 | - Books: 86 | - Domain-Driven Design: Tackling Complexity in the Heart of Software by Eric Evans 87 | - Implementing Domain-Driven Design by Vaughn Vernon 88 | - Domain-Driven Design Reference by Eric Evans 89 | - Domain-Driven Design Distilled by Vaughn Vernon 90 | - Blogs 91 | - <https://www.jamesmichaelhickey.com/domain-driven-design-aggregates/> 92 | - <https://dzone.com/articles/domain-driven-design-aggregate> 93 | - <https://www.martinfowler.com/bliki/DDD_Aggregate.html> 94 | - Youtube 95 | - Vaughn Vernon - How to Use Aggregates for Tactical Design: <https://www.youtube.com/watch?v=Xf_aLAK1RfE> 96 | - Vaughn Version - Effective Aggregate Design Part II: <https://www.youtube.com/watch?v=JOsv01y8dlw> 97 | - Thomas Ploch: The One Question To Haunt Everyone: What is a DDD Aggregate? - Thomas Ploch - DDD Europe 2022: <https://www.youtube.com/watch?v=zlFqjD2LKlE> 98 | - Codewrinkles: M****ing DDD Aggregate Modeling With THESE 3 Steps: <https://www.youtube.com/watch?v=E2ctgrKhqBw> 99 | - Amichai Mantinband: Aggregates, Entities & Value Objects | Modeling Rules of Thumb + Modeling Steps: <https://www.youtube.com/watch?v=UEtmOW8uZZY> 100 | - Milan Jovanović: Aggregate Root Design 101 | DDD, Clean Architecture, .NET 6 - <https://www.youtube.com/watch?v=0D3EB2jvQ44> 101 | -------------------------------------------------------------------------------- /blog/0005-how-to-get-from-event-storming-to-user-stories.md: -------------------------------------------------------------------------------- 1 | # From Event Storming to User Stories and beyond 2 | 3 | This Blog describes how Event Storming results can be translated into user stories and how these user stories can then be used as a starting point to create your domain model. 4 | 5 | ## Event Storming 6 | 7 | Event Storming, developed by Alberto Brandolini, is a great methodology to translate complex business requirements into actionable tasks. 8 | 9 | Event Storming is executed in a collaborative workshop that bring together ALL steak holders to share their business perspective to create a shared understanding of the whole business. 10 | 11 | As a result of an event storming workshop, the business domain is captured visually in bounded contexts with process flows, containing aggregates and domain events. 12 | In detail: 13 | 14 | 1. *Domain Events* 15 | Key occurrences that change the state of the system. 16 | 2. *Commands* 17 | Actions triggered by users or systems that cause domain events. 18 | 3. *Aggregates* 19 | Collections of related objects that ensure consistency within the domain. 20 | 4. *Read Models* 21 | Views that represent the data to be read by users. 22 | 5. *Bounded Contexts* 23 | Distinct areas within a domain where particular models are valid. 24 | 25 | An example Bounded Context **Reservation** as part of a larger Event Storming Event is shown below. 26 | 27 | 28 | ## Transition Event Storming results into user stories 29 | 30 | Once the Event Storming session has provided a clear understanding of the domain, the next step is to translate this knowledge into user stories. User stories are concise, simple descriptions of a feature or function. 31 | 32 | In the first step **identify Key Events and Actor** 33 | - Review the domain events and actors identified during the Event Storming session. 34 | - Determine which events are crucial from a user’s perspective. 35 | 36 | The second step is to **Define User Goals** 37 | - For each key event, ask what goal the user is trying to achieve. 38 | - Use the format: “As a [type of user], I want [an action] so that [a benefit].” 39 | 40 | Next: **Detail out Acceptance Criteria** 41 | - Define clear, testable conditions that must be met for the user story to be considered complete. 42 | - This ensures the development team knows exactly what is expected. 43 | 44 | Finally **prioritize User Stories** 45 | - Work with stakeholders to prioritize user stories based on business value and complexity. 46 | - Use techniques such as MoSCoW (Must have, Should have, Could have, and Won't have) to classify stories. 47 | 48 | ## Let’s take an example: 49 | 50 | Consider a café that offers a reservation service on their web site: 51 | 52 | ![](images/part_of_BC.png) 53 | 54 | 1. Identify Key Events and Actor 55 | 56 | Image, you as the potential customer want to reserve a table in the café. Your requirements are: 57 | - Table for three persons 58 | - Next Monday afternoon at 2 p.m. 59 | 60 | You go to the website of the café and navigate to the reservation page. 61 | > [command] “Request Reservation” 62 | 63 | A form is offered where you can put the necessary data, like your name, your email address and the reservation date/time and the number of persons. When you press the submit/send button you trigger 64 | > [event] “Reservation requested” 65 | 66 | The system is now working on this request by querying a view or read model 67 | > [read model]“reserved tables”. 68 | 69 | If [policy/decision]requested-table is available, the system will reserve the table 70 | If [policy/decision]requested-table is not available, the system will propose available tables for a “different” date. 71 | 72 | 2. Define User Goals 73 | 74 | The command is now translated into a user story with the following pattern: 75 | > As a [type of user], I want [an action] so that [a benefit]. 76 | > As a [customer], I want [to enter my data] so that [the system can reserve a table for me and my family] 77 | 78 | 3. Detail out Acceptance Criteria 79 | 80 | Acceptance Criteria are the rules that keep your aggregate (Reservation) consistent. Write a test case for every rule by detailing the rule (finding the invariant) to ensure consistency: 81 | - The system offers fields for necessary data. 82 | - Name and Email address are mandatory 83 | - Date and time are mandatory too 84 | - The system validates input data 85 | - Email address needs ‘.’ before and after ‘@’ 86 | - Reservation date and time when the café is open 87 | - Latest reservation time one hour before closing 88 | 89 | 90 | 91 | *helper.py* 92 | ``` 93 | import datetime 94 | 95 | weekDays = { 96 | 'Monday' : 1, 97 | 'Tuesday' : 2, 98 | 'Wednesday' : 3, 99 | 'Thursday' : 4, 100 | 'Friday' : 5, 101 | 'Saturday' : 6, 102 | 'Sunday' : 7 103 | } 104 | 105 | def get_weekday_as_number(timeStr): 106 | return weekDays[get_weekday(timeStr)] 107 | 108 | def get_weekday(timeStr): 109 | d = datetime.datetime.strptime(timeStr, '%Y-%m-%d') 110 | return d.strftime('%A') 111 | 112 | def decrease_by_one_hour(timeString): 113 | # assumed input format 'hh:mm' 114 | minutes = int(timeString.split(':')[0])*60+int(timeString.split(':')[1]) - 60 115 | return '%02d:%02d' % (minutes//60, minutes%60) 116 | ``` 117 | 118 | *model.py* 119 | ``` 120 | openingTimes = { 121 | 'Tuesday': ('09:00', '19:00'), 122 | 'Wednesday':('09:00', '13:00'), 123 | 'Thursday': ('09:00', '19:00'), 124 | 'Friday': ('09:00', '19:00'), 125 | 'Saturday': ('09:00', '19:00'), 126 | 'Sunday': ('13:00', '19:00') 127 | } 128 | 129 | class Reservation(): 130 | pass 131 | ``` 132 | 133 | 134 | *test_reservation.py* 135 | ``` 136 | import unittest 137 | import helper 138 | import model 139 | 140 | class TestReservation(unittest.TestCase): 141 | 142 | def setUp(self): 143 | self.reservation = model.Reservation() 144 | self.reservation.name = 'Thomas Muster' 145 | self.reservation.email = 'thomas.muster@sap.com' 146 | self.reservation.date = '2024-07-12' 147 | self.reservation.time = '15:00' 148 | self.reservation.number_of_persons = 3 149 | 150 | def test_date_during_open_days(self): 151 | openingDays = [1,2,3,4,5,7] 152 | self.assertTrue(helper.get_weekday_as_number(self.reservation.date) in openingDays) 153 | 154 | def test_date_not_during_open_days(self): 155 | openingDays = [1,2,3,4,6,7] 156 | self.assertFalse(helper.get_weekday_as_number(self.reservation.date) in openingDays) 157 | 158 | def test_time_during_open_hours(self): 159 | openingHours = ('09:00', '18:00') 160 | self.assertTrue(openingHours[0] <= self.reservation.time <= openingHours[1]) 161 | 162 | def test_time_not_during_open_hours(self): 163 | openingHours = ('09:00', '14:00') 164 | self.assertFalse(openingHours[0] <= self.reservation.time <= openingHours[1]) 165 | 166 | def test_time_date_during_opening(self): 167 | weekday = helper.get_weekday(self.reservation.date) 168 | openThatDay = model.openingTimes[weekday] 169 | self.assertTrue(weekday in model.openingTimes.keys() and 170 | openThatDay[0] <= self.reservation.time <= openThatDay[1]) 171 | 172 | def test_time_date_not_during_opening_1(self): 173 | self.reservation.time = '08:00' 174 | weekday = helper.get_weekday(self.reservation.date) 175 | openThatDay = model.openingTimes[weekday] 176 | self.assertFalse(weekday in model.openingTimes.keys() and 177 | openThatDay[0] <= self.reservation.time <= openThatDay[1]) 178 | 179 | def test_time_date_not_during_opening_2(self): 180 | self.reservation.date = '2024-07-08' 181 | weekday = helper.get_weekday(self.reservation.date) 182 | with self.assertRaises(KeyError): 183 | model.openingTimes[weekday] 184 | 185 | def test_60_minutes_before_closing_works(self): 186 | self.reservation.time = '18:00' 187 | weekday = helper.get_weekday(self.reservation.date) 188 | openToday = model.openingTimes[weekday] 189 | latest_reservation = helper.decrease_by_one_hour(openToday[1]) 190 | self.assertTrue(weekday in model.openingTimes.keys() and 191 | openToday[0] <= self.reservation.time <= latest_reservation) 192 | 193 | def test_30_minutes_before_closing_fails(self): 194 | self.reservation.time = '18:31' 195 | weekday = helper.get_weekday(self.reservation.date) 196 | openToday = model.openingTimes[weekday] 197 | latest_reservation = helper.decrease_by_one_hour(openToday[1]) 198 | self.assertFalse(weekday in model.openingTimes.keys() and 199 | openToday[0] <= self.reservation.time <= latest_reservation) 200 | ``` 201 | 202 | 203 | 4. Prioritize User Stories 204 | 205 | Prioritization is important to work on those stories first that bring the highest value to the customer and/or are a dependencies for other stories. 206 | 207 | ## SUMMARY 208 | 209 | Transitioning from Event Storming to user stories bridges the gap between high-level domain understanding and actionable development tasks. By following a structured approach, teams can ensure that they capture the essence of business requirements and translate them into features that deliver real value to users. 210 | 211 | -------------------------------------------------------------------------------- /blog/images/.gitkeep: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/blog/images/.gitkeep -------------------------------------------------------------------------------- /blog/images/part_of_BC.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/blog/images/part_of_BC.png -------------------------------------------------------------------------------- /detailedinfo/domainmessageflow.md: -------------------------------------------------------------------------------- 1 | # Domain Message Flow 2 | 3 | Content moved to [here](../knowledgebase/tools/domain-message-flow.md) 4 | -------------------------------------------------------------------------------- /detailedinfo/eventstorming.md: -------------------------------------------------------------------------------- 1 | # Event Storming 2 | 3 | Content has be moved to **[here](../knowledgebase/tools/eventstorming.md)**. 4 | -------------------------------------------------------------------------------- /detailedinfo/images/.gitkeep: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/detailedinfo/images/.gitkeep -------------------------------------------------------------------------------- /detailedinfo/images/Restaurant DDD Kata Example Grammar.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/detailedinfo/images/Restaurant DDD Kata Example Grammar.png -------------------------------------------------------------------------------- /detailedinfo/images/Restaurant DDD Kata Example_Chaotic_Exploration.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/detailedinfo/images/Restaurant DDD Kata Example_Chaotic_Exploration.png -------------------------------------------------------------------------------- /detailedinfo/images/Restaurant DDD Kata Example_DMF.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/detailedinfo/images/Restaurant DDD Kata Example_DMF.png -------------------------------------------------------------------------------- /detailedinfo/images/Restaurant DDD Kata Example_Detailed_Design_I.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/detailedinfo/images/Restaurant DDD Kata Example_Detailed_Design_I.png -------------------------------------------------------------------------------- /detailedinfo/images/Restaurant DDD Kata Example_Detailed_Design_II.png.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/detailedinfo/images/Restaurant DDD Kata Example_Detailed_Design_II.png.png -------------------------------------------------------------------------------- /detailedinfo/images/Restaurant DDD Kata Example_Detailed_Design_III.png.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/detailedinfo/images/Restaurant DDD Kata Example_Detailed_Design_III.png.png -------------------------------------------------------------------------------- /detailedinfo/images/Restaurant DDD Kata Example_Detailed_Design_IV.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/detailedinfo/images/Restaurant DDD Kata Example_Detailed_Design_IV.png -------------------------------------------------------------------------------- /detailedinfo/images/Restaurant DDD Kata Example_Enforce_Consistency.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/detailedinfo/images/Restaurant DDD Kata Example_Enforce_Consistency.png -------------------------------------------------------------------------------- /detailedinfo/images/Restaurant DDD Kata Example_Enforce_Timeline.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/detailedinfo/images/Restaurant DDD Kata Example_Enforce_Timeline.png -------------------------------------------------------------------------------- /detailedinfo/images/Restaurant DDD Kata Example_Identify_Bounded_Contexts.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/detailedinfo/images/Restaurant DDD Kata Example_Identify_Bounded_Contexts.png -------------------------------------------------------------------------------- /images/ddd-starter-modelling-process-colored.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/images/ddd-starter-modelling-process-colored.png -------------------------------------------------------------------------------- /images/ddd-starter-selected-tools.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/images/ddd-starter-selected-tools.png -------------------------------------------------------------------------------- /images/team-setup.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/images/team-setup.png -------------------------------------------------------------------------------- /images/timeline-proposal.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/images/timeline-proposal.png -------------------------------------------------------------------------------- /knowledgebase/concepts/additional-concepts/collaborativemodelling.md: -------------------------------------------------------------------------------- 1 | 2 | # **Collaborative Modeling in Software Design** 3 | 4 | Collaborative modeling is a process where all stakeholders involved in a software project, from developers to domain experts, come together to create a shared understanding of the problem and its solution. This approach encourages teams to work visually and interactively, facilitating domain modeling decisions and making informed design choices. 5 | 6 | ## What is Collaborative Modeling? 7 | 8 | Collaborative modeling is about visualizing complex decision-making processes to foster better communication and understanding across different stakeholders. It’s applicable not just in software development but across various industries. However, its utility is most prominent in software, where teams must frequently align on evolving requirements and designs. The goal is to bridge the gap between technical and non-technical participants, ensuring that the design accurately meets business needs. 9 | 10 | ## Key Benefits of Collaborative Modeling 11 | 12 | 1. **Shared Understanding**: Collaborative modeling helps create and maintain a deep understanding of the domain and a shared language across all participants. This is critical in software, where miscommunication often leads to costly rework. 13 | 2. **Alignment on Mental Models**: By involving all stakeholders, teams can ensure that everyone has a consistent understanding of the domain and software’s intended behavior. This alignment reduces misunderstandings and helps the team work more cohesively. 14 | 15 | 3. **Improved Design Decisions**: Directed conversations through visualization tools, such as event storming, make it easier to explore alternatives and gain insights from different perspectives. This broadens the scope of solutions and ensures that design decisions are made based on collective wisdom. 16 | 17 | 4. **Conflict Resolution**: Collaborative modeling brings all stakeholders to the same table. Conflicting ideas can be discussed and resolved transparently, avoiding later friction during implementation. This reduces the risk of siloed decisions, where teams might diverge from the broader architectural vision. 18 | 19 | ## Techniques and Tools for Collaborative Modeling 20 | 21 | 1. **EventStorming**: A workshop-style approach that helps teams visually explore complex processes. This method is particularly useful in understanding end-to-end workflows and in identifying events that occur within a system. 22 | 23 | 2. **Domain Storytelling**: Another visualization technique that involves creating "stories" about how people interact with software systems. This helps domain experts and developers align their perspectives by making implicit knowledge explicit. 24 | 25 | 3. **User Journey Mapping**: Creating a visual map of the user’s interactions with the software allows teams to better understand the user's needs and identify areas for improvement. 26 | 27 | 4. **Process Modeling**: Utilizing tools like flowcharts and sequence diagrams to model system processes helps communicate design decisions clearly. 28 | 29 | ## Who Should Be Involved? 30 | 31 | To achieve a successful collaborative modeling session, all relevant stakeholders should be present: 32 | 33 | - **Developers and Architects**: They bring the technical expertise needed to translate requirements into code. 34 | - **Domain Experts**: They understand the business processes and provide insight into what the software needs to achieve. 35 | - **Product Owners and Business Analysts**: They can connect the technical team to the business strategy and ensure alignment with organizational goals. 36 | - **Facilitator**: A facilitator often plays a crucial role in managing discussions, resolving conflicts, and ensuring all voices are heard. 37 | 38 | ## Challenges in Collaborative Modeling 39 | 40 | 1. **Stakeholder Buy-In**: It can be challenging to get full commitment from all stakeholders, especially those who may not understand the value of these sessions. Without participation from key individuals, it’s difficult to confirm business requirements accurately. 41 | 42 | 2. **Perceived Time Investment**: Collaborative modeling requires pulling multiple people away from their day-to-day tasks for extended periods, which can be seen as a significant time investment without immediate measurable returns. 43 | 44 | 3. **Management Misalignment**: Senior management often has difficulty seeing the long-term value of collaborative modeling due to its intangible results, which can lead to under-prioritizing this step in favor of faster (but less aligned) outputs. 45 | 46 | ## Best Practices for Collaborative Modeling 47 | 48 | 1. **Ensure Active Participation**: It's essential to have everyone, from developers to stakeholders, involved actively in the modeling process. Their contributions are crucial to building a comprehensive model. 49 | 50 | 2. **Facilitate, Don’t Dictate**: The role of the facilitator is to guide conversations, ensure all voices are heard, and resolve conflicts, but not to dictate decisions. Empowering the team is a fundamental principle of effective collaborative modeling. 51 | 52 | 3. **Document Outcomes**: It’s vital to document the session's outcomes, including the agreed model, the context behind decisions, and any remaining uncertainties. This documentation becomes a reference point for future discussions and helps maintain continuity. 53 | 54 | ## Conclusion 55 | 56 | Collaborative modeling is a powerful way to ensure that software development aligns with business needs and stakeholder expectations. It helps build shared understanding, uncover hidden complexities, and create robust domain models that reflect both business and user needs. Successful collaborative modeling leads to well-informed design decisions and improved overall software quality. 57 | 58 | The collaborative modeling journey is not without its challenges. It requires an understanding of social dynamics, commitment from all stakeholders, and effective facilitation. However, the benefits—better alignment, reduced misunderstandings, and a more resilient software design—make it an essential tool for teams looking to create impactful software systems. 59 | 60 | ## Resource 61 | 62 | - "Collaborative Software Design - How to facilitate domain modeling decisions" - Manning - Evelyn van Kelle, Gien Verschatse, and Kenny Baas-Schwegler - 2024 (MEAP) 63 | -------------------------------------------------------------------------------- /knowledgebase/concepts/architectual-concepts/architecture-modernization.md: -------------------------------------------------------------------------------- 1 | # Architecture Modernization 2 | 3 | ## Overview 4 | 5 | Architecture modernization is a transformative journey to convert legacy systems, which can hinder growth, into modern, adaptable, and competitive systems. Beyond technology updates, modernization focuses on aligning architecture with business strategy, organizational structure, and customer needs, fostering innovation and efficiency. 6 | 7 | ## **Drivers for Architecture Modernization** 8 | 9 | Organizations undertake architecture modernization for various reasons. Identifying and articulating these drivers is crucial for gaining stakeholder buy-in: 10 | 11 | 1. **Competitive Pressure**: Legacy systems can hinder agility, leaving organizations vulnerable to faster, more innovative competitors. 12 | 2. **Scalability Issues**: Legacy systems often struggle to support growing business demands and user bases. 13 | 3. **Cost Reduction**: High maintenance costs of legacy systems make modernization a cost-saving measure in the long run. 14 | 4. **Improved User Experience (UX)**: Outdated interfaces and workflows negatively impact user satisfaction and productivity. 15 | 5. **Regulatory Compliance**: Modern architectures simplify adherence to ever-evolving legal and security standards. 16 | 6. **Innovation Enablement**: Legacy systems can block integration with modern technologies like AI, IoT, or microservices. 17 | 18 | ## **Key Principles of Modernization** 19 | 20 | 1. **Holistic Viewpoint**: 21 | - Modernization is not merely a technical overhaul. It involves rethinking domain boundaries, business processes, and team interactions. 22 | - Use models like *Better Value Sooner Safer Happier (BVSSH)* to ensure modernization impacts multiple organizational dimensions positively. 23 | 24 | 2. **Independent Value Streams (IVS)**: 25 | - Align architecture with clearly defined business domains to minimize dependencies. 26 | - Enable small, autonomous teams to focus on business outcomes, reducing change coupling and bottlenecks. 27 | 28 | 3. **Evolutionary, Not Revolutionary**: 29 | - Treat modernization as a continuous journey, delivering incremental value and iterating based on feedback. 30 | - Prioritize high-impact subdomains using tools like Core Domain Charts or the Modernization Strategy Selector. 31 | 32 | ## **Practical Steps to Kickstart Modernization** 33 | 34 | ### **1. Build Organizational Readiness** 35 | 36 | - **Assess Leadership Buy-In**: Ensure leadership understands the trade-offs, including slowing feature delivery temporarily to focus on modernization. 37 | - **Upskill Teams**: Invest in training teams in modern practices such as Domain-Driven Design (DDD), EventStorming, and Team Topologies. 38 | - **Create a Compelling Business Case**: Clearly articulate how modernization will improve outcomes like revenue, user satisfaction, and system reliability. 39 | 40 | ### **2. Map the Current Landscape** 41 | 42 | - Conduct listening tours with stakeholders across the organization to identify pain points. 43 | - Use collaborative techniques like EventStorming to define and refine domain boundaries. 44 | - Apply Wardley Mapping to visualize the evolution of organizational capabilities and identify areas of investment. 45 | 46 | ### **3. Define a Clear Vision** 47 | 48 | - Identify a North Star for modernization efforts—a guiding metric or objective that aligns with strategic ambitions. 49 | - Ensure alignment between architectural goals and business strategy. 50 | 51 | ### **4. Prioritize Efforts** 52 | 53 | - Begin with subdomains that offer the highest business value and lowest complexity. 54 | - Avoid the temptation to rewrite entire systems; instead, apply targeted approaches like encapsulating legacy systems or replatforming components. 55 | 56 | ### **5. Build Momentum with Quick Wins** 57 | 58 | - Deliver tangible improvements in the first 3–6 months to sustain stakeholder interest. 59 | - Establish Architecture Modernization Enabling Teams (AMETs) to guide and support continuous improvement. 60 | 61 | ### **6. Foster Collaboration** 62 | 63 | - Break down silos between technical and business teams by encouraging co-design and joint decision-making. 64 | - Use techniques like Domain Storytelling or EventStorming to create shared understanding and ownership. 65 | 66 | ## **Tips and Tricks for Effective Modernization** 67 | 68 | 1. **Avoid Silver Bullets**: Resist the allure of one-size-fits-all solutions like microservices. Tailor your approach to your organization's unique needs. 69 | 2. **Communicate Early and Often**: Maintain transparency with stakeholders about the goals, challenges, and progress of modernization efforts. 70 | 3. **Invest in Internal Developer Platforms (IDPs)**: Simplify deployment and reduce developer friction by providing tools that enable faster, more reliable delivery. 71 | 4. **Leverage Metrics**: Continuously assess the impact of modernization efforts using metrics such as time-to-market, error rates, and team satisfaction. 72 | 5. **Plan for Continuous Learning**: Encourage a culture of experimentation and learning. This ensures teams stay adaptable and ready for future challenges. 73 | 74 | ## Resources 75 | 76 | [Architecture Modernization by Nick Tune](https://www.manning.com/books/architecture-modernization) 77 | -------------------------------------------------------------------------------- /knowledgebase/concepts/architectual-concepts/cqrs.md: -------------------------------------------------------------------------------- 1 | # Command Query Responsibility Segregation (CQRS) 2 | 3 | **Command Query Responsibility Segregation (CQRS)** is an architectural pattern used to separate the reading of data (queries) from the modification of data (commands). This separation allows for greater flexibility and scalability in distributed systems by decoupling the operational and retrieval models. 4 | 5 | ## Overview of CQRS 6 | 7 | CQRS splits an application's behavior into two parts: 8 | 9 | 1. **Command**: This part deals with the operational changes to the system—actions that alter the state of the application. For example, creating a new user, updating order details, or processing a payment. Commands are responsible for enforcing business rules, ensuring data integrity, and making changes to the database. 10 | 11 | 2. **Query**: This part handles data retrieval without making any modifications. Queries are used to retrieve data from the system, often optimized for read performance and user experience. 12 | 13 | The principle behind CQRS is based on **Command Query Separation (CQS)**, which was introduced by Bertrand Meyer, emphasizing that commands should not return data, and queries should not change state. CQRS takes this a step further by completely decoupling the commands from queries, typically resulting in two separate models and services. 14 | 15 | ## Benefits of CQRS 16 | 17 | - **Scalability**: Since the read and write operations are decoupled, they can be scaled independently, making CQRS well-suited for high-traffic systems. 18 | - **Optimization**: The read side can be optimized differently than the write side. For instance, the read model can use denormalized views or caching mechanisms to improve performance. 19 | - **Flexibility**: CQRS allows multiple read models tailored to different use cases. This means different clients can have views optimized for their specific needs without affecting the consistency of write operations. 20 | - **Event-Driven Integration**: CQRS works well with **Event Sourcing**, an approach where state changes are stored as events. Each change generates an event, which is used by the query model to update its data view. This event-driven mechanism ensures consistency between the read and write models. 21 | 22 | ## Implementation of CQRS 23 | 24 | In a CQRS-based system, there are typically separate stores for commands and queries: 25 | 26 | - **Write Store**: Handles the operational commands of the application. It’s responsible for storing the actual data in normalized form to maintain data integrity. 27 | - **Read Store**: Handles data retrieval, often utilizing a denormalized or replicated version of the data that is optimized for queries. 28 | 29 | This separation means that different databases and technologies can be used for the read and write operations. For example, a relational database could be used for the write store while a NoSQL database could serve the read store to achieve high query performance. 30 | 31 | ## Event-Driven Approach and CQRS 32 | 33 | According to the book "Building Event-Driven Microservices" by Adam Bellemare, event-driven approaches integrate well with CQRS because the system’s state changes are captured as events, which can then be propagated to update the query model effectively and asynchronously. Events act as the source of truth, enabling both consistency and traceability of all state transitions, which are crucial in distributed systems. 34 | 35 | ## Best Practices for Implementing CQRS 36 | 37 | - **Keep Read and Write Models Consistent**: Implement mechanisms to keep the read and write models eventually consistent. This could involve using a message broker to propagate events from the write model to the read model. 38 | - **Avoid Over-Complexity for Simple Systems**: CQRS is not suitable for all projects. It introduces additional complexity due to the maintenance of two separate models. It is best applied to systems with complex domain logic and scalability requirements. 39 | - **Event Sourcing**: Consider using **Event Sourcing** along with CQRS to leverage event-driven behavior effectively. Each state change is represented as an event, which can be useful for auditing, debugging, and replaying events to reconstruct system state. 40 | 41 | ## Challenges in CQRS 42 | 43 | - **Consistency Management**: Ensuring consistency between the read and write models can be challenging, especially in highly distributed environments. 44 | - **Increased Complexity**: CQRS introduces additional complexity by maintaining two different models, which may require more effort in terms of development, testing, and deployment. 45 | 46 | ## Conclusion 47 | 48 | CQRS is a powerful pattern that can help in managing complex domains by decoupling the read and write operations. Its integration with event-driven systems, particularly in combination with **Event Sourcing**, helps achieve scalability, flexibility, and robustness in distributed architectures. However, the added complexity makes it important to evaluate whether CQRS is suitable for a given use case before implementation. 49 | 50 | ### References 51 | 52 | - Bellemare, Adam. _Building Event-Driven Microservices_. O'Reilly Media, 2020. 53 | - Burns, Brendan. _Designing Distributed Systems: Patterns and Paradigms for Scalable, Reliable Services_. O'Reilly Media, 2018. 54 | -------------------------------------------------------------------------------- /knowledgebase/concepts/architectual-concepts/eda.md: -------------------------------------------------------------------------------- 1 | # Event-Driven Architecture (EDA) 2 | 3 | Event-Driven Architecture (EDA) is a software design paradigm that promotes decoupled, scalable, and flexible system interactions by relying on events as the core means of communication between components. This architectural style is well-suited to the needs of modern, distributed systems where real-time responsiveness and adaptability are crucial. Below, we will explore the essential components, benefits, challenges, and best practices of EDA, drawing from various foundational texts in distributed systems and software architecture. 4 | 5 | ## Core Concepts of Event-Driven Architecture 6 | 7 | ### Event Producers and Event Consumers 8 | 9 | In an event-driven system, components can either produce events, consume events, or both. The **event producers** generate events when significant actions or state changes occur, while **event consumers** are responsible for handling those events in a way that produces a meaningful response or action. 10 | 11 | - **Event Producers** are typically the origin points of events. They emit events based on specific activities, such as when a user performs an action in an application or when a system detects a state change. 12 | - **Event Consumers** react to the emitted events and can initiate further activities based on the received information. These activities could be business logic, database updates, or interactions with other services. 13 | 14 | ### Event Bus or Broker 15 | 16 | A core component of EDA is the **event bus** or **event broker**, which serves as an intermediary that routes events from producers to consumers. Event brokers decouple the producers and consumers, allowing them to operate independently of each other. Systems like **Apache Kafka**, **RabbitMQ**, and **AWS SNS** are often used as event brokers to enable distributed event handling, ensuring scalability and durability. 17 | 18 | ### Event Types 19 | 20 | - **Domain Events**: Represent key state changes within the domain, such as "Order Placed" or "Payment Processed." 21 | - **Integration Events**: Used for communication between different services, typically in distributed systems, to keep them in sync. 22 | 23 | ## Benefits of Event-Driven Architecture 24 | 25 | ### Scalability and Responsiveness 26 | 27 | EDA is inherently scalable, as producers and consumers operate independently. This means that more consumers can be added to handle a greater volume of events as the need arises. This decoupling helps to create systems that can be scaled horizontally without significant refactoring. 28 | 29 | The responsiveness is enhanced by enabling real-time data flows, where consumers react to events as they happen, leading to better user experiences and faster decision-making processes. 30 | 31 | ### Loose Coupling and Flexibility 32 | 33 | The decoupled nature of event-driven systems allows for greater flexibility in system evolution. Since producers and consumers are not directly dependent on each other, changes in one component do not necessarily require changes in the other. This allows for rapid iterations and deployment cycles. 34 | 35 | ### High Fault Tolerance 36 | 37 | An event-driven system can continue functioning effectively even if one or more components are unavailable. Event brokers typically have mechanisms for storing and replaying events, allowing services to pick up from where they left off once restored. This increases the fault tolerance of the system as a whole. 38 | 39 | ## Challenges of Event-Driven Architecture 40 | 41 | ### Complexity of Debugging and Monitoring 42 | 43 | While EDA provides scalability and flexibility, the complexity of managing such systems can be challenging. Tracing the flow of events across distributed components can make debugging and root cause analysis difficult. Effective **distributed tracing** and **logging tools** are crucial for gaining visibility into event flows. 44 | 45 | ### Eventual Consistency 46 | 47 | Since events are processed asynchronously, EDA often requires a trade-off between strong consistency and availability. Systems designed using EDA are generally **eventually consistent**, meaning that not all components have the latest state at any given moment. Managing this eventual consistency can be complex and requires additional design considerations, such as employing **sagas** for orchestrating long-running processes. 48 | 49 | ### Handling Duplicate Events 50 | 51 | Events can be delivered multiple times due to retries or network failures. Therefore, it is important to design consumers to be **idempotent**, meaning they can safely handle the same event multiple times without unintended side effects. 52 | 53 | ## Common Patterns in Event-Driven Architecture 54 | 55 | ### Event Sourcing 56 | 57 | **Event Sourcing** is a pattern where the state of the system is determined by replaying the sequence of domain events that have occurred. Rather than storing the current state, events are logged and stored as they occur. This enables complete reconstruction of system state at any point in time, allowing for auditing and easy reprocessing of events when the business logic evolves. 58 | 59 | ### Command Query Responsibility Segregation (CQRS) 60 | 61 | In combination with EDA, **CQRS** is often used to segregate the write and read sides of an application. Commands are used to make changes to the system, while events are emitted to synchronize the read model. This separation helps scale the read side independently, enabling complex query operations while maintaining high performance. 62 | 63 | ### Saga Pattern 64 | 65 | The **Saga pattern** is used to manage distributed transactions and achieve eventual consistency in an event-driven system. A saga orchestrates multiple distributed steps that must be completed for a business transaction, ensuring proper rollbacks and compensating actions if any of the steps fail. 66 | 67 | ## Best Practices for Implementing Event-Driven Architecture 68 | 69 | 1. **Design for Idempotency**: Make sure that event consumers can safely handle repeated events to avoid unintended actions or state corruption. 70 | 2. **Event Schema Evolution**: Ensure events can evolve without breaking consumers by including versioning and considering backward compatibility. 71 | 3. **Monitoring and Observability**: Utilize tracing and monitoring tools to capture the lifecycle of events as they traverse the system. Tools like **Jaeger**, **Zipkin**, and centralized logging platforms are helpful in maintaining observability. 72 | 4. **Event Granularity**: Keep events as meaningful but small as possible. Broadcasting highly granular events might lead to too much noise, while too coarse-grained events could lose important details and become hard to manage. 73 | 74 | ## Practical Applications and Use Cases 75 | 76 | - **E-commerce Platforms**: An e-commerce system may use EDA to trigger inventory updates, notify the user, and initiate fulfillment processes when a customer places an order. 77 | - **Fraud Detection**: Financial services can leverage EDA to implement real-time monitoring for fraudulent activities, using streaming analytics to detect unusual patterns as they emerge. 78 | - **IoT Systems**: In IoT, sensors produce a large volume of data that can be efficiently handled by an event-driven system, where different services can consume this data for analytics, monitoring, or alerting. 79 | 80 | ## Conclusion 81 | 82 | Event-Driven Architecture is well-suited to building scalable, decoupled, and resilient systems. By effectively separating event producers from consumers, EDA enables real-time responsiveness and independent service evolution, both crucial for complex distributed environments. While challenges like debugging, monitoring, and managing eventual consistency can pose difficulties, adopting best practices such as idempotency, robust monitoring, and thoughtful event granularity can ensure a successful implementation. 83 | 84 | ## References 85 | 86 | - Newman, Sam. _Building Microservices: Designing Fine-Grained Systems_. O'Reilly Media, 2021. 87 | - Kleppmann, Martin. _Designing Data-Intensive Applications_. O'Reilly Media, 2017. 88 | - Fowler, Martin. _Patterns of Enterprise Application Architecture_. Addison-Wesley, 2002. 89 | -------------------------------------------------------------------------------- /knowledgebase/concepts/architectual-concepts/event-sourcing.md: -------------------------------------------------------------------------------- 1 | # Event Sourcing: An Overview 2 | 3 | Event sourcing is an architectural pattern used in distributed systems that focuses on capturing all state changes as a sequence of events, rather than storing only the latest state. This technique is particularly useful for maintaining a historical log of changes, improving system reliability, and enabling scalability. It allows for full audit trails, supports temporal querying, and facilitates debugging by replaying events to reproduce issues, making it a robust choice for applications that require a detailed history of actions and flexible recovery options. 4 | 5 | ## What is Event Sourcing? 6 | 7 | In traditional applications, databases store the current state of an entity, and this state is updated whenever changes occur. Event sourcing, however, approaches data persistence differently. Instead of storing the current state, each change to an entity is recorded as an immutable event. The current state of the entity can be derived by replaying these events. 8 | 9 | The fundamental principle behind event sourcing is that every significant change in a system—often called a domain event—is captured and stored as a standalone record. This way, the series of events can be replayed in sequence to rebuild the entity's state at any point in time. This provides the ability to reconstruct historical states and gain insights into how and why specific changes occurred, which is especially valuable for complex domains with evolving business logic. 10 | 11 | ## How Event Sourcing Works 12 | 13 | - **Capture Events:** Every user action or system behavior that changes the state of the system generates an event. These events are recorded in an event store. 14 | - **Event Store:** The event store functions as a form of append-only log where all events are stored in the order they occur. This ensures an accurate historical record and allows for easy replication across distributed systems. 15 | - **Replay Events:** To reconstruct the current state of an entity, all events related to that entity are replayed in sequence, accumulating the changes to derive the final state. This process ensures that the system can recover from failures by simply reapplying events. 16 | - **Snapshots:** To enhance performance, periodic snapshots can be taken to represent the entity’s state at a specific time, reducing the need to replay all events when reconstructing the state. Snapshots help optimize the performance of the system, especially for entities with a large number of events. 17 | 18 | ## Benefits of Event Sourcing 19 | 20 | ### 1. **Audit Trail and History** 21 | 22 | With event sourcing, each change to the system is captured as an event, providing a detailed history of all modifications. This ensures a complete audit trail, which is especially useful in industries with strict regulatory requirements, such as finance or healthcare. The ability to trace every change provides transparency, making it easier to validate processes and comply with audit demands. 23 | 24 | ### 2. **Scalability** 25 | 26 | Event sourcing is naturally suited for distributed systems. Events are immutable, which makes it easier to replicate them across nodes and distribute system loads effectively. Additionally, it allows for better load balancing when managing high volumes of transactions. By decoupling the write and read models, event sourcing allows for efficient horizontal scaling, making it ideal for applications that need to handle a high number of concurrent operations. 27 | 28 | ### 3. **Debugging and Reproducibility** 29 | 30 | Because every state change is recorded, it's easy to diagnose issues and understand the exact sequence of actions that led to a particular state. This also means that bugs can be reproduced more easily by replaying the events in the same order. Debugging becomes more straightforward because developers can step through the history of events and identify exactly where the logic went wrong, enabling faster resolution of issues. 31 | 32 | ### 4. **Temporal Querying** 33 | 34 | Event sourcing allows for querying the state of the system at any specific point in time. This temporal aspect is helpful for understanding past states of the system, enabling use cases such as time travel debugging or auditing past user actions. The ability to access historical snapshots is invaluable for business intelligence, allowing organizations to analyze trends and behaviors over time. 35 | 36 | ## Challenges of Event Sourcing 37 | 38 | ### 1. **Complexity** 39 | 40 | Event sourcing introduces additional complexity to the design of the system. Developers need to manage the event store, deal with schema changes for events, and understand the implications of replaying events in the correct order. The need to consider event ordering and ensure that all events are applied correctly adds to the system's intricacy. Furthermore, understanding the implications of each event for different components of the system requires careful design and domain knowledge. 41 | 42 | ### 2. **Eventual Consistency** 43 | 44 | Event sourcing often leads to an eventually consistent system, especially when integrated with a Command Query Responsibility Segregation (CQRS) approach. This means that different parts of the system may temporarily be out of sync, requiring careful handling to avoid data inconsistency. Ensuring that end users have a seamless experience despite the delays in propagating state changes can be challenging. Proper monitoring and handling of inconsistencies are necessary to maintain system integrity. 45 | 46 | ### 3. **Event Versioning** 47 | 48 | As the system evolves, the structure of events might need to change. Handling event versioning is challenging, as all previously stored events must still be interpretable even if the business logic has changed. Developers must account for multiple versions of events and ensure that older events can be properly understood and processed by the system. This often requires implementing versioning strategies, upcasting, or fallback mechanisms to maintain compatibility. 49 | 50 | ## Use Cases for Event Sourcing 51 | 52 | 1. **Financial Transactions:** In financial services, maintaining a record of every transaction is critical for audits, reconciliation, and debugging. Event sourcing provides the necessary detailed historical records. This helps not only in maintaining compliance but also in providing customers with transparency regarding their transaction history. 53 | 54 | 2. **E-commerce Systems:** In e-commerce, actions like adding items to a shopping cart or placing orders can be captured as events, allowing for detailed analysis of user behavior and easier recovery from failures. Event sourcing can also be used to analyze customer journeys, track purchasing trends, and provide personalized recommendations based on historical events. 55 | 56 | 3. **Healthcare Systems:** Keeping track of all modifications to patient data is essential for compliance with regulations such as HIPAA. Event sourcing provides a detailed record of all changes, ensuring full auditability. It also helps healthcare professionals track the evolution of patient care, providing insights that can improve treatment outcomes and ensure patient safety. 57 | 58 | ## Event Sourcing and CQRS 59 | 60 | Event sourcing is often used in conjunction with the Command Query Responsibility Segregation (CQRS) pattern. CQRS is an approach that separates read and write operations into distinct models. In an event-sourced system, commands (write operations) generate events, and those events update the event store. Read models can then be derived from these events in an efficient way, optimized specifically for querying. 61 | 62 | By combining event sourcing and CQRS, systems can achieve a higher level of scalability, separate concerns more effectively, and manage complex business logic with better domain alignment. CQRS allows read operations to be optimized for performance and scalability, while write operations focus on capturing business intent. This combination not only simplifies the design but also ensures that the system remains responsive and adaptable to changes. 63 | 64 | ## Best Practices for Event Sourcing 65 | 66 | 1. **Idempotency:** Commands should be idempotent to ensure that reprocessing an event doesn't create inconsistencies. This is particularly important in distributed systems where retries can lead to duplicate events. Ensuring idempotency guarantees that each event results in a consistent state, regardless of how many times it is processed. 67 | 68 | 2. **Periodic Snapshots:** Create snapshots periodically to speed up the state reconstruction of aggregates. This is especially important for entities that accumulate a large number of events. Snapshots reduce the load on the event store and minimize the time required to rehydrate entities, which is crucial for maintaining the system's performance. 69 | 70 | 3. **Handling Event Versioning:** Use clear strategies for event versioning to ensure that older events are still compatible with newer logic. Techniques such as upcasting, where older events are transformed into a newer version, can help maintain compatibility. Proper documentation and tooling should be in place to handle different versions of events effectively, ensuring smooth system evolution. 71 | 72 | 4. **Domain-Driven Design (DDD):** Adopt DDD principles to ensure that domain events closely represent business actions. This helps in maintaining a rich, expressive domain model. By aligning events with domain concepts, the resulting model remains understandable and maintainable, even as the business evolves. 73 | 74 | ## Conclusion 75 | 76 | Event sourcing is a powerful pattern that addresses the limitations of traditional data storage by capturing every state change as a series of immutable events. It provides scalability, auditability, and temporal insights, making it particularly useful for complex business applications. However, event sourcing also introduces complexity, requiring careful attention to eventual consistency, event versioning, and maintaining an efficient event store. When used appropriately and combined with other architectural patterns like CQRS, event sourcing can significantly enhance the reliability and scalability of software systems. 77 | 78 | ### Resources 79 | 80 | - ""Building Event-Driven Microservices" by Hugo Rocha (2022), which explores the principles of designing resilient event-driven systems and emphasizes the benefits of using event sourcing in distributed architectures. 81 | - "Designing Distributed Systems" by Brendan Burns (2018), providing a comprehensive overview of how distributed systems can be designed for reliability and scalability, focusing on patterns like event sourcing to ensure robustness. 82 | - "Building Microservices" by Sam Newman (2021), detailing best practices for breaking down applications into smaller, loosely coupled services, and highlighting the role of event sourcing in managing distributed state effectively. 83 | -------------------------------------------------------------------------------- /knowledgebase/concepts/architectual-concepts/modular-monolith.md: -------------------------------------------------------------------------------- 1 | # Modular Monolith: An Overview 2 | 3 | A modular monolith is an architectural approach that combines some of the best practices of microservices while maintaining the simplicity of a monolithic system. Unlike a traditional monolith, where all the components are tightly coupled and interdependent, a modular monolith breaks down the system into separate, well-defined modules that can be worked on independently. However, these modules are still deployed together as a single unit. This combination of modularity and simplicity offers an attractive middle ground for many teams that are not ready for the complexity of full microservices but need to improve the flexibility and maintainability of their applications. 4 | 5 | ## What is a Modular Monolith? 6 | 7 | In a modular monolith, the application is composed of several distinct modules that represent different functional areas or business capabilities. Each module has its own well-defined responsibilities and interacts with other modules through explicit interfaces. Although all modules are deployed within a single runtime process, they are logically separated, reducing the complexity and interdependencies often associated with traditional monolithic systems. 8 | 9 | A modular monolith emphasizes the following characteristics: 10 | 11 | - **Separation of Concerns**: Different business functions are separated into different modules. This separation ensures that each module is responsible for a specific part of the system, which makes the codebase easier to understand, develop, and maintain. 12 | - **Independent Development**: Each module can be developed, tested, and maintained independently by different teams. By creating clearly defined boundaries, teams can work autonomously, which leads to faster development cycles. 13 | - **Single Deployment Unit**: Unlike microservices, where each service is deployed independently, a modular monolith is packaged and deployed as a single unit. This reduces deployment complexity, making it easier to manage. 14 | - **Increased Cohesion**: Each module is designed to be cohesive, meaning that related functionalities are grouped together. This high cohesion helps in understanding the domain more clearly and reduces redundancy across the system. 15 | 16 | ## Benefits of a Modular Monolith 17 | 18 | ### 1. **Simpler Deployment and Operations** 19 | 20 | A key advantage of a modular monolith over microservices is its simplicity in deployment. Since all modules are packaged into a single application, the need for coordinating deployments across different services is eliminated. This simplifies release management, reduces deployment failures, and requires fewer operational overheads. The need for complex container orchestration tools or distributed tracing solutions is also minimized, which can be appealing for small teams or projects without dedicated DevOps resources. 21 | 22 | ### 2. **Easier to Evolve into Microservices** 23 | 24 | Modular monoliths provide a solid foundation for gradually evolving into a microservice architecture. By first splitting the system into well-defined modules, teams can later decouple and extract individual modules into standalone services when needed. This evolutionary approach allows organizations to adopt microservices at their own pace, with minimal risk and disruption to the business. 25 | 26 | ### 3. **Improved Developer Experience** 27 | 28 | The modular monolith structure helps reduce cognitive load for developers by creating smaller, self-contained areas of functionality within the application. This makes it easier for new developers to onboard and focus on specific parts of the system without having to understand the entire codebase. It also fosters better communication among developers, as they can understand the boundaries and responsibilities of each module. 29 | 30 | ### 4. **Cost Efficiency** 31 | 32 | Operating and maintaining a microservice architecture can be expensive due to the need for complex infrastructure and monitoring tools. A modular monolith is more cost-effective as it runs as a single application, reducing cloud computing costs and infrastructure needs. This makes it an ideal solution for startups or small-to-medium-sized businesses that may not have the budget to manage microservices effectively. 33 | 34 | ## Challenges of a Modular Monolith 35 | 36 | ### 1. **Deployment Coupling** 37 | 38 | While a modular monolith reduces complexity by maintaining a single deployment unit, this also means that all modules need to be deployed together. If one module changes, the entire application needs to be redeployed. This could lead to bottlenecks if teams are working on multiple features at the same time, especially in a large application. 39 | 40 | ### 2. **Scalability Limitations** 41 | 42 | Scaling a modular monolith is more challenging compared to microservices. When the application needs to scale, the entire system is scaled, which may lead to inefficient use of resources. With microservices, individual components can be scaled based on demand, providing a more efficient scaling solution. 43 | 44 | ### 3. **Module Dependencies** 45 | 46 | Although a modular monolith aims to create clear boundaries between modules, enforcing these boundaries in a single deployment unit can be difficult. Over time, module dependencies may become tangled, making it challenging to separate them in the future if a move to microservices is desired. Maintaining discipline in defining and managing dependencies between modules is crucial for long-term success. 47 | 48 | ## Use Cases for Modular Monoliths 49 | 50 | ### 1. **Startups and MVP Development** 51 | 52 | For startups or organizations building a Minimum Viable Product (MVP), a modular monolith provides the right balance of simplicity and scalability. It allows for rapid development and iteration while maintaining a clean and maintainable codebase. As the business grows, the monolith can be gradually modularized and eventually split into microservices if necessary. 53 | 54 | ### 2. **Applications with Moderate Complexity** 55 | 56 | Applications that are not highly complex, but still require some level of modularity for maintainability, can benefit from a modular monolith. Examples include internal business applications, content management systems, or e-commerce platforms that don't need the high scalability offered by microservices. 57 | 58 | ### 3. **Organizations Not Ready for Microservices** 59 | 60 | Not every organization has the capability or the maturity to manage the complexity of a microservices architecture. A modular monolith offers an opportunity to adopt many of the best practices of software modularity without the complexity of distributed systems, making it an ideal stepping stone for organizations that plan to adopt microservices in the future. 61 | 62 | ## Best Practices for Implementing a Modular Monolith 63 | 64 | 1. **Define Clear Module Boundaries**: Establish clear boundaries between modules based on business capabilities. Each module should have well-defined responsibilities and should interact with other modules through well-documented APIs. 65 | 2. **Avoid Cross-Module Dependencies**: Cross-module dependencies can lead to tight coupling, which defeats the purpose of modularity. Keep dependencies minimal and well-defined, using interfaces to communicate between modules. 66 | 3. **Use Domain-Driven Design (DDD)**: Applying DDD principles, such as bounded contexts, can help create modules that closely align with business functions, ensuring that the monolith remains easy to understand and maintain. 67 | 4. **Refactor Regularly**: Regular refactoring helps prevent the monolith from becoming a "big ball of mud." Maintain clean, consistent code, and revisit module boundaries as the system evolves. 68 | 5. **Automate Testing and CI/CD**: Modular monoliths benefit greatly from automated testing and continuous integration/continuous deployment (CI/CD) pipelines. Unit tests, integration tests, and end-to-end tests ensure that modules interact correctly and reduce the risks associated with deployment coupling. 69 | 70 | ## Conclusion 71 | 72 | A modular monolith represents an architectural middle ground between traditional monolithic systems and microservices. It provides many of the benefits of microservices, such as modularity, clear boundaries, and improved maintainability, while retaining the simplicity of monolithic deployment. For many organizations, it is a practical choice that balances the need for scalability, flexibility, and ease of management, especially when the overhead of a full microservices architecture is not justified. 73 | 74 | As software systems grow in complexity, starting with a modular monolith can provide a strong foundation that makes future transitions to microservices easier. Organizations should carefully assess their needs, business goals, and available resources before deciding on the appropriate architecture, and a modular monolith can be an excellent place to begin. 75 | 76 | ### References 77 | 78 | - Newman, S. (2020). _Monolith to Microservices: Evolutionary Patterns to Transform Your Monolith_. O'Reilly Media. 79 | -------------------------------------------------------------------------------- /knowledgebase/concepts/architectual-concepts/msa.md: -------------------------------------------------------------------------------- 1 | 2 | # **Microservice Architecture** 3 | 4 | Microservice architecture is an architectural style that structures an application as a collection of small, autonomous services modeled around a business domain. This approach aims to improve agility, scalability, and maintainability by enabling independent development and deployment of services. 5 | 6 | ## Key Concepts of Microservice Architecture 7 | 8 | 1. **Independent Deployability**: Microservices are designed to be independently deployable. Each service can be updated, scaled, or replaced without impacting the rest of the system. This modularity allows teams to work autonomously, reduce dependencies, and accelerate release cycles. 9 | 10 | 2. **Domain-Driven Design**: Microservices are often modeled around business domains using Domain-Driven Design (DDD). The concept of bounded contexts, which helps define clear boundaries and responsibilities for each service, is critical to microservices. This ensures that each service focuses on a specific business capability, reducing coupling and enhancing cohesion. 11 | 12 | 3. **Technology Heterogeneity**: Microservices enable the use of different technologies, frameworks, and databases for different services. This flexibility allows developers to choose the best tools and languages for each service, catering to specific requirements. 13 | 14 | 4. **Autonomy**: Each microservice owns its own data and is responsible for its own database. This approach minimizes the dependencies between services, promoting autonomy and enabling independent scaling. 15 | 16 | 5. **Scalability**: Microservices are scalable at the individual service level. This means that only the components that experience high demand need to be scaled, leading to efficient resource usage. Horizontal scaling—adding more instances—is commonly used in microservices to achieve high availability and load distribution. 17 | 18 | 6. **Resilience**: Microservices are designed to handle failures gracefully. Techniques such as bulkheads, retries, and circuit breakers are used to ensure that failures in one service do not cascade to other parts of the system. By isolating faults and ensuring graceful degradation, microservices help build resilient and fault-tolerant systems. 19 | 20 | 7. **Event-Driven Communication**: Microservices often use event-driven communication to maintain loose coupling. Events help services communicate asynchronously, ensuring that they are decoupled and can evolve independently. This also supports patterns like event sourcing, where state changes are stored as a sequence of events. 21 | 22 | ## Pros and Cons of Microservices 23 | 24 | ### Advantages 25 | 26 | - **Agility**: Microservices allow teams to work independently, releasing features faster and improving overall responsiveness to business needs. 27 | - **Scalability**: Services can be scaled independently, optimizing resource use based on the demands of specific features or components. 28 | - **Flexibility in Technology**: Teams can choose the technology stack that best fits their use case for each service, rather than being constrained to a single stack. 29 | - **Improved Fault Isolation**: Failures in one service are isolated and do not lead to the entire system failing. 30 | 31 | ### Challenges 32 | 33 | - **Increased Complexity**: Microservices introduce complexity in areas like distributed systems, inter-service communication, and managing data consistency. 34 | - **Data Consistency**: Maintaining consistency across services can be challenging, especially as each service typically owns its own database. 35 | - **Monitoring and Debugging**: Observing the behavior of microservices can be difficult due to their distributed nature. Implementing effective monitoring, tracing, and debugging becomes essential. 36 | - **Deployment Overhead**: Each microservice needs to be deployed independently, which can add deployment overhead, especially in larger systems. 37 | 38 | ## Common Patterns in Microservices 39 | 40 | - **API Gateway**: An API Gateway is used as a single entry point for clients, routing requests to the appropriate microservice. It provides abstraction and can also handle cross-cutting concerns like authentication, logging, and rate limiting. 41 | - **Service Mesh**: A service mesh manages the inter-service communication in a microservice architecture, abstracting the network functions to provide secure and reliable communication. 42 | - **Event Sourcing and CQRS**: Command Query Responsibility Segregation (CQRS) is often used with microservices to separate read and write operations. Event sourcing stores the sequence of changes, allowing the system to be reconstructed by replaying events. 43 | 44 | ## Conclusion 45 | 46 | Microservices provide a powerful way to build scalable, agile, and resilient applications. They promote autonomy, independent deployability, and alignment with business domains, but also introduce challenges like increased complexity, data consistency issues, and operational overhead. When adopting microservices, it’s important to carefully evaluate the needs of your organization, understanding both the potential benefits and the trade-offs. 47 | 48 | ## **References** 49 | 50 | - Sam Newman, _Building Microservices: Designing Fine-Grained Systems_, 2nd Edition, O'Reilly Media, 2021. 51 | - Mark Richards, _Software Architecture Patterns_, 2nd Edition, O'Reilly Media, 2022. 52 | -------------------------------------------------------------------------------- /knowledgebase/concepts/best-practises/aligmentbusiness.md: -------------------------------------------------------------------------------- 1 | # Aligning Bounded Contexts with Business Boundaries 2 | 3 | ## **Table of Contents** 4 | 5 | - [Aligning Bounded Contexts with Business Boundaries](#aligning-bounded-contexts-with-business-boundaries) 6 | - [**Table of Contents**](#table-of-contents) 7 | - [**Introduction**](#introduction) 8 | - [**Understanding Bounded Contexts**](#understanding-bounded-contexts) 9 | - [**The Importance of Aligning Bounded Contexts with Business Boundaries**](#the-importance-of-aligning-bounded-contexts-with-business-boundaries) 10 | - [**Best Practices for Alignment**](#best-practices-for-alignment) 11 | - [**Analyze the Business Domain**](#analyze-the-business-domain) 12 | - [**Identify Natural Business Divisions**](#identify-natural-business-divisions) 13 | - [**Engage Stakeholders and Domain Experts**](#engage-stakeholders-and-domain-experts) 14 | - [**Reflect Organizational Structure**](#reflect-organizational-structure) 15 | - [**Use Ubiquitous Language**](#use-ubiquitous-language) 16 | - [**Consider Team Structures**](#consider-team-structures) 17 | - [**Maintain Clear Interfaces and Integration Points**](#maintain-clear-interfaces-and-integration-points) 18 | - [**Examples Where Alignment Fits**](#examples-where-alignment-fits) 19 | - [**Example 1: E-Commerce Platform**](#example-1-e-commerce-platform) 20 | - [**Example 2: Financial Services Organization**](#example-2-financial-services-organization) 21 | - [**Potential Challenges and Solutions**](#potential-challenges-and-solutions) 22 | - [**Dealing with Legacy Systems**](#dealing-with-legacy-systems) 23 | - [**Organizational Resistance**](#organizational-resistance) 24 | - [**Overlapping Responsibilities**](#overlapping-responsibilities) 25 | - [**Conclusion**](#conclusion) 26 | 27 | ## **Introduction** 28 | 29 | In **Domain-Driven Design (DDD)**, the concept of a **Bounded Context** is crucial for managing complexity in large systems. A bounded context defines a clear boundary within which a particular domain model applies. Aligning these bounded contexts with actual business boundaries ensures that the software system mirrors the real-world organization, leading to better communication, reduced complexity, and more effective collaboration between technical and business teams. 30 | 31 | This article explores the best practices for aligning bounded contexts with business boundaries, emphasizing the importance of reflecting real-world divisions and responsibilities within the technical architecture. 32 | 33 | ## **Understanding Bounded Contexts** 34 | 35 | A **Bounded Context** is a central pattern in Domain-Driven Design. It represents a specific responsibility or area within the domain where a particular model is defined and applicable. Within a bounded context: 36 | 37 | - The **Ubiquitous Language** is consistent. 38 | - The domain model is cohesive and well-defined. 39 | - The boundaries are explicit, reducing ambiguity. 40 | 41 | By segmenting a system into bounded contexts, teams can manage complexity by focusing on smaller, well-understood parts of the domain. 42 | 43 | ## **The Importance of Aligning Bounded Contexts with Business Boundaries** 44 | 45 | Aligning bounded contexts with business boundaries means that the technical divisions in the software reflect the actual organizational structures, responsibilities, and divisions within the business. This alignment offers several benefits: 46 | 47 | - **Improved Communication:** Shared understanding between developers and business stakeholders. 48 | - **Reduced Complexity:** Simplifies the system by mirroring real-world divisions. 49 | - **Enhanced Collaboration:** Teams can work more effectively when technical and business boundaries align. 50 | - **Clear Ownership:** Responsibilities and ownership are well-defined, reducing overlaps and conflicts. 51 | - **Easier Maintenance and Evolution:** Changes in the business are more naturally reflected in the software. 52 | 53 | ## **Best Practices for Alignment** 54 | 55 | ### **Analyze the Business Domain** 56 | 57 | **Understanding the business domain** is the first step toward effective alignment. This involves: 58 | 59 | - **Studying Business Processes:** Analyze workflows, operations, and procedures. 60 | - **Identifying Key Concepts:** Recognize fundamental entities, actions, and rules. 61 | - **Mapping Business Goals:** Understand the objectives and how different parts contribute. 62 | 63 | **Example:** In a retail company, recognizing that inventory management, order processing, and customer relations are distinct areas with specific responsibilities. 64 | 65 | ### **Identify Natural Business Divisions** 66 | 67 | Look for **natural separations** within the business, such as departments, functions, or product lines. These divisions often represent logical boundaries for bounded contexts. 68 | 69 | - **Departments:** Sales, Marketing, Finance, HR. 70 | - **Functions:** Customer Support, Product Development, Logistics. 71 | - **Product Lines:** Different products or services offered. 72 | 73 | **Example:** A software company might have separate divisions for desktop applications and cloud services, each representing a bounded context. 74 | 75 | ### **Engage Stakeholders and Domain Experts** 76 | 77 | Involve those who have deep knowledge of the domain: 78 | 79 | - **Domain Experts:** Individuals with specialized knowledge. 80 | - **Stakeholders:** Those affected by or interested in the system. 81 | 82 | Engaging them helps in: 83 | 84 | - **Clarifying Ambiguities:** Resolving unclear aspects of the domain. 85 | - **Validating Models:** Ensuring that the technical model reflects reality. 86 | - **Building Ubiquitous Language:** Developing a shared vocabulary. 87 | 88 | **Example:** Working with the finance team to understand regulatory compliance requirements in the accounting context. 89 | 90 | ### **Reflect Organizational Structure** 91 | 92 | Align the bounded contexts with the organization's structure: 93 | 94 | - **Team Alignment:** Each bounded context corresponds to a team or department. 95 | - **Responsibility Mapping:** Match technical responsibilities with business roles. 96 | - **Communication Paths:** Reflect existing communication channels. 97 | 98 | **Example:** If the customer service department handles support tickets, create a bounded context for customer support that aligns with this department. 99 | 100 | ### **Use Ubiquitous Language** 101 | 102 | Develop a common language used by both technical and business teams: 103 | 104 | - **Consistent Terminology:** Use the same terms across both realms. 105 | - **Documentation:** Maintain glossaries and definitions. 106 | - **Communication:** Encourage its use in meetings, documentation, and code. 107 | 108 | **Example:** If the business refers to clients as "customers," avoid using "users" or "accounts" in the technical model. 109 | 110 | ### **Consider Team Structures** 111 | 112 | Technical teams should be organized in a way that mirrors business divisions: 113 | 114 | - **Autonomous Teams:** Empower teams to make decisions within their context. 115 | - **Clear Boundaries:** Define where one team's responsibility ends and another's begins. 116 | - **Minimized Dependencies:** Reduce cross-team dependencies for faster development. 117 | 118 | **Example:** A dedicated team for order processing can focus solely on that bounded context without interference from other areas. 119 | 120 | ### **Maintain Clear Interfaces and Integration Points** 121 | 122 | Define how bounded contexts interact: 123 | 124 | - **Explicit Interfaces:** Clearly defined APIs or communication protocols. 125 | - **Integration Patterns:** Use appropriate patterns like **Anti-Corruption Layers** or **Published Languages**. 126 | - **Decoupling:** Ensure changes in one context have minimal impact on others. 127 | 128 | **Example:** The sales context communicates with the inventory context through well-defined services that abstract internal complexities. 129 | 130 | ## **Examples Where Alignment Fits** 131 | 132 | ### **Example 1: E-Commerce Platform** 133 | 134 | **Scenario:** An online retailer wants to improve its software system to better reflect its business operations. 135 | 136 | **Business Divisions:** 137 | 138 | - **Product Catalog Management** 139 | - **Shopping Cart and Order Processing** 140 | - **Payment and Billing** 141 | - **Customer Support** 142 | 143 | **Alignment Approach:** 144 | 145 | - **Bounded Contexts:** Define separate contexts for each division. 146 | - **Team Alignment:** Assign dedicated teams to each context. 147 | - **Ubiquitous Language:** Use consistent terms like "Order," "Customer," "Product" across both business and technical domains. 148 | - **Interfaces:** Establish clear APIs between contexts, such as order processing communicating with payment services. 149 | 150 | **Benefits:** 151 | 152 | - **Improved Efficiency:** Teams can work independently, reducing bottlenecks. 153 | - **Better Communication:** Alignment leads to clearer understanding between developers and business stakeholders. 154 | - **Scalability:** Each context can scale independently based on demand. 155 | 156 | ### **Example 2: Financial Services Organization** 157 | 158 | **Scenario:** A bank needs to modernize its systems to comply with new regulations and improve customer service. 159 | 160 | **Business Divisions:** 161 | 162 | - **Retail Banking** 163 | - **Corporate Banking** 164 | - **Investment Services** 165 | - **Compliance and Risk Management** 166 | 167 | **Alignment Approach:** 168 | 169 | - **Bounded Contexts:** Create contexts for each division, including a dedicated context for compliance. 170 | - **Domain Experts Involvement:** Engage compliance officers and financial analysts to define domain models. 171 | - **Reflecting Organizational Structure:** The compliance context mirrors the compliance department's responsibilities. 172 | - **Integration Points:** Use anti-corruption layers to interface legacy systems with new contexts. 173 | 174 | **Benefits:** 175 | 176 | - **Regulatory Compliance:** Ensures that compliance requirements are accurately implemented. 177 | - **Reduced Risk:** Clear boundaries prevent unintended interactions that could lead to compliance violations. 178 | - **Enhanced Collaboration:** Teams understand their responsibilities and how they fit into the larger picture. 179 | 180 | ## **Potential Challenges and Solutions** 181 | 182 | ### **Dealing with Legacy Systems** 183 | 184 | **Challenge:** Existing systems may not align with current business boundaries. 185 | 186 | **Solutions:** 187 | 188 | - **Incremental Refactoring:** Gradually restructure the system, one bounded context at a time. 189 | - **Strangler Pattern:** Implement new functionality around the old system, phasing out legacy components. 190 | - **Anti-Corruption Layer:** Use to interface between new bounded contexts and legacy systems without contaminating the new models. 191 | 192 | **Example:** Introduce a new customer management context while maintaining integration with the old CRM system through an anti-corruption layer. 193 | 194 | ### **Organizational Resistance** 195 | 196 | **Challenge:** Resistance to change from stakeholders or teams accustomed to existing structures. 197 | 198 | **Solutions:** 199 | 200 | - **Stakeholder Engagement:** Involve stakeholders early to explain benefits and gather input. 201 | - **Demonstrate Value:** Show quick wins and improvements resulting from alignment. 202 | - **Training and Support:** Provide resources to help teams adapt to new structures. 203 | 204 | **Example:** Conduct workshops to educate teams on the advantages of aligning technical and business boundaries. 205 | 206 | ### **Overlapping Responsibilities** 207 | 208 | **Challenge:** Some business processes may span multiple divisions, making boundaries unclear. 209 | 210 | **Solutions:** 211 | 212 | - **Define Clear Ownership:** Assign primary ownership while allowing collaboration. 213 | - **Shared Kernel:** Use a shared model for common concepts that overlap. 214 | - **Context Mapping:** Create context maps to visualize and manage overlaps. 215 | 216 | **Example:** Both sales and marketing need access to customer data; establish a shared kernel or define services to handle shared data responsibly. 217 | 218 | ## **Conclusion** 219 | 220 | Aligning bounded contexts with business boundaries is a best practice in Domain-Driven Design that enhances communication, collaboration, and efficiency. By ensuring that technical boundaries reflect real-world divisions and responsibilities, organizations can build software systems that are more maintainable, scalable, and responsive to business needs. 221 | 222 | Implementing this alignment requires careful analysis, stakeholder engagement, and a willingness to adapt. While challenges may arise, the benefits of a well-aligned system often outweigh the difficulties, leading to a more agile and effective organization. 223 | -------------------------------------------------------------------------------- /knowledgebase/concepts/best-practises/bcsmallfocused.md: -------------------------------------------------------------------------------- 1 | # Keeping Bounded Contexts Small and Focused 2 | 3 | ## **Table of Contents** 4 | 5 | - [Keeping Bounded Contexts Small and Focused](#keeping-bounded-contexts-small-and-focused) 6 | - [**Table of Contents**](#table-of-contents) 7 | - [**Introduction**](#introduction) 8 | - [**Understanding Bounded Contexts**](#understanding-bounded-contexts) 9 | - [**Why Smaller and Focused Bounded Contexts are Beneficial**](#why-smaller-and-focused-bounded-contexts-are-beneficial) 10 | - [**Manageability**](#manageability) 11 | - [**Understandability**](#understandability) 12 | - [**Evolvability**](#evolvability) 13 | - [**Best Practices for Keeping Bounded Contexts Small and Focused**](#best-practices-for-keeping-bounded-contexts-small-and-focused) 14 | - [**Define Clear Boundaries**](#define-clear-boundaries) 15 | - [**Align with the Single Responsibility Principle**](#align-with-the-single-responsibility-principle) 16 | - [**Limit the Scope**](#limit-the-scope) 17 | - [**Use Ubiquitous Language**](#use-ubiquitous-language) 18 | - [**Avoid Overlapping Responsibilities**](#avoid-overlapping-responsibilities) 19 | - [**Examples Where This Approach Fits**](#examples-where-this-approach-fits) 20 | - [**Example 1: E-Commerce Application**](#example-1-e-commerce-application) 21 | - [**Example 2: Healthcare System**](#example-2-healthcare-system) 22 | - [**Challenges and Solutions**](#challenges-and-solutions) 23 | - [**Over-Fracturing the Domain**](#over-fracturing-the-domain) 24 | - [**Integration Complexity**](#integration-complexity) 25 | - [**Organizational Alignment**](#organizational-alignment) 26 | - [**Conclusion**](#conclusion) 27 | 28 | ## **Introduction** 29 | 30 | In **Domain-Driven Design (DDD)**, a **Bounded Context** is a logical boundary within which a particular domain model is defined and applicable. Keeping bounded contexts small and focused is a best practice that enhances the manageability, understandability, and evolvability of software systems. This article explores the importance of maintaining small and focused bounded contexts, provides best practices for achieving this, and offers examples to illustrate the concept. 31 | 32 | ## **Understanding Bounded Contexts** 33 | 34 | A **Bounded Context** represents a specific responsibility or domain within a software system where particular terms, definitions, and models are consistent. It serves as a boundary that encapsulates a domain model and its associated code, preventing ambiguity and ensuring that the model remains coherent within its context. 35 | 36 | Key characteristics of a bounded context: 37 | 38 | - **Unified Model:** Within the context, all team members use the same language and definitions. 39 | - **Clear Boundaries:** Interfaces between contexts are explicitly defined. 40 | - **Isolation:** Changes within one context do not directly affect others. 41 | 42 | ## **Why Smaller and Focused Bounded Contexts are Beneficial** 43 | 44 | ### **Manageability** 45 | 46 | **Simplified Maintenance:** 47 | 48 | - **Easier to Maintain:** Smaller contexts contain less code and fewer concepts, making them easier to understand and maintain. 49 | - **Reduced Complexity:** Focusing on a specific domain reduces the cognitive load on developers. 50 | 51 | **Efficient Debugging and Testing:** 52 | 53 | - **Isolated Issues:** Bugs and issues are confined within a context, making them easier to locate and fix. 54 | - **Targeted Testing:** Tests can be more focused, covering the specific functionality of the context. 55 | 56 | ### **Understandability** 57 | 58 | **Clear Domain Understanding:** 59 | 60 | - **Focused Domain Knowledge:** Teams can develop deep expertise in a specific area. 61 | - **Simplified Onboarding:** New team members can learn the context more quickly due to its limited scope. 62 | 63 | **Consistent Language and Concepts:** 64 | 65 | - **Ubiquitous Language:** Consistency in terminology enhances communication within the team. 66 | - **Reduced Ambiguity:** A focused context minimizes misunderstandings related to domain concepts. 67 | 68 | ### **Evolvability** 69 | 70 | **Adaptability to Change:** 71 | 72 | - **Flexible Evolution:** Smaller contexts can adapt more easily to changes in business requirements. 73 | - **Independent Deployment:** Changes can be deployed without affecting other contexts. 74 | 75 | **Scalability:** 76 | 77 | - **Horizontal Scaling:** Individual contexts can be scaled independently based on demand. 78 | - **Technological Freedom:** Teams can choose the most appropriate technologies for their context without impacting others. 79 | 80 | ## **Best Practices for Keeping Bounded Contexts Small and Focused** 81 | 82 | ### **Define Clear Boundaries** 83 | 84 | **Establish Explicit Interfaces:** 85 | 86 | - **Communication Protocols:** Define how contexts interact, using APIs or messaging systems. 87 | - **Isolation of Internal Models:** Internal implementations should not leak outside the context. 88 | 89 | **Example:** In a microservices architecture, each service represents a bounded context with well-defined endpoints. 90 | 91 | ### **Align with the Single Responsibility Principle** 92 | 93 | **Focus on One Responsibility:** 94 | 95 | - **Domain-Driven Focus:** Each context should address a specific domain problem. 96 | - **Avoid Overloading:** Do not add unrelated functionalities to a context. 97 | 98 | **Example:** A "Payment Processing" context handles all payment-related operations, without incorporating order management or customer profiles. 99 | 100 | ### **Limit the Scope** 101 | 102 | **Avoid Scope Creep:** 103 | 104 | - **Strict Scope Definition:** Clearly document what is included and excluded in the context. 105 | - **Regular Reviews:** Periodically assess the context to ensure it hasn't expanded unintentionally. 106 | 107 | **Example:** A context for "User Authentication" should not start handling user preferences unless it's explicitly part of its defined scope. 108 | 109 | ### **Use Ubiquitous Language** 110 | 111 | **Consistent Terminology:** 112 | 113 | - **Shared Vocabulary:** Develop a language that is specific to the context and understood by all team members. 114 | - **Domain Expert Involvement:** Collaborate with domain experts to define terms and concepts. 115 | 116 | **Example:** In a "Shipping" context, terms like "Shipment," "Carrier," and "Tracking Number" have specific meanings agreed upon by the team. 117 | 118 | ### **Avoid Overlapping Responsibilities** 119 | 120 | **Distinct Contexts for Distinct Responsibilities:** 121 | 122 | - **Prevent Duplication:** Ensure that no two contexts handle the same functionality. 123 | - **Clear Ownership:** Assign ownership of domain concepts to specific contexts. 124 | 125 | **Example:** If both "Inventory Management" and "Order Processing" contexts handle stock levels, consider refactoring to have inventory managed solely within "Inventory Management." 126 | 127 | ## **Examples Where This Approach Fits** 128 | 129 | ### **Example 1: E-Commerce Application** 130 | 131 | **Scenario:** 132 | 133 | An online retailer is building an e-commerce platform and wants to ensure the system is maintainable and scalable. 134 | 135 | **Implementation:** 136 | 137 | - **Contexts Defined:** 138 | - **Product Catalog:** Manages product information. 139 | - **Shopping Cart:** Handles items added to the cart by customers. 140 | - **Order Processing:** Manages order creation and fulfillment. 141 | - **Payment Gateway:** Handles payment transactions. 142 | 143 | **Benefits:** 144 | 145 | - **Manageability:** Teams can focus on specific areas, such as the catalog or payments. 146 | - **Understandability:** Each context deals with a well-defined domain, making it easier for team members to specialize. 147 | - **Evolvability:** Changes to the payment system (e.g., adding a new payment provider) can be made independently. 148 | 149 | ### **Example 2: Healthcare System** 150 | 151 | **Scenario:** 152 | 153 | A healthcare provider is developing an electronic health records (EHR) system and wants to keep contexts focused due to the sensitive nature of medical data. 154 | 155 | **Implementation:** 156 | 157 | - **Contexts Defined:** 158 | - **Patient Records:** Manages patient demographic and medical history. 159 | - **Appointment Scheduling:** Handles booking and managing appointments. 160 | - **Billing:** Manages invoices and insurance claims. 161 | - **Laboratory Results:** Handles lab test orders and results. 162 | 163 | **Benefits:** 164 | 165 | - **Manageability:** Sensitive data is confined within specific contexts, enhancing security and compliance. 166 | - **Understandability:** Medical professionals can contribute to the domain model within their expertise. 167 | - **Evolvability:** New regulations affecting billing can be implemented within the billing context without affecting other parts of the system. 168 | 169 | ## **Challenges and Solutions** 170 | 171 | ### **Over-Fracturing the Domain** 172 | 173 | **Challenge:** 174 | 175 | Creating too many small contexts can lead to fragmentation, increasing the complexity of interactions between them. 176 | 177 | **Solution:** 178 | 179 | - **Balance Granularity:** Find the right level of granularity where contexts are small but not excessively fragmented. 180 | - **Context Mapping:** Use context maps to visualize and manage relationships between contexts. 181 | 182 | ### **Integration Complexity** 183 | 184 | **Challenge:** 185 | 186 | Smaller contexts may require more integration points, potentially increasing the complexity of communication. 187 | 188 | **Solution:** 189 | 190 | - **Standardized Communication:** Use consistent protocols and integration patterns. 191 | - **Simplify Interfaces:** Keep interfaces as simple as possible to reduce integration overhead. 192 | 193 | ### **Organizational Alignment** 194 | 195 | **Challenge:** 196 | 197 | Ensuring that team structures align with small and focused contexts can be difficult in larger organizations. 198 | 199 | **Solution:** 200 | 201 | - **Team Topologies:** Organize teams around bounded contexts to enhance ownership and expertise. 202 | - **Cross-Functional Teams:** Include all necessary roles within teams to reduce dependencies. 203 | 204 | ## **Conclusion** 205 | 206 | Keeping bounded contexts small and focused is a best practice in Domain-Driven Design that offers significant advantages in manageability, understandability, and evolvability. By defining clear boundaries, aligning with the single responsibility principle, limiting the scope, using ubiquitous language, and avoiding overlapping responsibilities, organizations can build software systems that are easier to develop, maintain, and adapt to changing business needs. 207 | 208 | This approach facilitates the creation of autonomous teams, enhances communication, and allows for independent scaling and deployment, ultimately leading to more robust and agile software solutions. 209 | -------------------------------------------------------------------------------- /knowledgebase/concepts/best-practises/crossfunctionalteams.md: -------------------------------------------------------------------------------- 1 | # Cross-Functional Teams in Domain-Driven Design: Empowerment and Effectiveness 2 | 3 | ## Introduction 4 | 5 | Domain-Driven Design (DDD) is more than just a set of technical practices for structuring software systems; it's also a mindset that helps align technology and teams with the realities of a business domain. Cross-functional teams play a pivotal role in implementing DDD effectively, ensuring that both technical and domain expertise are integrated from the outset. In this article, we will explore the importance of cross-functional teams within the context of Domain-Driven Design, their structure, and how the notion of empowered product teams fits perfectly into the DDD landscape. 6 | 7 | ## The Importance of Cross-Functional Teams in DDD 8 | 9 | In the context of DDD, cross-functional teams are essential for bridging the gap between business and technology. DDD emphasizes creating software models that closely mirror the business domain, and to achieve this, it's crucial that the people building the software deeply understand the business challenges and opportunities. Cross-functional teams are designed to bring together diverse perspectives—developers, product managers, domain experts, UX designers, and testers—to ensure that all aspects of the domain are understood and correctly modeled. 10 | 11 | The core principle of DDD is collaboration, which requires breaking down traditional silos that often hinder effective communication. Cross-functional teams create an environment where domain knowledge is shared among team members, resulting in a more holistic understanding of the business. This ensures that the domain model is not only technically sound but also aligned with the business's real needs and goals. Such an integrated approach can lead to improved software quality, reduced misunderstandings, and faster development cycles. 12 | 13 | ## Structuring Cross-Functional Teams for DDD Success 14 | 15 | Cross-functional teams in a DDD context should be structured around **bounded contexts**. A bounded context defines a boundary within which a specific model is valid, aligning closely with the notion of business subdomains. Ideally, each cross-functional team is responsible for one or more bounded contexts, enabling them to specialize in a particular area of the business domain and develop a deep understanding of it. 16 | 17 | A typical DDD cross-functional team may consist of: 18 | 19 | - **Domain Experts**: Provide insights into business processes, rules, and challenges. 20 | - **Developers**: Design and implement the software model, ensuring that technical solutions are aligned with the domain requirements. 21 | - **Product Managers**: Define business priorities, make trade-offs, and ensure that the software meets user needs. In DDD, the product manager takes on the role of the Domain Expert, learning everything about the domain and transferring this knowledge to the development team. 22 | - **UX Designers**: Ensure that user interfaces support the goals of the domain, making software intuitive and aligned with user workflows. 23 | - **QA Engineers**: Validate that the domain model behaves as expected and that the implementation aligns with requirements. 24 | 25 | This composition ensures that every aspect of software development—from business rules to user interaction—is accounted for. By embedding domain experts within the team, developers gain direct access to knowledge, which fosters a shared understanding of the domain and reduces the risk of knowledge loss. 26 | 27 | ## Empowered Product Teams 28 | 29 | Empowered product teams are a model for effective product development in which members are not simply following requirements handed to them by management; instead, they have the autonomy to solve business problems creatively and collaboratively. This empowerment is crucial in the context of DDD, where understanding the domain and being able to iterate on the domain model in response to changing business needs is key. 30 | 31 | Empowered product teams take ownership of outcomes rather than just outputs. This means that they are not simply tasked with "delivering features" but with solving real business problems in the best possible way. In a DDD context, this aligns perfectly because empowered teams are responsible for exploring and refining the domain, continually iterating on the bounded contexts they own, and making informed decisions about how best to model the domain. 32 | 33 | To be empowered effectively, these teams need three core components: 34 | 35 | 1. **Strong Product Leadership**: Product managers who understand both the user and business needs are crucial in guiding empowered teams. In DDD, this role is vital for maintaining alignment between the software model and the strategic goals of the organization. 36 | 37 | 2. **Autonomy**: Teams should have the freedom to decide how to achieve their objectives. In DDD, this translates into autonomy over designing the domain model, implementing bounded contexts, and iterating based on user feedback and business evolution. 38 | 39 | 3. **Clear Outcomes**: Empowered teams need to understand the "why" behind their work. In DDD, this means having a clear vision of what the business is trying to achieve and how the domain model supports that vision. 40 | 41 | This approach encourages teams to embrace experimentation, fail fast, and learn continuously, all of which are essential in a domain-driven environment where understanding evolves over time. 42 | 43 | ## Best Practices for Cross-Functional and Empowered Teams in DDD 44 | 45 | 1. **Align Teams with Business Domains**: Organize cross-functional teams around bounded contexts that reflect real-world business domains. This alignment ensures that teams can develop a deep understanding of their domain, leading to better domain models. 46 | 47 | 2. **Foster Shared Language**: Use the **Ubiquitous Language** of DDD to ensure that all members of the team—from developers to business experts—speak the same language when discussing domain concepts. This reduces misunderstandings and promotes collaboration. 48 | 49 | 3. **Encourage Autonomy and Ownership**: Empower teams to make decisions about their bounded contexts. This includes modeling the domain, defining interfaces, and deciding how to evolve their bounded context as requirements change. 50 | 51 | 4. **Prioritize Collaborative Modeling**: Use collaborative modeling techniques like **EventStorming** and **Domain Storytelling** to bring the whole team together to explore and understand the domain. This helps in building a shared understanding and uncovering edge cases that might otherwise be missed. 52 | 53 | 5. **Iterate Continuously**: Domain-Driven Design is an iterative process. Empowered teams are best positioned to iterate on domain models, as they have the autonomy to test, learn, and refine their understanding of the domain based on feedback and evolving requirements. 54 | 55 | ## Avoiding Common Pitfalls 56 | 57 | ### 1. **Siloed Expertise** 58 | 59 | One of the biggest pitfalls in software development, particularly in the context of DDD, is siloed expertise. Cross-functional teams help mitigate this risk, but it requires genuine collaboration—not just a collection of roles. Domain experts need to engage deeply with developers, and developers need to understand the business logic beyond the code. 60 | 61 | ### 2. **Lack of Empowerment** 62 | 63 | Teams that lack true empowerment often struggle to make effective decisions about the domain model. When teams are merely executing predefined requirements without understanding the "why," they are unable to apply domain insights effectively. Empowering teams allows them to take initiative and adjust their models as they learn more about the domain. 64 | 65 | ### 3. **Misaligned Boundaries** 66 | 67 | In DDD, aligning bounded contexts with business domains is crucial for reducing coupling and ensuring that teams can evolve independently. Misaligned boundaries can lead to teams that are too dependent on each other, slowing down development and reducing responsiveness to changes. Cross-functional teams should take ownership of well-defined contexts, ensuring clear boundaries and minimal dependencies. 68 | 69 | ## Conclusion 70 | 71 | Cross-functional teams, when empowered and aligned with Domain-Driven Design principles, are instrumental in building software that closely reflects business needs. The combination of deep domain knowledge, collaborative modeling, and the autonomy to iterate and refine models makes these teams highly effective. By adopting the principles of empowered product teams, organizations can create a culture where cross-functional teams are not just delivery units but are actively shaping the business through well-aligned and thoughtful software design. 72 | 73 | To succeed with DDD, it’s essential to invest in cross-functional, empowered teams that own their bounded contexts, are deeply aligned with the business, and are equipped to respond to changing requirements. This approach not only ensures better software but also creates a more motivated and capable team, capable of driving business success through meaningful software development. 74 | 75 | ### References 76 | 77 | - Cagan, M. (2018). _Inspired: How To Create Tech Products Customers Love_. Silicon Valley Product Group. 78 | - Brandolini, A. (2014). _Introducing EventStorming: An act of deliberate collective learning_. 79 | -------------------------------------------------------------------------------- /knowledgebase/concepts/best-practises/encapsulation.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/knowledgebase/concepts/best-practises/encapsulation.md -------------------------------------------------------------------------------- /knowledgebase/concepts/best-practises/interfaces.md: -------------------------------------------------------------------------------- 1 | # Maintaining Clear Interfaces Between Bounded Contexts 2 | 3 | ## **Table of Contents** 4 | 5 | - [Maintaining Clear Interfaces Between Bounded Contexts](#maintaining-clear-interfaces-between-bounded-contexts) 6 | - [**Table of Contents**](#table-of-contents) 7 | - [**Introduction**](#introduction) 8 | - [**Understanding Bounded Contexts and Interfaces**](#understanding-bounded-contexts-and-interfaces) 9 | - [**The Importance of Clear Interfaces**](#the-importance-of-clear-interfaces) 10 | - [**Best Practices for Defining Explicit Interfaces**](#best-practices-for-defining-explicit-interfaces) 11 | - [**Define Clear Contracts**](#define-clear-contracts) 12 | - [**Use Standard Communication Protocols**](#use-standard-communication-protocols) 13 | - [**Encapsulate Internal Implementations**](#encapsulate-internal-implementations) 14 | - [**Document Interfaces Thoroughly**](#document-interfaces-thoroughly) 15 | - [**Version Interfaces Carefully**](#version-interfaces-carefully) 16 | - [**Align with Business Capabilities**](#align-with-business-capabilities) 17 | - [**Integration Patterns and Relationship Types**](#integration-patterns-and-relationship-types) 18 | - [**Open Host Service**](#open-host-service) 19 | - [**Published Language**](#published-language) 20 | - [**Anti-Corruption Layer**](#anti-corruption-layer) 21 | - [**Examples Where This Approach Fits**](#examples-where-this-approach-fits) 22 | - [**Example 1: Microservices Architecture**](#example-1-microservices-architecture) 23 | - [**Example 2: Legacy System Integration**](#example-2-legacy-system-integration) 24 | - [**Challenges and Solutions**](#challenges-and-solutions) 25 | - [**Handling Changes in Interfaces**](#handling-changes-in-interfaces) 26 | - [**Managing Complexity**](#managing-complexity) 27 | - [**Conclusion**](#conclusion) 28 | 29 | ## **Introduction** 30 | 31 | In **Domain-Driven Design (DDD)**, maintaining clear and explicit interfaces between **bounded contexts** is essential for facilitating communication and integration within complex software systems. By defining well-structured interfaces, teams can ensure that interactions between different parts of the system are seamless, reducing coupling and enhancing scalability. 32 | 33 | This article explores the importance of maintaining clear interfaces, provides best practices for defining explicit interfaces between bounded contexts, discusses relevant integration patterns and relationship types, and offers examples to illustrate the concept. 34 | 35 | ## **Understanding Bounded Contexts and Interfaces** 36 | 37 | A **bounded context** is a logical boundary within which a particular domain model applies consistently. Within a bounded context, the language, definitions, and models are unified, preventing ambiguity. 38 | 39 | An **interface** in this context refers to the defined means by which one bounded context communicates with another. Interfaces can be: 40 | 41 | - **Technical Interfaces:** Such as APIs, messaging protocols, or service endpoints. 42 | - **Conceptual Interfaces:** Agreements on how data and commands are structured and interpreted. 43 | 44 | Maintaining clear interfaces ensures that bounded contexts remain decoupled, allowing them to evolve independently while still collaborating effectively. 45 | 46 | ## **The Importance of Clear Interfaces** 47 | 48 | **Facilitating Communication and Integration:** 49 | 50 | - **Reduced Coupling:** Clear interfaces prevent tight coupling between bounded contexts, allowing for independent development and deployment. 51 | - **Consistency:** Ensures that data exchanged between contexts is consistent and adheres to agreed-upon formats and protocols. 52 | - **Scalability:** Systems can scale more easily when interactions are well-defined and predictable. 53 | - **Maintainability:** Simplifies debugging and updating interfaces without affecting internal implementations. 54 | 55 | **Example:** In an online marketplace, the "Payment Processing" context interacts with the "Order Management" context via a well-defined interface, ensuring that payment confirmations are reliably communicated. 56 | 57 | ## **Best Practices for Defining Explicit Interfaces** 58 | 59 | ### **Define Clear Contracts** 60 | 61 | **Explicit Agreements:** 62 | 63 | - **Contract Specifications:** Clearly define what services are offered, input and output data formats, and expected behaviors. 64 | - **Use Interface Definition Languages (IDLs):** Such as OpenAPI/Swagger for RESTful APIs or Protocol Buffers for gRPC services. 65 | 66 | **Example:** The "User Authentication" context exposes an API endpoint `/authenticate` that accepts credentials and returns a token, with the contract specifying the exact request and response formats. 67 | 68 | ### **Use Standard Communication Protocols** 69 | 70 | **Consistency in Communication:** 71 | 72 | - **Common Protocols:** Employ widely accepted protocols like REST, gRPC, or AMQP. 73 | - **Interoperability:** Facilitates integration with different technologies and platforms. 74 | 75 | **Example:** All bounded contexts use RESTful APIs with JSON payloads, simplifying integration and reducing the need for custom parsers. 76 | 77 | ### **Encapsulate Internal Implementations** 78 | 79 | **Hide Internal Details:** 80 | 81 | - **Abstraction:** Do not expose internal domain models or database schemas. 82 | - **Boundary Protection:** Ensure that changes within a context do not leak out and affect others. 83 | 84 | **Example:** The "Inventory Management" context provides endpoints for stock queries without revealing its internal data structures or processing logic. 85 | 86 | ### **Document Interfaces Thoroughly** 87 | 88 | **Clarity and Transparency:** 89 | 90 | - **Comprehensive Documentation:** Provide clear documentation for all interfaces, including usage examples and error handling. 91 | - **Accessible Resources:** Make documentation easily accessible to all teams involved. 92 | 93 | **Example:** An internal developer portal hosts API documentation generated from annotations in the codebase, ensuring it's always up-to-date. 94 | 95 | ### **Version Interfaces Carefully** 96 | 97 | **Manage Changes Over Time:** 98 | 99 | - **Versioning Strategies:** Implement versioning to handle updates without breaking existing integrations. 100 | - **Deprecation Policies:** Clearly communicate timelines for deprecating old versions. 101 | 102 | **Example:** The "Customer Data" context maintains `/v1/customers` and `/v2/customers` endpoints, allowing consuming contexts to migrate at their own pace. 103 | 104 | ### **Align with Business Capabilities** 105 | 106 | **Reflect Business Needs:** 107 | 108 | - **Business-Oriented Interfaces:** Design interfaces that represent business actions and data, not technical implementations. 109 | - **Domain Language:** Use the ubiquitous language in interface definitions. 110 | 111 | **Example:** An interface method `submitOrder` aligns with the business action of submitting an order, making it intuitive for both developers and business stakeholders. 112 | 113 | ## **Integration Patterns and Relationship Types** 114 | 115 | ### **Open Host Service** 116 | 117 | **Definition:** 118 | 119 | An **Open Host Service** pattern exposes a bounded context's functionality through a well-defined interface, allowing other contexts to interact with it in a standardized way. 120 | 121 | **Benefits:** 122 | 123 | - **Standardization:** Provides a common way to access services. 124 | - **Scalability:** Multiple consumers can use the service without custom integrations. 125 | 126 | **Example:** 127 | 128 | The "Billing" context offers an Open Host Service with endpoints for creating invoices, processing payments, and querying billing history. 129 | 130 | ### **Published Language** 131 | 132 | **Definition:** 133 | 134 | A **Published Language** is a shared language or data model that multiple bounded contexts use to communicate, ensuring consistency in data interpretation. 135 | 136 | **Benefits:** 137 | 138 | - **Consistency:** Reduces translation errors between contexts. 139 | - **Collaboration:** Encourages agreement on data formats and structures. 140 | 141 | **Example:** 142 | 143 | Contexts agree on a common JSON schema for "Customer" data, using the same field names and data types across all interfaces. 144 | 145 | ### **Anti-Corruption Layer** 146 | 147 | **Definition:** 148 | 149 | An **Anti-Corruption Layer (ACL)** acts as a translator between two bounded contexts with different models, preventing one context's model from corrupting another's. 150 | 151 | **Benefits:** 152 | 153 | - **Isolation:** Protects the integrity of each context's domain model. 154 | - **Adaptation:** Allows integration without forcing changes in either context. 155 | 156 | **Example:** 157 | 158 | When integrating with a third-party CRM system, an ACL translates external customer data into the internal format used by the "Customer Management" context. 159 | 160 | ## **Examples Where This Approach Fits** 161 | 162 | ### **Example 1: Microservices Architecture** 163 | 164 | **Scenario:** 165 | 166 | An organization adopts a microservices architecture, with each service representing a bounded context. 167 | 168 | **Implementation:** 169 | 170 | - **Clear APIs:** Each microservice exposes its functionality through well-defined RESTful APIs. 171 | - **Service Discovery:** Uses a registry to locate services, facilitating communication. 172 | - **Standard Protocols:** All services communicate over HTTP/HTTPS with JSON payloads. 173 | 174 | **Benefits:** 175 | 176 | - **Independent Deployment:** Services can be updated or scaled independently. 177 | - **Ease of Integration:** New services can easily integrate using the standard interfaces. 178 | 179 | ### **Example 2: Legacy System Integration** 180 | 181 | **Scenario:** 182 | 183 | A company needs to integrate a new application with an existing legacy system that uses outdated protocols. 184 | 185 | **Implementation:** 186 | 187 | - **Anti-Corruption Layer:** Introduce an ACL that translates between the legacy system's protocols and the new application's interfaces. 188 | - **Published Language:** Define a common data model that both systems can understand. 189 | 190 | **Benefits:** 191 | 192 | - **Smooth Integration:** The new application communicates seamlessly without altering the legacy system. 193 | - **Model Integrity:** The new application's domain model remains clean and unaffected by legacy complexities. 194 | 195 | ## **Challenges and Solutions** 196 | 197 | ### **Handling Changes in Interfaces** 198 | 199 | **Challenge:** 200 | 201 | Updating interfaces can lead to breaking changes, affecting consuming contexts. 202 | 203 | **Solutions:** 204 | 205 | - **Backward Compatibility:** Design interfaces to be backward compatible where possible. 206 | - **Versioning:** Implement versioning strategies to allow coexistence of old and new interfaces. 207 | - **Communication:** Notify consuming teams in advance and provide migration support. 208 | 209 | ### **Managing Complexity** 210 | 211 | **Challenge:** 212 | 213 | Defining and maintaining interfaces across many contexts can become complex. 214 | 215 | **Solutions:** 216 | 217 | - **Standardization:** Use common tools and frameworks for defining and documenting interfaces. 218 | - **Automation:** Employ CI/CD pipelines to automate testing and deployment of interfaces. 219 | - **Governance:** Establish guidelines and review processes for interface changes. 220 | 221 | ## **Conclusion** 222 | 223 | Maintaining clear and explicit interfaces between bounded contexts is a critical practice in Domain-Driven Design that facilitates effective communication and integration within complex systems. By defining well-structured interfaces, employing appropriate integration patterns, and adhering to best practices, organizations can build scalable, maintainable, and flexible software systems. 224 | 225 | Clear interfaces enable bounded contexts to remain decoupled yet collaborative, allowing teams to focus on their specific domains while ensuring the system as a whole functions cohesively. Embracing this approach leads to improved agility, easier integration, and a stronger alignment between technical implementations and business needs. 226 | -------------------------------------------------------------------------------- /knowledgebase/concepts/best-practises/robustdocument.md: -------------------------------------------------------------------------------- 1 | # Robust Documentation in Domain-Driven Design: A Comprehensive Approach 2 | 3 | ## Introduction 4 | 5 | In the realm of software development, robust documentation is often undervalued but is critical to the success of a project. Within the context of Domain-Driven Design (DDD), documentation plays an even more pivotal role. It helps bridge the gap between domain experts, developers, and stakeholders, facilitating a shared understanding that is crucial for effective design and delivery. Comprehensive documentation for each bounded context—including its purpose, models, interfaces, and integration points—provides a solid foundation for building scalable, maintainable, and cohesive software systems. This article delves into best practices for creating and maintaining such documentation, highlighting its benefits and offering practical insights. 6 | 7 | ## The Purpose of Documentation in DDD 8 | 9 | In Domain-Driven Design, documentation serves as a living artifact that reflects the shared understanding of the domain across teams. It is not just a technical necessity but also a tool to foster alignment between various stakeholders—from developers to domain experts to business leaders. In a DDD context, every bounded context represents a distinct part of the domain, and documenting each context comprehensively is essential for ensuring clarity and consistency throughout the software system. 10 | 11 | Comprehensive documentation of a bounded context should encompass: 12 | 13 | 1. **Purpose and Scope**: Clearly define the purpose of the bounded context and its role within the larger domain. This helps in aligning stakeholders and provides a reference point when evolving the system. 14 | 2. **Domain Models**: Describe the domain models that exist within the context, including entities, value objects, and aggregates. This information is the result of visual and collaborative modeling, ensuring that all stakeholders have contributed to and understand the shared language and concepts that underpin the system, making it easier for new team members or stakeholders to grasp the domain quickly. 15 | 3. **Interfaces and APIs**: Document all interfaces and APIs that the bounded context provides or consumes. This includes public endpoints, messaging channels, or any other means of interaction. Clear interface documentation is critical for ensuring smooth integration between contexts. Additionally, a good versioning concept is required for managing changes over time without breaking integrations. Different types of versioning can be employed, such as: 16 | - **Semantic Versioning**: Using a version number format like `MAJOR.MINOR.PATCH`, where increments indicate the type of changes made (e.g., breaking changes, backward-compatible additions, or patches). 17 | - **Date-Based Versioning**: Using the date as part of the version identifier (e.g., `2023.04`), which can be useful for communicating the release timeline and ensuring regular updates. 18 | - **Sequential Versioning**: Assigning simple incrementing numbers to versions (e.g., `v1`, `v2`), which is often used for internal APIs where simplicity is prioritized. 19 | 4. **Integration Points**: Specify how the bounded context integrates with other bounded contexts or external systems. This could be through domain events, synchronous calls, shared kernels, or other interaction patterns. Documenting these details helps in avoiding miscommunication and misunderstandings during integration efforts. Context mapping can be particularly useful here to visualize the relationships between bounded contexts and provide clarity on the interactions. 20 | 21 | ## Best Practices for Robust Documentation 22 | 23 | ### 1. **Maintain Context-Specific Documentation** 24 | 25 | Each bounded context should have its own dedicated documentation that focuses solely on its domain, models, and integration points. This approach keeps documentation manageable, makes it easier to update, and avoids the confusion that comes from bloated, generalized documentation. Bounded contexts exist because they encapsulate specific parts of the domain, and the documentation should reflect this separation by being self-contained and highly relevant. 26 | 27 | ### 2. **Use Ubiquitous Language** 28 | 29 | The **Ubiquitous Language** is a key tenet of DDD. Documentation should use the same language that the domain experts, developers, and other stakeholders use in daily discussions. This ensures that the terms and definitions are consistent throughout the project, which helps reduce misunderstandings. When all documentation adheres to the ubiquitous language, onboarding new team members becomes significantly easier, and misinterpretations are minimized. 30 | 31 | ### 3. **Focus on the Why and the How** 32 | 33 | Effective documentation not only covers "what" exists in the system but also provides context for "why" certain decisions were made and "how" the bounded context fits within the larger domain. This is particularly important for modeling decisions, integration strategies, and domain rules. Including the rationale behind these choices helps future developers or architects understand the context and makes it easier for teams to extend or modify the system with confidence. 34 | 35 | ### 4. **Keep Documentation Up-to-Date** 36 | 37 | Documentation that lags behind the implementation is worse than having no documentation at all, as it can mislead developers and stakeholders. In a DDD context, bounded contexts evolve alongside the business, which means that keeping documentation updated is essential. One way to ensure this is to incorporate documentation updates as part of the definition of done for any feature or change. Automating aspects of documentation, such as API specs, can also reduce the maintenance burden. 38 | 39 | ### 5. **Visualize Relationships and Integration Points** 40 | 41 | Diagrams can be incredibly useful in understanding the relationships between bounded contexts and their integration points. Tools like context maps or sequence diagrams should be used to visualize how different contexts interact with each other. Visuals help communicate complex interactions and provide a high-level understanding that textual documentation alone may not effectively convey. These diagrams are invaluable during integration discussions or system evolution planning. 42 | 43 | ### 6. **Capture Domain Events and Business Rules** 44 | 45 | Bounded contexts often interact through domain events, and documenting these events is vital. Each domain event should have a description that includes its trigger, data, and downstream impact. Similarly, key business rules within the bounded context should be captured and documented. This level of detail is crucial for ensuring that the domain logic is well understood and can be reliably extended or modified. 46 | 47 | ### 7. **Leverage Collaborative Documentation Techniques** 48 | 49 | Documentation in a DDD environment should be a collaborative effort. Collaborative modeling sessions, such as **EventStorming**, are a great way to gather information for documentation. By involving domain experts, product managers, and developers, you ensure that all perspectives are captured, resulting in more accurate and complete documentation. Furthermore, the product manager often plays the role of the **Domain Expert** in product development. They are responsible for deeply understanding the domain and transferring this knowledge to the development team, making them a critical contributor to documentation. 50 | 51 | ## Benefits of Robust Documentation 52 | 53 | 1. **Facilitates Team Alignment**: Documentation provides a shared reference point, which ensures that everyone—from developers to business stakeholders—is on the same page. It also helps avoid the dreaded "tribal knowledge" scenario, where only a few individuals possess critical information. 54 | 55 | 2. **Supports Independent Team Evolution**: In DDD, each bounded context should ideally be able to evolve independently. Comprehensive documentation enables teams to understand integration points, minimizing the need for constant communication between teams and reducing the risk of unintended side effects during changes. 56 | 57 | 3. **Accelerates Onboarding**: When new developers join a team, robust documentation drastically reduces the time required for onboarding. It allows them to understand the domain, the key models, and the interfaces more quickly, thereby making them productive sooner. 58 | 59 | 4. **Reduces Technical Debt**: Lack of documentation or poorly maintained documentation often results in misunderstandings, errors, and increased technical debt. By documenting each bounded context thoroughly, the team reduces the risk of accumulating debt and ensures that changes to the system are made with a full understanding of the domain. 60 | 61 | ## Common Pitfalls to Avoid 62 | 63 | ### 1. **Over-Documenting** 64 | 65 | It’s possible to fall into the trap of over-documenting. The goal is not to document every line of code or every minor decision but rather to focus on the key aspects that convey domain understanding and facilitate integration effectively. Documentation should provide value by highlighting critical components like domain models, integration points, and business rules, while avoiding unnecessary details that add little benefit. Overly detailed documentation can become cumbersome to maintain, leading to outdated or incorrect information, which ultimately reduces its usefulness. Strive to create concise, value-driven documentation that supports comprehension and collaboration without overwhelming the team with excessive details. 66 | 67 | ### 2. **Siloed Documentation** 68 | 69 | Documentation should not exist in silos, accessible to only a few members of the team. Ensuring that documentation is available in a shared, easily accessible location is key. It should be centrally organized so that all team members, regardless of their role or expertise, can access, update, and benefit from it. By making documentation universally accessible, teams can reduce barriers to information, foster transparency, and ensure that everyone is working with the most current and accurate details. Collaborative documentation tools can be utilized to store and share information, but it's crucial to establish consistent guidelines for its maintenance and usage, ensuring it remains a valuable and trusted resource. 70 | 71 | ### 3. **Lack of Context-Specific Detail** 72 | 73 | Documentation that is too generic can be as harmful as having no documentation at all. It lacks the necessary details that developers need to make informed decisions, leading to confusion and incorrect assumptions. Inadequate documentation often results in misunderstandings during integration, poor alignment between teams, and a greater likelihood of introducing defects. When documentation is not specific enough, developers may struggle to understand the unique aspects of a bounded context, leading to increased dependency on oral communication, which is prone to loss of details and misinterpretation. This can slow down development, increase the burden on domain experts, and ultimately degrade team productivity and morale. Each bounded context should have documentation that is highly specific to its purpose, models, and integration points, ensuring that developers have a clear understanding of what they are dealing with, minimizing the chances of making incorrect assumptions, and enabling smoother collaboration across teams. 74 | 75 | ## Conclusion 76 | 77 | Robust documentation is an integral part of Domain-Driven Design and is crucial for the success of any software system, particularly when managing multiple bounded contexts. Comprehensive documentation helps to clearly define the purpose of each bounded context, details the domain models, interfaces, and integration points, and ensures that information remains accessible and actionable for all stakeholders. By focusing on these aspects and keeping the documentation continuously up-to-date, teams can foster alignment across different roles, reduce misunderstandings, and mitigate technical debt. Furthermore, comprehensive documentation supports the independent evolution of bounded contexts, allowing teams to iterate and adapt without excessive dependencies or miscommunication. The product manager, acting as the domain expert, plays a pivotal role in gathering domain knowledge and effectively transferring it to the development team, ensuring that documentation accurately reflects the business domain. Collaborative efforts from all stakeholders make documentation a vital tool in driving the overall success of DDD initiatives, facilitating better decision-making, efficient onboarding, and sustainable system evolution. 78 | -------------------------------------------------------------------------------- /knowledgebase/concepts/strategic-concepts/ubiquitouslanguage.md: -------------------------------------------------------------------------------- 1 | # Ubiquitous Language in Domain-Driven Design 2 | 3 | ## **Table of Contents** 4 | 5 | 1. [Introduction](#introduction) 6 | 2. [What is Ubiquitous Language?](#what-is-ubiquitous-language) 7 | 3. [Importance of Ubiquitous Language in DDD](#importance-of-ubiquitous-language-in-ddd) 8 | 4. [Developing a Ubiquitous Language](#developing-a-ubiquitous-language) 9 | 5. [Maintaining Ubiquitous Language](#maintaining-ubiquitous-language) 10 | 6. [Challenges and Solutions](#challenges-and-solutions) 11 | 7. [Best Practices](#best-practices) 12 | 8. [Examples](#examples) 13 | 9. [Conclusion](#conclusion) 14 | 10. [Further References and Resources](#further-references-and-resources) 15 | 16 | ## **Introduction** 17 | 18 | In complex software development projects, aligning technical teams with business stakeholders is crucial for success. **Ubiquitous Language** is a foundational concept in **Domain-Driven Design (DDD)** that bridges the gap between developers and domain experts. This article explores the essence of Ubiquitous Language, its significance in DDD, and strategies to develop and maintain it effectively. 19 | 20 | ## **What is Ubiquitous Language?** 21 | 22 | **Ubiquitous Language** is a common, shared language that is rigorously used by all team members—developers, domain experts, and stakeholders—to describe the domain model. It ensures that everyone involved has a consistent understanding of the terms, concepts, and processes within the project. 23 | 24 | ### **Key Characteristics:** 25 | 26 | - **Shared Understanding:** All team members use the same terminology, reducing misunderstandings. 27 | - **Precision:** Terms are defined clearly and unambiguously. 28 | - **Consistency:** Language remains uniform across documentation, code, conversations, and models. 29 | - **Evolves with the Domain:** As the domain understanding deepens, the language adapts accordingly. 30 | 31 | ## **Importance of Ubiquitous Language in DDD** 32 | 33 | Implementing a Ubiquitous Language offers several benefits that enhance the effectiveness of Domain-Driven Design: 34 | 35 | ### **1. Enhances Communication** 36 | 37 | - **Clarity:** Reduces ambiguity by ensuring everyone uses the same terms. 38 | - **Efficiency:** Streamlines discussions and decision-making processes. 39 | - **Collaboration:** Fosters better teamwork between technical and non-technical members. 40 | 41 | ### **2. Improves Domain Model Alignment** 42 | 43 | - **Relevance:** Ensures the software model accurately reflects business concepts. 44 | - **Consistency:** Maintains uniformity between the model and the codebase. 45 | - **Adaptability:** Facilitates easier updates as business requirements evolve. 46 | 47 | ### **3. Reduces Complexity and Errors** 48 | 49 | - **Minimizes Misinterpretations:** Clear language prevents misunderstandings that could lead to errors. 50 | - **Simplifies Maintenance:** Consistent terminology makes the codebase easier to navigate and maintain. 51 | 52 | ## **Developing a Ubiquitous Language** 53 | 54 | Creating a Ubiquitous Language involves a collaborative and iterative process: 55 | 56 | ### **1. Collaborative Workshops** 57 | 58 | - **Domain Experts and Developers:** Facilitate sessions where both groups can discuss and define key terms. 59 | - **Brainstorming Sessions:** Identify and agree upon essential vocabulary. 60 | 61 | ### **2. Define Clear Terms** 62 | 63 | - **Glossary Creation:** Develop a comprehensive glossary of terms with precise definitions. 64 | - **Avoid Jargon:** Use language that is accessible to all team members, avoiding unnecessary technical jargon. 65 | 66 | ### **3. Integrate into All Artifacts** 67 | 68 | - **Documentation:** Ensure all documents, specifications, and manuals use the Ubiquitous Language. 69 | - **Codebase:** Reflect the language in class names, method names, variables, and comments. 70 | - **Communication Channels:** Use the language consistently in meetings, emails, and chats. 71 | 72 | ### **4. Continuous Refinement** 73 | 74 | - **Feedback Loops:** Regularly solicit feedback to refine and update the language. 75 | - **Adapt to Changes:** Modify the language as new insights and requirements emerge. 76 | 77 | ## **Maintaining Ubiquitous Language** 78 | 79 | Sustaining a Ubiquitous Language requires ongoing effort and vigilance: 80 | 81 | ### **1. Governance and Ownership** 82 | 83 | - **Language Stewards:** Assign team members responsible for maintaining and updating the language. 84 | - **Standardization:** Establish guidelines for introducing and modifying terms. 85 | 86 | ### **2. Integration into Development Processes** 87 | 88 | - **Code Reviews:** Ensure adherence to the Ubiquitous Language during code reviews. 89 | - **Testing:** Align test cases and scenarios with the defined language. 90 | 91 | ### **3. Documentation and Training** 92 | 93 | - **Comprehensive Documentation:** Keep the glossary and related documents up-to-date. 94 | - **Onboarding Programs:** Train new team members in the Ubiquitous Language as part of their onboarding. 95 | 96 | ### **4. Monitoring and Enforcement** 97 | 98 | - **Regular Audits:** Periodically review the use of language across all project artifacts. 99 | - **Encourage Adoption:** Foster a culture that values and adheres to the Ubiquitous Language. 100 | 101 | ## **Challenges and Solutions** 102 | 103 | ### **1. Resistance to Change** 104 | 105 | - **Solution:** Demonstrate the benefits through incremental adoption and involve team members in the language development process. 106 | 107 | ### **2. Diverse Backgrounds** 108 | 109 | - **Solution:** Facilitate inclusive discussions that respect and incorporate different perspectives and expertise levels. 110 | 111 | ### **3. Language Drift** 112 | 113 | - **Solution:** Implement regular reviews and establish language governance to prevent divergence from the agreed-upon terms. 114 | 115 | ### **4. Scaling Across Teams** 116 | 117 | - **Solution:** Ensure clear communication and provide comprehensive documentation to maintain consistency as the team grows. 118 | 119 | ## **Best Practices** 120 | 121 | - **Start Early:** Begin developing the Ubiquitous Language from the project's inception. 122 | - **Be Iterative:** Allow the language to evolve naturally as understanding deepens. 123 | - **Encourage Participation:** Involve all relevant stakeholders in language development and maintenance. 124 | - **Keep It Simple:** Strive for clarity and simplicity to ensure the language is easily adoptable. 125 | - **Embed in Culture:** Make the Ubiquitous Language a fundamental part of the team's culture and daily practices. 126 | 127 | ## **Examples** 128 | 129 | ### **E-commerce Platform** 130 | 131 | - **Terms:** 132 | - **Order:** Represents a customer's request to purchase products. 133 | - **Cart:** A temporary collection of items a customer intends to buy. 134 | - **Checkout:** The process of finalizing an order. 135 | - **Inventory:** The available stock of products. 136 | - **Usage:** 137 | - **In Code:** `OrderService`, `CartController`, `InventoryRepository` 138 | - **In Conversations:** "Let's review the order placement workflow," "Update the inventory levels after checkout." 139 | 140 | ### **Healthcare System** 141 | 142 | - **Terms:** 143 | - **Patient:** An individual receiving medical care. 144 | - **Appointment:** A scheduled meeting between a patient and a healthcare provider. 145 | - **Diagnosis:** The identification of a disease or condition. 146 | - **Treatment Plan:** A prescribed course of action to address a diagnosis. 147 | - **Usage:** 148 | - **In Code:** `PatientRepository`, `AppointmentScheduler`, `DiagnosisService` 149 | - **In Conversations:** "Ensure the treatment plan is updated after diagnosis," "Schedule the patient's appointment." 150 | 151 | ## **Conclusion** 152 | 153 | Ubiquitous Language is a cornerstone of Domain-Driven Design, fostering clear communication and ensuring that the software model remains closely aligned with business objectives. By collaboratively developing and diligently maintaining a shared language, teams can enhance their understanding, reduce complexity, and build more effective and adaptable software systems. Embracing Ubiquitous Language not only bridges the gap between technical and non-technical stakeholders but also drives the success of complex projects through unified vision and purpose. 154 | 155 | ## **Further References and Resources** 156 | 157 | ### **Books:** 158 | 159 | - _Domain-Driven Design: Tackling Complexity in the Heart of Software_ by Eric Evans 160 | - _Implementing Domain-Driven Design_ by Vaughn Vernon 161 | - _Domain-Driven Design Distilled_ by Vaughn Vernon 162 | - _Learning Domain-Driven Design_ by Vlad Khononov 163 | 164 | ### **Blogs and Articles:** 165 | 166 | 167 | 168 | -------------------------------------------------------------------------------- /knowledgebase/concepts/tactical-concepts/factories.md: -------------------------------------------------------------------------------- 1 | # Factories in Domain-Driven Design 2 | 3 | ## **Table of Contents** 4 | 5 | 1. [Introduction](#introduction) 6 | 2. [What are Factories in DDD?](#what-are-factories-in-ddd) 7 | 3. [The Role of Factories in DDD](#the-role-of-factories-in-ddd) 8 | 4. [Types of Factories](#types-of-factories) 9 | 5. [When to Use Factories](#when-to-use-factories) 10 | 6. [Best Practices for Designing Factories](#best-practices-for-designing-factories) 11 | 7. [Common Challenges and Solutions](#common-challenges-and-solutions) 12 | 8. [Examples](#examples) 13 | 9. [Conclusion](#conclusion) 14 | 10. [Further References and Resources](#further-references-and-resources) 15 | 16 | ## **Introduction** 17 | 18 | In **Domain-Driven Design (DDD)**, ensuring the correct creation of complex domain objects is critical for maintaining consistency and adhering to business rules. **Factories** provide a means of encapsulating the process of constructing domain objects, ensuring that objects are instantiated in a valid and consistent state. This article explores the role of factories in DDD, the different types of factories, and best practices for their use. 19 | 20 | ## **What are Factories in DDD?** 21 | 22 | A **Factory** in Domain-Driven Design is a design pattern used to abstract the creation of complex domain objects. Factories are responsible for ensuring that an entity or aggregate is instantiated with all necessary attributes and business rules, leaving the rest of the domain model free from concerns about how objects are created. 23 | 24 | ### **Key Characteristics:** 25 | 26 | - **Abstraction of Creation:** Factories hide the complexity involved in constructing domain objects. 27 | - **Consistency Enforcement:** They ensure that domain invariants and business rules are adhered to during object creation. 28 | - **Reusable Logic:** Centralize object creation logic to avoid duplication across the system. 29 | 30 | ### **Example:** 31 | 32 | If an **Order** in an e-commerce system requires several parameters (e.g., customer information, order items, shipping details), a factory ensures that every order created is valid and complete, encapsulating all the necessary steps involved in its creation. 33 | 34 | ## **The Role of Factories in DDD** 35 | 36 | Factories play an essential role in DDD by ensuring that domain objects, particularly complex entities and aggregates, are created correctly and consistently. By doing so, factories help maintain the integrity of the domain model and prevent the system from entering invalid states. 37 | 38 | ### **1. Encapsulation of Complex Creation Logic** 39 | 40 | In DDD, entities or aggregates often have intricate creation processes that involve setting multiple attributes, initializing dependent objects, and adhering to business rules. Factories encapsulate this complexity, providing a clean interface for creating objects. 41 | 42 | ### **2. Ensuring Domain Invariants** 43 | 44 | Domain invariants are rules or constraints that must always hold true for an object. For instance, a bank account may have the invariant that its balance must never be negative. Factories ensure that these rules are respected from the moment the object is created, reducing the likelihood of errors or inconsistent states. 45 | 46 | ### **3. Separation of Concerns** 47 | 48 | By delegating object creation to factories, the rest of the domain model remains focused on business logic and behavior rather than construction details. This separation of concerns results in a more maintainable and understandable codebase. 49 | 50 | ### **4. Flexibility and Reusability** 51 | 52 | Factories offer flexibility in how objects are constructed and can be reused across different parts of the system. They also make it easier to handle variations in object creation, such as building objects with different configurations depending on the context. 53 | 54 | ## **Types of Factories** 55 | 56 | There are two main types of factories commonly used in Domain-Driven Design: 57 | 58 | ### **1. Factory Method** 59 | 60 | The **Factory Method** is a design pattern where the creation of an object is delegated to a method in the class itself. This pattern allows the domain object to take responsibility for some of its creation logic but still hides the complexity from the outside. 61 | 62 | - **Use Case:** Factory methods are typically used for simpler object creation, where the domain object itself can manage the instantiation with minimal complexity. 63 | 64 | ### **2. Factory Class (External Factory)** 65 | 66 | An **External Factory** (or Factory Class) is a separate object responsible for creating complex entities or aggregates. These factories are commonly used when object creation involves multiple steps, dependencies, or when the creation process requires collaboration between various objects. 67 | 68 | - **Use Case:** Factory classes are suited for creating aggregates or entities that have many dependencies or require detailed configuration to ensure consistency. 69 | 70 | ## **When to Use Factories** 71 | 72 | Factories are not always necessary for every domain object. They are most useful in the following situations: 73 | 74 | ### **1. Complex Aggregates or Entities** 75 | 76 | When an entity or aggregate has multiple attributes, dependencies, or requires specific initialization steps, a factory is the best way to encapsulate the creation process and ensure that the object starts in a valid state. 77 | 78 | ### **2. Adherence to Domain Invariants** 79 | 80 | If an object must conform to strict domain invariants from the moment it is created, a factory can enforce these rules, preventing invalid objects from being instantiated. 81 | 82 | ### **3. Aggregates with Dependencies** 83 | 84 | If an aggregate depends on other objects or services during its creation (e.g., generating a unique identifier or querying external data), a factory can manage these dependencies, ensuring the aggregate is fully constructed before it is used. 85 | 86 | ### **4. Preventing Object Construction in Application Layer** 87 | 88 | Factories are useful when you want to avoid cluttering the application layer with object construction logic. Instead, the application layer can focus on business operations, delegating object creation to factories. 89 | 90 | ## **Best Practices for Designing Factories** 91 | 92 | Designing effective factories in Domain-Driven Design requires careful consideration of the domain model and the specific requirements of object creation. 93 | 94 | ### **1. Keep Factories Focused** 95 | 96 | Factories should focus solely on the creation of domain objects. Avoid mixing business logic or other responsibilities within the factory. Keep the factory’s purpose clear: creating valid instances of domain objects. 97 | 98 | ### **2. Use Factories for Aggregate Creation** 99 | 100 | It is generally a good practice to use factories for creating aggregates. Since aggregates are the consistency boundaries in DDD, ensuring they are created correctly from the start is essential to maintaining system integrity. 101 | 102 | ### **3. Encapsulate Complex Creation** 103 | 104 | If object creation requires multiple steps, such as validation, calculation, or interaction with other services, encapsulate these steps inside the factory. This keeps the complexity hidden and ensures that the object is constructed in a consistent and valid manner. 105 | 106 | ### **4. Avoid Factories for Simple Objects** 107 | 108 | For simpler objects, such as value objects or entities with minimal attributes, factories may not be necessary. In these cases, constructors or factory methods may suffice, keeping the design simpler. 109 | 110 | ### **5. Make Factories Explicit** 111 | 112 | Factories should be explicit in what they produce. This means giving clear names to factory methods and making it obvious what type of object is being created. For example, methods like `CreateOrder` or `BuildCustomer` help clarify the factory’s purpose. 113 | 114 | ### **6. Enforce Domain Invariants in Factories** 115 | 116 | Factories should enforce domain invariants from the moment of creation. If an entity or aggregate must adhere to specific rules (e.g., an order must contain at least one line item), ensure that these rules are enforced during the object’s construction. 117 | 118 | ## **Common Challenges and Solutions** 119 | 120 | While factories simplify object creation in DDD, they also present certain challenges. Here are some common challenges and solutions for working with factories: 121 | 122 | ### **1. Overcomplicated Factories** 123 | 124 | **Challenge:** Factories can become overly complex when trying to manage too many responsibilities, leading to difficult-to-maintain code. 125 | 126 | - **Solution:** Keep factories focused solely on creation. If the factory starts becoming overly complex, consider refactoring the process into smaller, reusable components or creating helper methods. 127 | 128 | ### **2. Factories with Too Many Parameters** 129 | 130 | **Challenge:** When factories require many parameters to create an object, they can become difficult to use and error-prone. 131 | 132 | - **Solution:** Simplify the parameter list by using objects like _data transfer objects (DTOs)_, _builder patterns_, or grouping related parameters into value objects. 133 | 134 | ### **3. Testing Factories** 135 | 136 | **Challenge:** Testing factories can be difficult, especially when they involve external dependencies or complex logic. 137 | 138 | - **Solution:** Ensure that factories remain focused on object creation and delegate external dependencies to other layers. Use dependency injection to mock external services during testing. 139 | 140 | ### **4. Overuse of Factories** 141 | 142 | **Challenge:** Not every domain object needs a factory. Overusing factories can lead to unnecessary complexity. 143 | 144 | - **Solution:** Reserve factories for complex aggregates or entities that have strict invariants or require multiple dependencies. For simpler objects, use constructors or factory methods instead. 145 | 146 | ## **Examples** 147 | 148 | ### **1. Customer Factory in a CRM System** 149 | 150 | A **CustomerFactory** would be responsible for ensuring that a new `Customer` object is created with all necessary attributes, such as contact details, address, and initial settings. The factory would ensure that no customer is created without valid data and that all domain invariants are respected (e.g., a customer must have a valid email address). 151 | 152 | ### **2. Order Factory in an E-commerce System** 153 | 154 | An **OrderFactory** would handle the creation of an `Order` aggregate. The factory would ensure that each order contains at least one item, that customer information is valid, and that payment details are correctly initialized. This encapsulates all the complexity involved in creating a valid order. 155 | 156 | ### **3. Product Factory in an Inventory Management System** 157 | 158 | A **ProductFactory** would be responsible for creating a new `Product` entity, ensuring that essential attributes such as name, price, stock quantity, and category are set. The factory could enforce business rules such as ensuring the product's price is above zero and that stock quantity is valid. 159 | 160 | ## **Conclusion** 161 | 162 | In Domain-Driven Design, **Factories** play a vital role in ensuring that complex domain objects, particularly aggregates, are created in a consistent and 163 | 164 | valid state. By encapsulating the construction process and enforcing domain invariants, factories maintain the integrity of the domain model while simplifying object creation for other parts of the system. Properly designed factories focus on the creation of complex entities and aggregates, allowing the rest of the domain model to remain focused on business logic. 165 | 166 | Factories are most useful when dealing with aggregates that have multiple dependencies, strict business rules, or complex initialization processes. By adhering to best practices such as keeping factories focused, using them for aggregate creation, and enforcing domain rules, developers can ensure that factories remain a powerful and maintainable tool within the DDD framework. 167 | 168 | By understanding the role of factories in Domain-Driven Design, teams can build systems that are not only aligned with business objectives but also flexible, maintainable, and resilient. Factories are a powerful tool in the DDD toolkit, ensuring that domain objects are created correctly and consistently, laying a strong foundation for robust software systems. 169 | 170 | ## **Further References and Resources** 171 | 172 | ### **Books:** 173 | 174 | - _Domain-Driven Design: Tackling Complexity in the Heart of Software_ by Eric Evans 175 | - _Implementing Domain-Driven Design_ by Vaughn Vernon 176 | - _Domain-Driven Design Distilled_ by Vaughn Vernon 177 | - _Patterns, Principles, and Practices of Domain-Driven Design_ by Scott Millett and Nick Tune -------------------------------------------------------------------------------- /knowledgebase/concepts/tactical-concepts/images/Aggregate Testing.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/knowledgebase/concepts/tactical-concepts/images/Aggregate Testing.png -------------------------------------------------------------------------------- /knowledgebase/concepts/tactical-concepts/images/Aggregates Roots.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/knowledgebase/concepts/tactical-concepts/images/Aggregates Roots.png -------------------------------------------------------------------------------- /knowledgebase/concepts/tactical-concepts/images/Aggregates and Boundaries.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/knowledgebase/concepts/tactical-concepts/images/Aggregates and Boundaries.png -------------------------------------------------------------------------------- /knowledgebase/concepts/tactical-concepts/images/Aggregates.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/knowledgebase/concepts/tactical-concepts/images/Aggregates.png -------------------------------------------------------------------------------- /knowledgebase/concepts/tactical-concepts/images/Best Practises.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/knowledgebase/concepts/tactical-concepts/images/Best Practises.png -------------------------------------------------------------------------------- /knowledgebase/concepts/tactical-concepts/images/Domain Invariants.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/knowledgebase/concepts/tactical-concepts/images/Domain Invariants.png -------------------------------------------------------------------------------- /knowledgebase/concepts/tactical-concepts/images/Implementation.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/knowledgebase/concepts/tactical-concepts/images/Implementation.png -------------------------------------------------------------------------------- /knowledgebase/index.md: -------------------------------------------------------------------------------- 1 | # Domain-Driven Design (DDD) Concepts: A Comprehensive Overview 2 | 3 | Domain-Driven Design (DDD) is a strategic approach to software development that emphasizes aligning the software model closely with the business domain. Below is a bullet-point list of key DDD concepts, organized into strategic and tactical categories to provide a clear understanding of the framework. 4 | 5 | ## **Strategic Design Concepts** 6 | 7 | - **[Ubiquitous Language](./concepts/strategic-concepts/ubiquitouslanguage.md)** 8 | - A common, shared language between developers and domain experts. 9 | - Ensures clear communication and consistency across the model. 10 | 11 | - **[Bounded Context](./concepts/strategic-concepts/boundedcontext.md)** 12 | - Defines a clear boundary within which a specific domain model is applicable. 13 | - Prevents ambiguity by ensuring terms and concepts have consistent meanings within the context. 14 | 15 | - **[Context Mapping](./tools/contextmapping.md)** 16 | - Visual representation of how different bounded contexts interact. 17 | - Identifies integration patterns and relationships between contexts. 18 | 19 | - **[Subdomains](./concepts/strategic-concepts/domain.md#core-subdomains)** 20 | - **[Core Subdomain](./concepts/strategic-concepts/domain.md#core-subdomains):** The primary area that provides competitive advantage and is central to the business. 21 | - **[Supporting Subdomai](./concepts/strategic-concepts/domain.md#supporting-subdomains):** Assists the core subdomain but is not unique to the business. 22 | - **[Generic Subdomain](./concepts/strategic-concepts/domain.md#generic-subdomains):** Common functionalities that can often be outsourced or implemented using third-party solutions. 23 | 24 | ## **Tactical Design Concepts** 25 | 26 | - **[Entities](./concepts/tactical-concepts/entities.md)** 27 | - Objects with a distinct identity that persists over time. 28 | - Defined by their continuity rather than their attributes. 29 | 30 | - **[Value Objects](./concepts/tactical-concepts/value-objects.md)** 31 | - Immutable objects defined solely by their attributes. 32 | - Do not have a unique identity and are interchangeable if their attributes are the same. 33 | 34 | - **[Aggregates](./concepts/tactical-concepts/aggregate.md)** 35 | - Clusters of related entities and value objects treated as a single unit for data changes. 36 | - Ensures consistency and enforces business rules within the boundary. 37 | 38 | - **[Aggregate Root](./concepts/tactical-concepts/aggregate.md#aggregate-root-responsibilities)** 39 | - The primary entity within an aggregate. 40 | - Controls access to the aggregate and ensures its invariants are maintained. 41 | 42 | - **[Repositories](./concepts/tactical-concepts/repositories.md)** 43 | - Abstractions for persisting and retrieving aggregates. 44 | - Provide methods to access aggregates without exposing the underlying data storage details. 45 | 46 | - **[Factories](./concepts/tactical-concepts/factories.md)** 47 | - Responsible for creating complex aggregates. 48 | - Ensure that all invariants are satisfied during the creation process. 49 | 50 | - **[Domain Services](./concepts/tactical-concepts/domain-services.md)** 51 | - Operations that don't naturally fit within entities or value objects. 52 | - Encapsulate domain logic that involves multiple aggregates or doesn't belong to any single entity. 53 | 54 | - **[Application Services](./concepts/tactical-concepts/application-services.md)** 55 | - Coordinate tasks and delegate work to domain objects. 56 | - Handle transactions, security, and other cross-cutting concerns. 57 | 58 | - **[Domain Events](./concepts/tactical-concepts/domain-events.md)** 59 | - Represent significant occurrences within the domain. 60 | - Facilitate communication between different parts of the system in a decoupled manner. 61 | 62 | - **[Modules](./concepts/tactical-concepts/modules.md)** 63 | - Logical grouping of related concepts within a bounded context. 64 | - Helps in organizing the domain model for better maintainability. 65 | 66 | ## Methods & Tools 67 | 68 | - **[Big Picture EventStorming](./tools/bigpictureeventstorming.md)**: 69 | - Holistic Domain Exploration: Immersive workshop method for exploring and modeling an entire business domain by focusing on domain events. 70 | - Cross-Functional Collaboration: Fosters collaboration between business and technical stakeholders to uncover hidden dependencies and generate actionable insights. 71 | 72 | - **[Process and Design Level EventStorming](./tools/eventstorming.md)**: 73 | - Collaborative Exploration: Uses a workshop format to collaboratively explore and model complex business domains through domain events. 74 | - Rapid Insight Generation: Facilitates rapid knowledge sharing and identification of domain insights, inefficiencies, and improvement areas. 75 | 76 | - **[Context Mapping](./tools/contextmapping.md):** 77 | - Visualizes Relationships: Helps understand and visualize the relationships and interactions between different bounded contexts and teams. 78 | - Patterns and Best Practices: Utilizes specific patterns and best practices to manage dependencies and communication flows effectively. 79 | 80 | - **[Domain Message Flow Diagrams](./tools/domain-message-flow.md):** 81 | - Message Flow Visualization: Illustrates the flow of messages (commands, events, queries) between actors, bounded contexts, and external systems. 82 | - Dependency Identification: Helps identify dependencies, potential bottlenecks, and ensures alignment with business processes. 83 | 84 | - **[Event Modeling](./tools/eventmodelling.md):** 85 | - Focus on Data Evolution: Models how information changes over time through events, commands, views, and triggers. 86 | - Improved Collaboration: Enhances communication between technical and non-technical stakeholders by providing a clear visual blueprint of system behavior. 87 | 88 | ## **Architectural Patterns and Practices** 89 | 90 | - **[Microservices Architecture](./concepts/architectual-concepts/msa.md)** 91 | - Implements each bounded context as an independent microservice. 92 | - Enhances scalability and allows for independent deployment. 93 | 94 | - **[Modular Monolith](./concepts/architectual-concepts/modular-monolith.md)** 95 | - Organizes bounded contexts into distinct modules within a single application. 96 | - Balances separation of concerns with simpler deployment compared to microservices. 97 | 98 | - **[Event-Driven Architecture](./concepts/architectual-concepts/eda.md)** 99 | - Utilizes asynchronous events for communication between bounded contexts. 100 | - Promotes loose coupling and scalability. 101 | 102 | - **[CQRS (Command Query Responsibility Segregation)](./concepts/architectual-concepts/cqrs.md)** 103 | 104 | - Separates read and write operations into different models. 105 | - Optimizes performance and scalability by handling commands and queries independently. 106 | 107 | - **[Event Sourcing](./concepts/architectual-concepts/event-sourcing.md)** 108 | - Stores the state of a domain model as a sequence of [domain events](./concepts/tactical-concepts/domain-events.md). 109 | - Enables rebuilding of the state by replaying events and supports audit trails. 110 | 111 | - **[Architecture Modernization](./concepts/architectual-concepts/architecture-modernization.md)** 112 | - Transform legacy systems into modern, adaptable architectures aligned with business strategy and customer needs. 113 | - Focus on incremental improvements, stakeholder buy-in, and fostering collaboration for continuous innovation and efficiency. 114 | 115 | ## **Additional Concepts** 116 | 117 | - **[Anti-Patterns](./concepts/additional-concepts/antipatterns.md)** 118 | - Practices that go against DDD principles, such as Anemic Domain Model or God Objects. 119 | - Should be avoided to maintain a robust and maintainable domain model. 120 | 121 | - **[Collaborative Modeling](./concepts/additional-concepts/collaborativemodelling.md)** 122 | - Engaging domain experts and developers in the modeling process. 123 | - Ensures the model accurately reflects business realities. 124 | 125 | ## **Best Practices** 126 | 127 | - **[Align Bounded Contexts with Business Boundaries](./concepts/best-practises/aligmentbusiness.md):** Ensure that technical boundaries reflect real-world business divisions and responsibilities. 128 | 129 | - **[Keep Bounded Contexts Small and Focused](./concepts/best-practises/bcsmallfocused.md):** Smaller contexts are easier to manage, understand, and evolve. 130 | 131 | - **[Maintain Clear Interfaces](./concepts/best-practises/interfaces.md):** Define explicit interfaces for interactions between bounded contexts to facilitate communication and integration. 132 | 133 | - **[Avoid Overlapping Responsibilities](./concepts/best-practises/responsibilities.md):** Ensure each bounded context has distinct responsibilities to prevent duplication and conflicts. 134 | 135 | - **[Encourage Independent Evolution](./concepts/best-practises/evolution.md):** Design bounded contexts to evolve independently, allowing teams to iterate and improve without being hindered by other contexts. 136 | 137 | - **[Invest in Robust Documentation](./concepts/best-practises/robustdocument.md):** Maintain comprehensive documentation for each bounded context, including its purpose, models, interfaces, and integration points. 138 | 139 | - **[Foster Cross-Functional Teams](./concepts/best-practises/crossfunctionalteams.md):** Encourage collaboration between developers, domain experts, and stakeholders within each bounded context to enhance model accuracy and relevance. 140 | 141 | ## **Further References and Resources** 142 | 143 | ### **Books:** 144 | 145 | - _Domain-Driven Design: Tackling Complexity in the Heart of Software_ by Eric Evans 146 | - _Implementing Domain-Driven Design_ by Vaughn Vernon 147 | - _Domain-Driven Design Distilled_ by Vaughn Vernon 148 | - _Patterns, Principles, and Practices of Domain-Driven Design_ by Scott Millett and Nick Tune 149 | - _Learning Domain-Driven Design: Aligning Software Architecture and Business Strategy_ by Vlad Khononov 150 | 151 | ### **Links:** 152 | 153 | - [Domain-Driven Design Reference](https://www.domainlanguage.com/wp-content/uploads/2016/05/DDD_Reference_2015-03.pdf) 154 | - [Domain-Driven Design Community](https://www.dddcommunity.org/) 155 | - [Eric Evans' Official Website](https://www.domainlanguage.com/) 156 | - [DDD Crew](https://github.com/ddd-crew) 157 | -------------------------------------------------------------------------------- /knowledgebase/tools/contextmapping.md: -------------------------------------------------------------------------------- 1 | # Context Mapping in Domain-Driven Design 2 | 3 | ## **Table of Contents** 4 | 5 | - [Context Mapping in Domain-Driven Design](#context-mapping-in-domain-driven-design) 6 | - [**Table of Contents**](#table-of-contents) 7 | - [**Introduction**](#introduction) 8 | - [**Understanding Context Mapping**](#understanding-context-mapping) 9 | - [**Team Relationships in Context Mapping**](#team-relationships-in-context-mapping) 10 | - [**Mutually Dependent**](#mutually-dependent) 11 | - [**Upstream / Downstream**](#upstream--downstream) 12 | - [**Free**](#free) 13 | - [**Context Map Patterns**](#context-map-patterns) 14 | - [**Open-Host Service**](#open-host-service) 15 | - [**Conformist**](#conformist) 16 | - [**Anticorruption Layer**](#anticorruption-layer) 17 | - [**Shared Kernel**](#shared-kernel) 18 | - [**Partnership**](#partnership) 19 | - [**Customer/Supplier Development**](#customersupplier-development) 20 | - [**Published Language**](#published-language) 21 | - [**Separate Ways**](#separate-ways) 22 | - [**Big Ball of Mud**](#big-ball-of-mud) 23 | - [**Best Practices for Context Maps**](#best-practices-for-context-maps) 24 | - [**Prefer Small Context Maps for Explicit Questions**](#prefer-small-context-maps-for-explicit-questions) 25 | - [**Document and Explain the Patterns You Are Going to Use**](#document-and-explain-the-patterns-you-are-going-to-use) 26 | - [**Work with Different Perspectives and Multiple Context Maps**](#work-with-different-perspectives-and-multiple-context-maps) 27 | - [**Conclusion**](#conclusion) 28 | 29 | ## **Introduction** 30 | 31 | In **Domain-Driven Design (DDD)**, managing the complexity of large systems involves breaking down the domain into **Bounded Contexts**. However, these contexts often need to interact, and understanding the relationships and interactions between them is crucial. **Context Mapping** is a strategic design technique in DDD that provides a holistic view of how different bounded contexts and teams relate and communicate with each other. 32 | 33 | ## **Understanding Context Mapping** 34 | 35 | **Context Maps** describe the relationships between bounded contexts and the teams working on them. They provide a collection of patterns and team relationship types that help visualize and analyze the interactions within a system or across multiple systems. 36 | 37 | There are **nine context map patterns** and **three team relationship types** that offer diverse perspectives, such as service provisioning, model propagation, and governance aspects. This diversity enables teams to gain a comprehensive understanding of how different parts of the system influence each other. 38 | 39 | Context Maps can be used both for analyzing existing systems and for planning new ones. They help identify dependencies, communication flows, and potential areas of conflict or collaboration between teams and bounded contexts. 40 | 41 | ## **Team Relationships in Context Mapping** 42 | 43 | Understanding team relationships is fundamental in context mapping, as it affects how bounded contexts interact and how teams coordinate their efforts. 44 | 45 | ### **Mutually Dependent** 46 | 47 | **Definition:** Two teams or bounded contexts are **mutually dependent** when their software artifacts or systems need to be delivered together to be successful. There is a close, reciprocal link between their data, functionality, and capabilities, requiring significant communication and coordination between the teams. 48 | 49 | **Example:** In a financial services company, the **Billing Team** and the **Subscription Management Team** might be mutually dependent. The billing system relies on subscription data to generate invoices, while the subscription system needs billing information to manage account statuses. Both teams must coordinate releases and changes to ensure compatibility. 50 | 51 | ### **Upstream / Downstream** 52 | 53 | **Definition:** In an **upstream/downstream** relationship, the actions of the upstream team affect the downstream team, but not vice versa. The upstream team can succeed independently, while the downstream team's success is influenced by the upstream team's outputs. 54 | 55 | **Example:** An **Inventory Management Team** (upstream) provides product availability data to an **Order Processing Team** (downstream). Changes in the inventory system impact how orders are processed, but the order system does not affect inventory management directly. 56 | 57 | ### **Free** 58 | 59 | **Definition:** A team or bounded context is **free** when changes in other bounded contexts do not influence its success or failure. There are no organizational or technical dependencies, allowing the team to operate independently. 60 | 61 | **Example:** A **Marketing Analytics Team** develops tools to analyze campaign performance. Their work does not depend on other systems or teams, and they are free to choose their technologies and timelines without affecting or being affected by others. 62 | 63 | ## **Context Map Patterns** 64 | 65 | Context map patterns define how bounded contexts interact and the nature of their relationships. Here are the nine context map patterns, each with detailed explanations and examples. 66 | 67 | ### **Open-Host Service** 68 | 69 | **Definition:** An **Open-Host Service** provides a protocol or interface that gives access to a subsystem as a set of services. It is open so that any team needing to integrate can use it. The service is enhanced over time to handle new integration requirements, while special cases may use one-off translators to avoid complicating the shared protocol. 70 | 71 | **Example:** A **Payment Processing Service** exposes APIs for handling transactions. Multiple teams (e.g., e-commerce, subscription services) use this open-host service to process payments. The service is designed to accommodate various clients without needing direct coordination. 72 | 73 | ### **Conformist** 74 | 75 | **Definition:** In the **Conformist** pattern, a downstream team eliminates the complexity of translation between bounded contexts by strictly adhering to the upstream team's model. This simplifies integration but may limit the downstream team's flexibility. 76 | 77 | **Example:** A **Mobile App Team** conforms to the data models and APIs provided by the **Backend Services Team**. Instead of translating or adapting the data, the mobile app uses the same structures, ensuring seamless integration but potentially inheriting limitations of the backend model. 78 | 79 | ### **Anticorruption Layer** 80 | 81 | **Definition:** An **Anticorruption Layer (ACL)** is an isolating layer that provides a way for a downstream system to interact with an upstream system while preserving its own domain model. The ACL translates or adapts the upstream model to fit the downstream context. 82 | 83 | **Example:** A **Reporting System** needs data from an **ERP System** with a complex and unsuitable model. The reporting team implements an anticorruption layer that transforms ERP data into a simplified, reporting-friendly model, allowing them to maintain their own domain concepts. 84 | 85 | ### **Shared Kernel** 86 | 87 | **Definition:** A **Shared Kernel** involves an explicit boundary where teams agree to share a subset of the domain model, including code or database design. This shared part requires close collaboration and coordination to manage changes. 88 | 89 | **Example:** The **User Management Team** and the **Authentication Team** share a common user identity model. They maintain a shared kernel for user entities and related database schemas, ensuring consistency across authentication and user profile functionalities. 90 | 91 | ### **Partnership** 92 | 93 | **Definition:** In a **Partnership**, two teams have a mutual dependency where the failure of one affects the other. They collaborate closely, with joint planning and management of integration. Features are scheduled to align with shared release cycles. 94 | 95 | **Example:** A **Ride-Sharing Platform**'s **Driver Team** and **Rider Team** must work in tandem. Features like real-time location tracking require both teams to coordinate development and releases to ensure functionality works across both driver and rider applications. 96 | 97 | ### **Customer/Supplier Development** 98 | 99 | **Definition:** In a **Customer/Supplier** relationship, the downstream team's needs influence the upstream team's planning. The upstream team (supplier) accommodates the requirements of the downstream team (customer), negotiating and budgeting tasks to meet shared goals. 100 | 101 | **Example:** A **Front-End Web Team** (customer) relies on APIs provided by a **Backend API Team** (supplier). The front-end team communicates their needs, and the backend team plans their development to support those requirements, ensuring the front-end team can deliver their features. 102 | 103 | ### **Published Language** 104 | 105 | **Definition:** A **Published Language** is a well-documented, shared language used for communication between bounded contexts. It serves as a common medium, translating as necessary to ensure consistent understanding. 106 | 107 | **Example:** Teams across different services use a standard **JSON API Specification** to communicate. This published language ensures all teams interpret data structures consistently, facilitating integration without misunderstandings. 108 | 109 | ### **Separate Ways** 110 | 111 | **Definition:** When bounded contexts have no significant relationship, they follow **Separate Ways**, operating independently. This allows teams to find specialized solutions within their scope without the need for integration. 112 | 113 | **Example:** A **Human Resources System** and a **Manufacturing Control System** in a company may have no overlap. Each operates separately, using different technologies and models suited to their specific needs without any dependency. 114 | 115 | ### **Big Ball of Mud** 116 | 117 | **Definition:** A **Big Ball of Mud** refers to a system or bounded context with a disorganized structure, mixed models, and inconsistent boundaries. It represents poor quality and a lack of clear design. 118 | 119 | **Example:** An old **Legacy System** that has been patched over years without proper architecture becomes a big ball of mud. Teams working on new systems implement strategies to prevent this messy model from contaminating other contexts, such as by isolating it behind anticorruption layers. 120 | 121 | ## **Best Practices for Context Maps** 122 | 123 | Effectively using context maps requires careful planning and consideration. Here are some best practices to follow: 124 | 125 | ### **Prefer Small Context Maps for Explicit Questions** 126 | 127 | Large context maps can become overwhelming and hard to interpret. Instead, create small, focused context maps aimed at answering specific questions or addressing particular concerns. 128 | 129 | **Example:** If you want to understand how data flows between the **Order Management System** and the **Inventory System**, create a context map focusing solely on these two bounded contexts and their relationship. 130 | 131 | ### **Document and Explain the Patterns You Are Going to Use** 132 | 133 | Not all stakeholders may be familiar with context mapping patterns. Before presenting a context map, decide which patterns you will use and provide clear explanations and examples for each. 134 | 135 | **Example:** When presenting to a mixed audience of developers and business analysts, include a brief guide explaining patterns like **Anticorruption Layer** or **Shared Kernel**, using language and examples that are accessible to all. 136 | 137 | ### **Work with Different Perspectives and Multiple Context Maps** 138 | 139 | Different stakeholders may have varying perspectives and interests. Use multiple context maps to address these different viewpoints, ensuring that each map remains clear and relevant to its intended audience. 140 | 141 | **Example:** Create one context map highlighting technical dependencies for the development team and another focusing on business processes and team interactions for project managers and executives. 142 | 143 | ## **Conclusion** 144 | 145 | Context mapping is a powerful technique in Domain-Driven Design that helps teams visualize and understand the complex relationships between bounded contexts and the teams working on them. By using defined patterns and recognizing team relationships, organizations can plan and coordinate more effectively, manage dependencies, and prevent issues related to model propagation and system integration. 146 | 147 | Adhering to best practices such as creating focused context maps, documenting patterns, and tailoring views for different perspectives ensures that context mapping remains a valuable tool for both analysis and design in complex systems. 148 | -------------------------------------------------------------------------------- /knowledgebase/tools/eventmodelling.md: -------------------------------------------------------------------------------- 1 | # Event Modeling 2 | 3 | Event Modeling is a modern methodology for designing information systems by explicitly modeling how information changes over time. It provides a blueprint for systems that helps bridge the gap between technical and non-technical stakeholders. In this article, we delve into the principles, building blocks, practical applications, and resources for mastering Event Modeling. 4 | 5 | ## **1. Introduction** 6 | 7 | ### What is Event Modeling? 8 | 9 | Event Modeling is a collaborative approach to software design that focuses on illustrating how data evolves over time through a sequence of events. This methodology was pioneered by Adam Dymitruk and his team at Adaptech Group to address the challenges of designing complex systems in a structured yet flexible manner. 10 | 11 | Unlike other methodologies that focus primarily on the "how" of implementation, Event Modeling emphasizes the "what" and "why" of business processes, offering a shared language for all stakeholders. 12 | 13 | ### Key Benefits 14 | 15 | - **Improved Collaboration**: Facilitates communication between developers, product managers, UX designers, and business analysts. 16 | - **Clarity**: Provides a clear and visual blueprint of system behavior. 17 | - **Predictability**: Reduces the risk of misaligned requirements and costly rework during development. 18 | 19 | ## **2. Core Concepts** 20 | 21 | ### Events 22 | 23 | - **Definition**: Immutable facts about what has occurred in the system (e.g., "Order Placed," "Payment Processed"). 24 | - **Purpose**: Capture the state change of an entity over time. 25 | 26 | ### Commands 27 | 28 | - **Definition**: User or system intentions to change the state of the system (e.g., "Place Order," "Cancel Subscription"). 29 | - **Purpose**: Trigger actions that result in events. 30 | 31 | ### Views (Read Models) 32 | 33 | - **Definition**: Representations of data tailored for specific use cases or user interfaces (e.g., "Order Summary Page"). 34 | - **Purpose**: Provide insights and support decision-making by aggregating and presenting data from events. 35 | 36 | ### Triggers 37 | 38 | - **Definition**: External factors or user actions that initiate a sequence of operations. 39 | - **Purpose**: Define the starting points for use cases. 40 | 41 | ## **3. Building Blocks and Patterns** 42 | 43 | Event Modeling is built on four primary building blocks and leverages specific patterns to address common scenarios. 44 | 45 | ### Building Blocks 46 | 47 | 1. **Triggers**: Define the external stimuli. 48 | 2. **Commands**: Capture intent. 49 | 3. **Events**: Record state changes. 50 | 4. **Views**: Provide projections for user needs. 51 | 52 | ### Patterns 53 | 54 | 1. **Command Pattern**: Isolate business logic that leads to events. 55 | 2. **View Pattern**: Structure data retrieval optimized for specific user needs. 56 | 3. **Automation Pattern**: Automate repetitive workflows triggered by events. 57 | 4. **Translation Pattern**: Convert data between systems or domains seamlessly. 58 | 59 | ## **4. Application in Traditional Systems** 60 | 61 | While Event Modeling is particularly effective for event-driven systems, it can also be applied to traditional systems using relational databases. 62 | 63 | ### Steps to Apply in Traditional Systems 64 | 65 | 1. **Identify Key Events**: Map business processes to a sequence of state changes. 66 | 2. **Define Commands and Views**: Align commands with user intents and views with business queries. 67 | 3. **Integrate Events into the Database**: Use tables to represent event streams. 68 | 69 | ### Advantages 70 | 71 | - Ensures systematic design even with legacy systems. 72 | - Encourages forward-thinking architecture for future scalability. 73 | 74 | ## **5. Comparison with Event Storming** 75 | 76 | Event Modeling and Event Storming are complementary techniques often used in the Domain-Driven Design (DDD) toolkit. However, they serve distinct purposes: 77 | 78 | | **Aspect** | **Event Modeling** | **[Event Storming](eventstorming.md)** | 79 | | ------------- | --------------------------------- | --------------------------------------- | 80 | | **Focus** | Designing the solution space | Exploring the problem space | 81 | | **Output** | A blueprint for implementation | Shared understanding of domain concepts | 82 | | **Artifacts** | Commands, Events, Views, Triggers | Event timeline, aggregates, policies | 83 | | **Formality** | Structured | Exploratory | 84 | 85 | ### Resources 86 | 87 | 1. **Website**: [Event Modeling website](https://eventmodeling.org) 88 | 2. **Books**: *Event Modeling and Event Sourcing* by Martin Dilger. 89 | 3. **Cheat Sheets**: The [Event Modeling Cheat Sheet](https://eventmodeling.org/posts/event-modeling-cheatsheet) provides quick guidance. 90 | 4. **Podcasts**: Subscribe to episodes on [podcast.eventmodeling.org](https://podcast.eventmodeling.org). 91 | 5. **Video Tutorials**: Watch live streams and recorded tutorials for step-by-step instructions. 92 | -------------------------------------------------------------------------------- /knowledgebase/tools/images/BigPicture EventStorming Example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/knowledgebase/tools/images/BigPicture EventStorming Example.png -------------------------------------------------------------------------------- /knowledgebase/tools/images/BigPictureEventStorming Grammar.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/knowledgebase/tools/images/BigPictureEventStorming Grammar.png -------------------------------------------------------------------------------- /knowledgebase/tools/images/EventStorming Example Grammar.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/knowledgebase/tools/images/EventStorming Example Grammar.png -------------------------------------------------------------------------------- /knowledgebase/tools/images/Restaurant DDD Kata Example Grammar.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/knowledgebase/tools/images/Restaurant DDD Kata Example Grammar.png -------------------------------------------------------------------------------- /knowledgebase/tools/images/Restaurant DDD Kata Example_Chaotic_Exploration.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/knowledgebase/tools/images/Restaurant DDD Kata Example_Chaotic_Exploration.png -------------------------------------------------------------------------------- /knowledgebase/tools/images/Restaurant DDD Kata Example_DMF.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/knowledgebase/tools/images/Restaurant DDD Kata Example_DMF.png -------------------------------------------------------------------------------- /knowledgebase/tools/images/Restaurant DDD Kata Example_Detailed_Design_I.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/knowledgebase/tools/images/Restaurant DDD Kata Example_Detailed_Design_I.png -------------------------------------------------------------------------------- /knowledgebase/tools/images/Restaurant DDD Kata Example_Detailed_Design_II.png.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/knowledgebase/tools/images/Restaurant DDD Kata Example_Detailed_Design_II.png.png -------------------------------------------------------------------------------- /knowledgebase/tools/images/Restaurant DDD Kata Example_Detailed_Design_III.png.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/knowledgebase/tools/images/Restaurant DDD Kata Example_Detailed_Design_III.png.png -------------------------------------------------------------------------------- /knowledgebase/tools/images/Restaurant DDD Kata Example_Detailed_Design_IV.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/knowledgebase/tools/images/Restaurant DDD Kata Example_Detailed_Design_IV.png -------------------------------------------------------------------------------- /knowledgebase/tools/images/Restaurant DDD Kata Example_Enforce_Consistency.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/knowledgebase/tools/images/Restaurant DDD Kata Example_Enforce_Consistency.png -------------------------------------------------------------------------------- /knowledgebase/tools/images/Restaurant DDD Kata Example_Enforce_Timeline.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/knowledgebase/tools/images/Restaurant DDD Kata Example_Enforce_Timeline.png -------------------------------------------------------------------------------- /knowledgebase/tools/images/Restaurant DDD Kata Example_Identify_Bounded_Contexts.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/knowledgebase/tools/images/Restaurant DDD Kata Example_Identify_Bounded_Contexts.png -------------------------------------------------------------------------------- /knowledgebase/tools/images/messages-and-contents.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAP/curated-resources-for-domain-driven-design/bd14844dc007c93ea3f4b64fe2c33f40d565a42c/knowledgebase/tools/images/messages-and-contents.jpg --------------------------------------------------------------------------------