First MADRs for latest decisions (#334)

Author: stefan-ka

docs/madr/0001-domain-services-outside-aggregates.md

@@ -0,0 +1,26 @@
+---
+status: "accepted"
+date: "2023-04-06"
+deciders: "stefan-ka, socadk"
+---
+# Allow modeling of domain services besides aggregates, instead of inside aggregates
+
+## Context and Problem Statement
+
+We originally took the [Sculptor DSL](http://sculptorgenerator.org/) for the tactic DDD part. For some reason we do not exactly know, they decided that services are modelled inside aggregates. This does not correspond with our interpretation of the DDD patterns and was additionally reported with [#326](https://github.com/ContextMapper/context-mapper-dsl/issues/326). Domain services should be modeled on the same level as aggregates (for CML, this means inside the bounded context object).
+
+The problem: correcting this issue in a clean way would lead to a non-backwards-compatible change.
+
+## Considered Options
+
+* Not backwards-compatible: Make non-backwards-compatible change and release a new major version of Context Mapper.
+* Backwards-compatible: Allow to model domain services inside bounded contexts, but still support the old option to stay backwards-compatible.
+
+## Decision Outcome
+
+Chosen option: "backwards-compatible", because a breaking change is risky, causes a lot of documentation work for us, and lots of migration work for the users (adjust their models). 
+
+### Consequences
+
+* Good, because we lower the risk and cause less migration and documentation work for us and the users.
+* Bad, because it is still possible to model domain services in a way that does not reflect our understanding of the patterns.

docs/madr/0002-use-case-diagram-layout.md

@@ -0,0 +1,20 @@
+---
+status: "accepted"
+date: "2023-05-04"
+deciders: "stefan-ka, socadk"
+---
+# Layout for Use Case Diagrams (PlantUML Generator)
+
+## Context and Problem Statement
+
+While implementing our Use Case diagram generator, we realised that there are some differences regarding how people visualize use case diagrams. The [PlantUML documentation](https://plantuml.com/use-case-diagram) by default suggests that arrows point from actors to use cases. It does not clearly state how [secondary actors](https://socadk.github.io/design-practice-repository/artifact-templates/DPR-UseCase.html) shall be visualized. socadk legitimately pointed out that for a secondary actor it would make more sense to point the arrow from the use case to the secondary actor, as only the primary actor initiates the use case.
+Based on that discussion we checked out [Larman](https://www.amazon.de/Applying-UML-Patterns-Introduction-Object-Oriented/dp/0131489062); a popular book on UML and OOAD, serving as a 'de-facto' standard for many modelers. Larman suggests to not make arrows but just connect the actors with the use cases and draw the primary actors on the left and secondary actors on the right. Use cases are visualized top to bottom.
+
+## Considered Options
+
+* Default PlantUML with arrows
+* Stick to Larman
+
+## Decision Outcome
+
+Chosen option: "Stick to Larman", because we try to use and align with the literature as such as possible. For example: For the Context Map generator we tried to stick to the visualization of [Vaughn Vernon](https://www.amazon.de/s?k=implementing+domain+driven+design&adgrpid=63456564181&hvadid=381008329565&hvdev=c&hvlocphy=1030659&hvnetw=g&hvqmt=e&hvrand=11057192946270756118&hvtargid=kwd-299405302030&hydadcr=14770_1980674&tag=hydrach-21&ref=pd_sl_9tt0fqrrb3_e). Thereby, our decision is consistent with our earlier design principles.

docs/madr/README.md

@@ -0,0 +1,5 @@
+# Markdown Any Decision Records (MADR)
+
+Within this folder we document our design and architectural decisions according to the [MADR template](https://github.com/adr/madr).
+
+To create a new record, use the template file [here](https://github.com/adr/madr/blob/develop/template/adr-template.md).