context-mapper 0.20.2__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- context_mapper-0.20.2/LICENSE +15 -0
- context_mapper-0.20.2/PKG-INFO +211 -0
- context_mapper-0.20.2/README.md +182 -0
- context_mapper-0.20.2/pyproject.toml +61 -0
- context_mapper-0.20.2/setup.cfg +4 -0
- context_mapper-0.20.2/src/context_mapper/__init__.py +1 -0
- context_mapper-0.20.2/src/context_mapper/__main__.py +6 -0
- context_mapper-0.20.2/src/context_mapper/build.py +137 -0
- context_mapper-0.20.2/src/context_mapper/graph.py +428 -0
- context_mapper-0.20.2/src/context_mapper/mermaid.py +647 -0
- context_mapper-0.20.2/src/context_mapper/serve.py +166 -0
- context_mapper-0.20.2/src/context_mapper/template/app.js +622 -0
- context_mapper-0.20.2/src/context_mapper/template/index.html +50 -0
- context_mapper-0.20.2/src/context_mapper/template/style.css +47 -0
- context_mapper-0.20.2/src/context_mapper.egg-info/PKG-INFO +211 -0
- context_mapper-0.20.2/src/context_mapper.egg-info/SOURCES.txt +22 -0
- context_mapper-0.20.2/src/context_mapper.egg-info/dependency_links.txt +1 -0
- context_mapper-0.20.2/src/context_mapper.egg-info/entry_points.txt +2 -0
- context_mapper-0.20.2/src/context_mapper.egg-info/requires.txt +5 -0
- context_mapper-0.20.2/src/context_mapper.egg-info/top_level.txt +1 -0
- context_mapper-0.20.2/tests/test_build.py +225 -0
- context_mapper-0.20.2/tests/test_graph.py +482 -0
- context_mapper-0.20.2/tests/test_mermaid.py +598 -0
- context_mapper-0.20.2/tests/test_serve.py +276 -0
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
ISC License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Henrique Moody <henriquemoody@gmail.com>
|
|
4
|
+
|
|
5
|
+
Permission to use, copy, modify, and/or distribute this software for any
|
|
6
|
+
purpose with or without fee is hereby granted, provided that the above
|
|
7
|
+
copyright notice and this permission notice appear in all copies.
|
|
8
|
+
|
|
9
|
+
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
10
|
+
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
11
|
+
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
|
|
12
|
+
SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
13
|
+
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
14
|
+
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
|
|
15
|
+
IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
@@ -0,0 +1,211 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: context-mapper
|
|
3
|
+
Version: 0.20.2
|
|
4
|
+
Summary: Builds an interactive context map and Mermaid diagrams from a YAML domain model.
|
|
5
|
+
Author-email: Henrique Moody <henriquemoody@gmail.com>
|
|
6
|
+
License-Expression: ISC
|
|
7
|
+
Project-URL: Homepage, https://github.com/henriquemoody/context-mapper
|
|
8
|
+
Project-URL: Documentation, https://github.com/henriquemoody/context-mapper#readme
|
|
9
|
+
Project-URL: Repository, https://github.com/henriquemoody/context-mapper
|
|
10
|
+
Project-URL: Issues, https://github.com/henriquemoody/context-mapper/issues
|
|
11
|
+
Keywords: domain-driven-design,context-map,mermaid,diagrams
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Topic :: Software Development :: Documentation
|
|
21
|
+
Requires-Python: >=3.9
|
|
22
|
+
Description-Content-Type: text/markdown
|
|
23
|
+
License-File: LICENSE
|
|
24
|
+
Requires-Dist: PyYAML
|
|
25
|
+
Provides-Extra: dev
|
|
26
|
+
Requires-Dist: pytest; extra == "dev"
|
|
27
|
+
Requires-Dist: ruff; extra == "dev"
|
|
28
|
+
Dynamic: license-file
|
|
29
|
+
|
|
30
|
+
# Context Mapper
|
|
31
|
+
|
|
32
|
+
Builds a context map: an interactive page plus static Mermaid diagrams of your domains, bounded contexts, and the dependencies between them, from two YAML files. `context-map.yml` says what the map describes; `context-map.style.yml` says how it looks.
|
|
33
|
+
|
|
34
|
+
[](https://henriquemoody.github.io/context-mapper/)
|
|
35
|
+
|
|
36
|
+
The interactive page built from the [`example/`](example/) model, published by GitHub Actions — click the picture, or go straight to <https://henriquemoody.github.io/context-mapper/>.
|
|
37
|
+
|
|
38
|
+
The build fails on unknown ids, duplicates, dependency cycles between bounded contexts, and unknown or invalid `context-map.style.yml` options, so a bad change breaks the build instead of the picture. It warns when two domains depend on each other.
|
|
39
|
+
|
|
40
|
+
- `src/context_mapper/build.py` validates the model and builds everything.
|
|
41
|
+
- `src/context_mapper/graph.py` holds the model logic: levels, lifting context dependencies to domains, and the focus walk.
|
|
42
|
+
- `src/context_mapper/mermaid.py` turns views into Mermaid.
|
|
43
|
+
- `src/context_mapper/template/` is the interactive page: `index.html`, `style.css` and `app.js`, spliced into one file when it builds.
|
|
44
|
+
- `example/` is a small working model you can build right away.
|
|
45
|
+
|
|
46
|
+
## Install
|
|
47
|
+
|
|
48
|
+
Requires Python 3.9+; Mermaid itself is loaded from a CDN when you view a page, so the only build dependency is PyYAML.
|
|
49
|
+
|
|
50
|
+
```sh
|
|
51
|
+
pip install git+https://github.com/henriquemoody/context-mapper.git
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Pin a tag (as above) or a branch, so a change here cannot break your build unannounced.
|
|
55
|
+
|
|
56
|
+
Run `context-mapper` in a directory that has a `context-map.yml` and a `context-map.style.yml`. The paths are flags:
|
|
57
|
+
|
|
58
|
+
```sh
|
|
59
|
+
context-mapper --model context-map.yml --diagrams context-map.style.yml --out public
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
While you write the model, `context-mapper serve --watch` serves the site at `http://127.0.0.1:8000/` and rebuilds it whenever you save — the same flags apply.
|
|
63
|
+
|
|
64
|
+
## The model
|
|
65
|
+
|
|
66
|
+
```yaml
|
|
67
|
+
types:
|
|
68
|
+
core: { name: Core } # the colors live in context-map.style.yml
|
|
69
|
+
supporting: { name: Supporting }
|
|
70
|
+
generic: { name: Generic }
|
|
71
|
+
|
|
72
|
+
clusters: # a set of domains or contexts treated together
|
|
73
|
+
foundations: { name: Shared Foundations }
|
|
74
|
+
|
|
75
|
+
context-map: # every id is a key, exactly once
|
|
76
|
+
payments: # no `domain:` key: a domain
|
|
77
|
+
name: Payments
|
|
78
|
+
type: generic
|
|
79
|
+
cluster: foundations # a member of the foundations cluster
|
|
80
|
+
downstreams: # who depends on it, and why
|
|
81
|
+
checkout: Charges the payment method and signals whether it went through. # a tooltip on the arrow
|
|
82
|
+
fulfillment: # a bare key: no comment yet
|
|
83
|
+
catalog: # a dependency can point at a whole domain
|
|
84
|
+
name: Catalog
|
|
85
|
+
type: core
|
|
86
|
+
downstreams:
|
|
87
|
+
checkout:
|
|
88
|
+
comment: Reads prices and availability at checkout time.
|
|
89
|
+
style: dotted # or a map, for a styled edge
|
|
90
|
+
checkout: # a `domain:` key makes an entry a bounded context
|
|
91
|
+
name: Checkout
|
|
92
|
+
domain: orders
|
|
93
|
+
description: Takes a cart and turns it into a paid order. # shows as a tooltip on the box
|
|
94
|
+
fulfillment:
|
|
95
|
+
name: Fulfillment
|
|
96
|
+
domain: orders
|
|
97
|
+
type: supporting # a context can override its domain's type
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Three kinds of thing, in three sections. `types` is the role vocabulary of the model: a domain or bounded context has one. `clusters` names a set of domains or contexts treated together; members join with `cluster:`, and nothing can depend on a cluster. In `context-map`, an entry with a `domain:` key is a bounded context, and any other entry is a domain — one no context points at is a single bounded context. How anything first renders comes from `defaultDisplay` in the style file: a domain or a cluster takes `expanded` (the box and what it holds), `collapsed` (the box alone), `contents` (what it holds, no box), or `hidden` (neither). A bounded context — one box with nothing inside, and a domain no context points at is one too — takes only `expanded` or `hidden`; writing `collapsed` or `contents` for one fails the build, saying why.
|
|
101
|
+
|
|
102
|
+
Every entry can carry a `description`: the interactive page shows it as a tooltip when you hover over its box, and the item's page shows it under the title.
|
|
103
|
+
|
|
104
|
+
A domain no context points at is a single bounded context with the same name.
|
|
105
|
+
|
|
106
|
+
At domain level, context dependencies are lifted to their domains and merged, and dependencies inside a domain disappear.
|
|
107
|
+
|
|
108
|
+
## What gets built
|
|
109
|
+
|
|
110
|
+
| Output | What it is |
|
|
111
|
+
| --- | --- |
|
|
112
|
+
| `<out>/index.html` | Interactive view. Switch between bounded contexts and domains, click anything to focus on it, hide anything from the side panel, hover a box or an arrow for the details. |
|
|
113
|
+
| `<out>/mermaid/*.html` | One static Mermaid page per domain, per bounded context, and per named view. Click a box to jump to its page. |
|
|
114
|
+
| `<out>/markdown/*.md` | The same diagrams as Markdown. GitLab renders them natively, and they can go to Confluence. |
|
|
115
|
+
|
|
116
|
+
## Run locally
|
|
117
|
+
|
|
118
|
+
```sh
|
|
119
|
+
git clone https://github.com/henriquemoody/context-mapper.git
|
|
120
|
+
cd context-mapper
|
|
121
|
+
pip install .
|
|
122
|
+
cd example
|
|
123
|
+
context-mapper serve --watch
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
`serve` builds the site and serves it at `http://127.0.0.1:8000/` (`--host` and `--port` to move it, `--out` for the directory). With `--watch`, saving the model or the style file rebuilds the site and the browser reloads the page by itself; a build that fails says why on the terminal and the page keeps showing the last good one, so a broken edit never takes the site down. The reload script is served on the wire only — the files stay exactly what a plain `context-mapper` writes, ready to publish.
|
|
127
|
+
|
|
128
|
+
## Customize the diagrams
|
|
129
|
+
|
|
130
|
+
`context-map.style.yml` holds all of it. Its sections mirror the model's — `types`, `clusters`, `context-map` — keyed by the same ids, and take Mermaid's own classDef attributes as keys (`fill`, `stroke`, `stroke-width`, ...), so what you write is what Mermaid draws: a domain's entry styles the box around its bounded contexts, a bounded context's entry styles its own box. Any entry also takes `defaultDisplay`, saying how it first renders — a bounded context hidden that way is hidden like `hide` hides it, everywhere except its own page. The build fails if one points at an id that doesn't exist, on an attribute Mermaid doesn't know, or on a type without `fill` and `stroke`.
|
|
131
|
+
|
|
132
|
+
```yaml
|
|
133
|
+
types:
|
|
134
|
+
core: { fill: "#dedaff", stroke: "#6631d7" } # types need fill and stroke
|
|
135
|
+
|
|
136
|
+
clusters:
|
|
137
|
+
foundations: { fill: "#eaf9ef", stroke: "#067429", stroke-dasharray: "4 3", defaultDisplay: collapsed }
|
|
138
|
+
|
|
139
|
+
context-map:
|
|
140
|
+
orders: { fill: "#eef4ff", stroke: "#305bab" } # overrides mermaid.domain_style
|
|
141
|
+
checkout: { fill: "#fff4f4", defaultDisplay: hidden } # a bounded context styles its own box, and can start hidden
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
A style also fills in a readable text `color` when you don't set one.
|
|
145
|
+
|
|
146
|
+
The rest lives in the `mermaid` section. Every style in it is a map of the same Mermaid attributes as above, so `focus_style`, `domain_style` and `edge_styles` read like `types`, `clusters` and `context-map`. It styles the interactive page (`index.html`) and the static pages alike, since both are drawn with Mermaid. The interactive page uses the view `defaults` (such as `display` and `hide`) as its starting state. Unknown keys fail the build, so a typo tells you instead of doing nothing.
|
|
147
|
+
|
|
148
|
+
| Option | Values | What it does |
|
|
149
|
+
| --- | --- | --- |
|
|
150
|
+
| `direction` | `BT`, `TB`, `LR`, `RL` | Flow direction. `BT` puts upstream on top. |
|
|
151
|
+
| `theme` | `base`, `default`, `neutral`, `dark`, `forest` | Mermaid theme. |
|
|
152
|
+
| `layout` | `dagre`, `elk` | Layout engine. The HTML pages load ELK when you pick it. |
|
|
153
|
+
| `look` | `classic`, `handDrawn` | Mermaid look. |
|
|
154
|
+
| `curve` | `basis`, `linear`, `step`, `stepBefore`, ... | Line shape. Set on every edge with `linkStyle ... interpolate`, so it works with any layout. |
|
|
155
|
+
| `theme_variables` | map | Passed to Mermaid as-is (fonts, colors). |
|
|
156
|
+
| `config` | map | Any other [Mermaid config](https://mermaid.js.org/config/schema-docs/config.html), merged over the above. For example `elk.nodePlacementStrategy`. |
|
|
157
|
+
| `markdown_config` | map | Merged over everything for `<out>/markdown/*.md` only. GitLab's built-in Mermaid has no ELK, so the example sets `layout: dagre` here. |
|
|
158
|
+
| `focus_style` | map of Mermaid attributes | How the focused item is highlighted. |
|
|
159
|
+
| `domain_style` | map of Mermaid attributes | Style of the box around a domain's bounded contexts. A domain with its own style under `context-map` overrides it — and its type colors, when drawn as one box. |
|
|
160
|
+
| `edge_styles.solid`, `edge_styles.dotted` | map of Mermaid attributes | Line styles. Dotted comes from `style: dotted` on a downstream. |
|
|
161
|
+
| `pages` | `all`, `domains`, `contexts`, or a list of ids | Which items get their own page. |
|
|
162
|
+
|
|
163
|
+
These can be set under `defaults` and overridden per view:
|
|
164
|
+
|
|
165
|
+
| Option | Values | What it does |
|
|
166
|
+
| --- | --- | --- |
|
|
167
|
+
| `level` | `context`, `domain` | Bounded contexts inside domain boxes, or one box per domain. |
|
|
168
|
+
| `depth` | number, `99` for all | Hops out from the focus. |
|
|
169
|
+
| `dir` | `both`, `up`, `down` | Depends on, used by, or both. |
|
|
170
|
+
| `display` | `expanded`, `collapsed`, `contents`, `hidden`, or a map from container id to one of those | How containers first render. A single value applies to every container; a map leaves the rest to their own `defaultDisplay` in the style file. |
|
|
171
|
+
| `hide` | a list of ids | What the view never draws, no matter what: hiding a domain or a cluster takes everything inside it, hiding a bounded context only its own box and arrows. In the whole system that trims domains and clusters; in a domain's view it leaves out bounded contexts; in a cluster's view, members. The focus itself is never hidden. |
|
|
172
|
+
| `child_labels` | `true`, `false` | A collapsed container names what it holds, in the box and on each arrow that reaches it. |
|
|
173
|
+
| `group_by_type` | `true`, `false` | Wrap Core, Supporting and Generic in their own boxes. |
|
|
174
|
+
|
|
175
|
+
A view can also set `id`, `title`, `focus` (a domain, context or cluster id), `description` and `direction`:
|
|
176
|
+
|
|
177
|
+
```yaml
|
|
178
|
+
- id: catalog-detail
|
|
179
|
+
title: Catalog in detail
|
|
180
|
+
focus: catalog
|
|
181
|
+
display: contents # or { foundations: contents }
|
|
182
|
+
hide: [search] # never draw the Search context here
|
|
183
|
+
direction: LR
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
## Use it in another repository
|
|
187
|
+
|
|
188
|
+
Keep only the model in your repository and let CI install this tool. Pin a tag so the build is reproducible; when you want a newer version, bump the tag. This GitLab Pages job is all it takes (the GitHub tag tarball works everywhere, and needs no `git` in the image):
|
|
189
|
+
|
|
190
|
+
```yaml
|
|
191
|
+
pages:
|
|
192
|
+
image: python:3.12-slim
|
|
193
|
+
script:
|
|
194
|
+
- pip install --quiet https://github.com/henriquemoody/context-mapper/archive/refs/tags/v0.20.2.tar.gz
|
|
195
|
+
- context-mapper
|
|
196
|
+
artifacts:
|
|
197
|
+
paths:
|
|
198
|
+
- public
|
|
199
|
+
rules:
|
|
200
|
+
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
## Links
|
|
204
|
+
|
|
205
|
+
- `index.html#focus=checkout`: interactive, Checkout and its direct neighbors
|
|
206
|
+
- `index.html#focus=foundations`: interactive, the foundations cluster, opened, and what its members touch
|
|
207
|
+
- `index.html#level=domain&focus=orders`: interactive, the Orders domain and its neighbors
|
|
208
|
+
- `index.html#focus=orders&hide.fulfillment=1`: interactive, the Orders domain without the Fulfillment context
|
|
209
|
+
- Other hash options: `depth=1|2|99`, `dir=both|up|down`, `display.<domain id>=expanded|collapsed|contents|hidden`, `hide.<id>=1|0`
|
|
210
|
+
- `mermaid/checkout.html`: static diagram for Checkout
|
|
211
|
+
- `mermaid/index.html`: all static diagrams
|
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
# Context Mapper
|
|
2
|
+
|
|
3
|
+
Builds a context map: an interactive page plus static Mermaid diagrams of your domains, bounded contexts, and the dependencies between them, from two YAML files. `context-map.yml` says what the map describes; `context-map.style.yml` says how it looks.
|
|
4
|
+
|
|
5
|
+
[](https://henriquemoody.github.io/context-mapper/)
|
|
6
|
+
|
|
7
|
+
The interactive page built from the [`example/`](example/) model, published by GitHub Actions — click the picture, or go straight to <https://henriquemoody.github.io/context-mapper/>.
|
|
8
|
+
|
|
9
|
+
The build fails on unknown ids, duplicates, dependency cycles between bounded contexts, and unknown or invalid `context-map.style.yml` options, so a bad change breaks the build instead of the picture. It warns when two domains depend on each other.
|
|
10
|
+
|
|
11
|
+
- `src/context_mapper/build.py` validates the model and builds everything.
|
|
12
|
+
- `src/context_mapper/graph.py` holds the model logic: levels, lifting context dependencies to domains, and the focus walk.
|
|
13
|
+
- `src/context_mapper/mermaid.py` turns views into Mermaid.
|
|
14
|
+
- `src/context_mapper/template/` is the interactive page: `index.html`, `style.css` and `app.js`, spliced into one file when it builds.
|
|
15
|
+
- `example/` is a small working model you can build right away.
|
|
16
|
+
|
|
17
|
+
## Install
|
|
18
|
+
|
|
19
|
+
Requires Python 3.9+; Mermaid itself is loaded from a CDN when you view a page, so the only build dependency is PyYAML.
|
|
20
|
+
|
|
21
|
+
```sh
|
|
22
|
+
pip install git+https://github.com/henriquemoody/context-mapper.git
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Pin a tag (as above) or a branch, so a change here cannot break your build unannounced.
|
|
26
|
+
|
|
27
|
+
Run `context-mapper` in a directory that has a `context-map.yml` and a `context-map.style.yml`. The paths are flags:
|
|
28
|
+
|
|
29
|
+
```sh
|
|
30
|
+
context-mapper --model context-map.yml --diagrams context-map.style.yml --out public
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
While you write the model, `context-mapper serve --watch` serves the site at `http://127.0.0.1:8000/` and rebuilds it whenever you save — the same flags apply.
|
|
34
|
+
|
|
35
|
+
## The model
|
|
36
|
+
|
|
37
|
+
```yaml
|
|
38
|
+
types:
|
|
39
|
+
core: { name: Core } # the colors live in context-map.style.yml
|
|
40
|
+
supporting: { name: Supporting }
|
|
41
|
+
generic: { name: Generic }
|
|
42
|
+
|
|
43
|
+
clusters: # a set of domains or contexts treated together
|
|
44
|
+
foundations: { name: Shared Foundations }
|
|
45
|
+
|
|
46
|
+
context-map: # every id is a key, exactly once
|
|
47
|
+
payments: # no `domain:` key: a domain
|
|
48
|
+
name: Payments
|
|
49
|
+
type: generic
|
|
50
|
+
cluster: foundations # a member of the foundations cluster
|
|
51
|
+
downstreams: # who depends on it, and why
|
|
52
|
+
checkout: Charges the payment method and signals whether it went through. # a tooltip on the arrow
|
|
53
|
+
fulfillment: # a bare key: no comment yet
|
|
54
|
+
catalog: # a dependency can point at a whole domain
|
|
55
|
+
name: Catalog
|
|
56
|
+
type: core
|
|
57
|
+
downstreams:
|
|
58
|
+
checkout:
|
|
59
|
+
comment: Reads prices and availability at checkout time.
|
|
60
|
+
style: dotted # or a map, for a styled edge
|
|
61
|
+
checkout: # a `domain:` key makes an entry a bounded context
|
|
62
|
+
name: Checkout
|
|
63
|
+
domain: orders
|
|
64
|
+
description: Takes a cart and turns it into a paid order. # shows as a tooltip on the box
|
|
65
|
+
fulfillment:
|
|
66
|
+
name: Fulfillment
|
|
67
|
+
domain: orders
|
|
68
|
+
type: supporting # a context can override its domain's type
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Three kinds of thing, in three sections. `types` is the role vocabulary of the model: a domain or bounded context has one. `clusters` names a set of domains or contexts treated together; members join with `cluster:`, and nothing can depend on a cluster. In `context-map`, an entry with a `domain:` key is a bounded context, and any other entry is a domain — one no context points at is a single bounded context. How anything first renders comes from `defaultDisplay` in the style file: a domain or a cluster takes `expanded` (the box and what it holds), `collapsed` (the box alone), `contents` (what it holds, no box), or `hidden` (neither). A bounded context — one box with nothing inside, and a domain no context points at is one too — takes only `expanded` or `hidden`; writing `collapsed` or `contents` for one fails the build, saying why.
|
|
72
|
+
|
|
73
|
+
Every entry can carry a `description`: the interactive page shows it as a tooltip when you hover over its box, and the item's page shows it under the title.
|
|
74
|
+
|
|
75
|
+
A domain no context points at is a single bounded context with the same name.
|
|
76
|
+
|
|
77
|
+
At domain level, context dependencies are lifted to their domains and merged, and dependencies inside a domain disappear.
|
|
78
|
+
|
|
79
|
+
## What gets built
|
|
80
|
+
|
|
81
|
+
| Output | What it is |
|
|
82
|
+
| --- | --- |
|
|
83
|
+
| `<out>/index.html` | Interactive view. Switch between bounded contexts and domains, click anything to focus on it, hide anything from the side panel, hover a box or an arrow for the details. |
|
|
84
|
+
| `<out>/mermaid/*.html` | One static Mermaid page per domain, per bounded context, and per named view. Click a box to jump to its page. |
|
|
85
|
+
| `<out>/markdown/*.md` | The same diagrams as Markdown. GitLab renders them natively, and they can go to Confluence. |
|
|
86
|
+
|
|
87
|
+
## Run locally
|
|
88
|
+
|
|
89
|
+
```sh
|
|
90
|
+
git clone https://github.com/henriquemoody/context-mapper.git
|
|
91
|
+
cd context-mapper
|
|
92
|
+
pip install .
|
|
93
|
+
cd example
|
|
94
|
+
context-mapper serve --watch
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
`serve` builds the site and serves it at `http://127.0.0.1:8000/` (`--host` and `--port` to move it, `--out` for the directory). With `--watch`, saving the model or the style file rebuilds the site and the browser reloads the page by itself; a build that fails says why on the terminal and the page keeps showing the last good one, so a broken edit never takes the site down. The reload script is served on the wire only — the files stay exactly what a plain `context-mapper` writes, ready to publish.
|
|
98
|
+
|
|
99
|
+
## Customize the diagrams
|
|
100
|
+
|
|
101
|
+
`context-map.style.yml` holds all of it. Its sections mirror the model's — `types`, `clusters`, `context-map` — keyed by the same ids, and take Mermaid's own classDef attributes as keys (`fill`, `stroke`, `stroke-width`, ...), so what you write is what Mermaid draws: a domain's entry styles the box around its bounded contexts, a bounded context's entry styles its own box. Any entry also takes `defaultDisplay`, saying how it first renders — a bounded context hidden that way is hidden like `hide` hides it, everywhere except its own page. The build fails if one points at an id that doesn't exist, on an attribute Mermaid doesn't know, or on a type without `fill` and `stroke`.
|
|
102
|
+
|
|
103
|
+
```yaml
|
|
104
|
+
types:
|
|
105
|
+
core: { fill: "#dedaff", stroke: "#6631d7" } # types need fill and stroke
|
|
106
|
+
|
|
107
|
+
clusters:
|
|
108
|
+
foundations: { fill: "#eaf9ef", stroke: "#067429", stroke-dasharray: "4 3", defaultDisplay: collapsed }
|
|
109
|
+
|
|
110
|
+
context-map:
|
|
111
|
+
orders: { fill: "#eef4ff", stroke: "#305bab" } # overrides mermaid.domain_style
|
|
112
|
+
checkout: { fill: "#fff4f4", defaultDisplay: hidden } # a bounded context styles its own box, and can start hidden
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
A style also fills in a readable text `color` when you don't set one.
|
|
116
|
+
|
|
117
|
+
The rest lives in the `mermaid` section. Every style in it is a map of the same Mermaid attributes as above, so `focus_style`, `domain_style` and `edge_styles` read like `types`, `clusters` and `context-map`. It styles the interactive page (`index.html`) and the static pages alike, since both are drawn with Mermaid. The interactive page uses the view `defaults` (such as `display` and `hide`) as its starting state. Unknown keys fail the build, so a typo tells you instead of doing nothing.
|
|
118
|
+
|
|
119
|
+
| Option | Values | What it does |
|
|
120
|
+
| --- | --- | --- |
|
|
121
|
+
| `direction` | `BT`, `TB`, `LR`, `RL` | Flow direction. `BT` puts upstream on top. |
|
|
122
|
+
| `theme` | `base`, `default`, `neutral`, `dark`, `forest` | Mermaid theme. |
|
|
123
|
+
| `layout` | `dagre`, `elk` | Layout engine. The HTML pages load ELK when you pick it. |
|
|
124
|
+
| `look` | `classic`, `handDrawn` | Mermaid look. |
|
|
125
|
+
| `curve` | `basis`, `linear`, `step`, `stepBefore`, ... | Line shape. Set on every edge with `linkStyle ... interpolate`, so it works with any layout. |
|
|
126
|
+
| `theme_variables` | map | Passed to Mermaid as-is (fonts, colors). |
|
|
127
|
+
| `config` | map | Any other [Mermaid config](https://mermaid.js.org/config/schema-docs/config.html), merged over the above. For example `elk.nodePlacementStrategy`. |
|
|
128
|
+
| `markdown_config` | map | Merged over everything for `<out>/markdown/*.md` only. GitLab's built-in Mermaid has no ELK, so the example sets `layout: dagre` here. |
|
|
129
|
+
| `focus_style` | map of Mermaid attributes | How the focused item is highlighted. |
|
|
130
|
+
| `domain_style` | map of Mermaid attributes | Style of the box around a domain's bounded contexts. A domain with its own style under `context-map` overrides it — and its type colors, when drawn as one box. |
|
|
131
|
+
| `edge_styles.solid`, `edge_styles.dotted` | map of Mermaid attributes | Line styles. Dotted comes from `style: dotted` on a downstream. |
|
|
132
|
+
| `pages` | `all`, `domains`, `contexts`, or a list of ids | Which items get their own page. |
|
|
133
|
+
|
|
134
|
+
These can be set under `defaults` and overridden per view:
|
|
135
|
+
|
|
136
|
+
| Option | Values | What it does |
|
|
137
|
+
| --- | --- | --- |
|
|
138
|
+
| `level` | `context`, `domain` | Bounded contexts inside domain boxes, or one box per domain. |
|
|
139
|
+
| `depth` | number, `99` for all | Hops out from the focus. |
|
|
140
|
+
| `dir` | `both`, `up`, `down` | Depends on, used by, or both. |
|
|
141
|
+
| `display` | `expanded`, `collapsed`, `contents`, `hidden`, or a map from container id to one of those | How containers first render. A single value applies to every container; a map leaves the rest to their own `defaultDisplay` in the style file. |
|
|
142
|
+
| `hide` | a list of ids | What the view never draws, no matter what: hiding a domain or a cluster takes everything inside it, hiding a bounded context only its own box and arrows. In the whole system that trims domains and clusters; in a domain's view it leaves out bounded contexts; in a cluster's view, members. The focus itself is never hidden. |
|
|
143
|
+
| `child_labels` | `true`, `false` | A collapsed container names what it holds, in the box and on each arrow that reaches it. |
|
|
144
|
+
| `group_by_type` | `true`, `false` | Wrap Core, Supporting and Generic in their own boxes. |
|
|
145
|
+
|
|
146
|
+
A view can also set `id`, `title`, `focus` (a domain, context or cluster id), `description` and `direction`:
|
|
147
|
+
|
|
148
|
+
```yaml
|
|
149
|
+
- id: catalog-detail
|
|
150
|
+
title: Catalog in detail
|
|
151
|
+
focus: catalog
|
|
152
|
+
display: contents # or { foundations: contents }
|
|
153
|
+
hide: [search] # never draw the Search context here
|
|
154
|
+
direction: LR
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
## Use it in another repository
|
|
158
|
+
|
|
159
|
+
Keep only the model in your repository and let CI install this tool. Pin a tag so the build is reproducible; when you want a newer version, bump the tag. This GitLab Pages job is all it takes (the GitHub tag tarball works everywhere, and needs no `git` in the image):
|
|
160
|
+
|
|
161
|
+
```yaml
|
|
162
|
+
pages:
|
|
163
|
+
image: python:3.12-slim
|
|
164
|
+
script:
|
|
165
|
+
- pip install --quiet https://github.com/henriquemoody/context-mapper/archive/refs/tags/v0.20.2.tar.gz
|
|
166
|
+
- context-mapper
|
|
167
|
+
artifacts:
|
|
168
|
+
paths:
|
|
169
|
+
- public
|
|
170
|
+
rules:
|
|
171
|
+
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
## Links
|
|
175
|
+
|
|
176
|
+
- `index.html#focus=checkout`: interactive, Checkout and its direct neighbors
|
|
177
|
+
- `index.html#focus=foundations`: interactive, the foundations cluster, opened, and what its members touch
|
|
178
|
+
- `index.html#level=domain&focus=orders`: interactive, the Orders domain and its neighbors
|
|
179
|
+
- `index.html#focus=orders&hide.fulfillment=1`: interactive, the Orders domain without the Fulfillment context
|
|
180
|
+
- Other hash options: `depth=1|2|99`, `dir=both|up|down`, `display.<domain id>=expanded|collapsed|contents|hidden`, `hide.<id>=1|0`
|
|
181
|
+
- `mermaid/checkout.html`: static diagram for Checkout
|
|
182
|
+
- `mermaid/index.html`: all static diagrams
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "context-mapper"
|
|
7
|
+
version = "0.20.2"
|
|
8
|
+
description = "Builds an interactive context map and Mermaid diagrams from a YAML domain model."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "ISC"
|
|
11
|
+
license-files = ["LICENSE"]
|
|
12
|
+
requires-python = ">=3.9"
|
|
13
|
+
authors = [
|
|
14
|
+
{ name = "Henrique Moody", email = "henriquemoody@gmail.com" },
|
|
15
|
+
]
|
|
16
|
+
keywords = ["domain-driven-design", "context-map", "mermaid", "diagrams"]
|
|
17
|
+
classifiers = [
|
|
18
|
+
"Development Status :: 4 - Beta",
|
|
19
|
+
"Intended Audience :: Developers",
|
|
20
|
+
"Programming Language :: Python :: 3",
|
|
21
|
+
"Programming Language :: Python :: 3.9",
|
|
22
|
+
"Programming Language :: Python :: 3.10",
|
|
23
|
+
"Programming Language :: Python :: 3.11",
|
|
24
|
+
"Programming Language :: Python :: 3.12",
|
|
25
|
+
"Programming Language :: Python :: 3.13",
|
|
26
|
+
"Topic :: Software Development :: Documentation",
|
|
27
|
+
]
|
|
28
|
+
dependencies = [
|
|
29
|
+
"PyYAML",
|
|
30
|
+
]
|
|
31
|
+
|
|
32
|
+
[project.optional-dependencies]
|
|
33
|
+
dev = [
|
|
34
|
+
"pytest",
|
|
35
|
+
"ruff",
|
|
36
|
+
]
|
|
37
|
+
|
|
38
|
+
[project.urls]
|
|
39
|
+
Homepage = "https://github.com/henriquemoody/context-mapper"
|
|
40
|
+
Documentation = "https://github.com/henriquemoody/context-mapper#readme"
|
|
41
|
+
Repository = "https://github.com/henriquemoody/context-mapper"
|
|
42
|
+
Issues = "https://github.com/henriquemoody/context-mapper/issues"
|
|
43
|
+
|
|
44
|
+
[project.scripts]
|
|
45
|
+
context-mapper = "context_mapper.build:main"
|
|
46
|
+
|
|
47
|
+
[tool.setuptools.packages.find]
|
|
48
|
+
where = ["src"]
|
|
49
|
+
|
|
50
|
+
[tool.setuptools.package-data]
|
|
51
|
+
context_mapper = ["template/*"]
|
|
52
|
+
|
|
53
|
+
[tool.pytest.ini_options]
|
|
54
|
+
testpaths = ["tests"]
|
|
55
|
+
|
|
56
|
+
[tool.ruff]
|
|
57
|
+
target-version = "py39"
|
|
58
|
+
|
|
59
|
+
[tool.ruff.lint]
|
|
60
|
+
select = ["E", "W", "F", "I", "B", "UP"]
|
|
61
|
+
ignore = ["E501"]
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Build a context map site from a model file and a style file."""
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
"""Build the context map from a model file (what it describes) and a style file (how it looks).
|
|
2
|
+
|
|
3
|
+
Writes an interactive page (index.html), one static Mermaid page per view
|
|
4
|
+
(mermaid/*.html) and the same diagrams as Markdown (markdown/*.md), all under
|
|
5
|
+
the output directory.
|
|
6
|
+
|
|
7
|
+
Fails (exit 1) on unknown ids, duplicates, dependency cycles between bounded
|
|
8
|
+
contexts, and unknown or invalid Mermaid options, so a bad change breaks the
|
|
9
|
+
pipeline instead of the picture.
|
|
10
|
+
"""
|
|
11
|
+
import argparse
|
|
12
|
+
import json
|
|
13
|
+
import sys
|
|
14
|
+
from pathlib import Path
|
|
15
|
+
|
|
16
|
+
import yaml
|
|
17
|
+
|
|
18
|
+
from . import graph, mermaid
|
|
19
|
+
|
|
20
|
+
TEMPLATE_DIR = Path(__file__).parent / "template"
|
|
21
|
+
DIAGRAMS_KEYS = {"types", "clusters", "context-map", "mermaid"}
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
class StrictLoader(yaml.SafeLoader):
|
|
25
|
+
"""A SafeLoader that refuses duplicate keys, which would otherwise silently overwrite each other."""
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def _construct_mapping(loader, node, deep=False):
|
|
29
|
+
loader.flatten_mapping(node)
|
|
30
|
+
mapping = {}
|
|
31
|
+
for key_node, value_node in node.value:
|
|
32
|
+
key = loader.construct_object(key_node, deep=deep)
|
|
33
|
+
if key in mapping:
|
|
34
|
+
raise yaml.constructor.ConstructorError(
|
|
35
|
+
"while constructing a mapping", node.start_mark,
|
|
36
|
+
f"found duplicate key {key!r}", key_node.start_mark)
|
|
37
|
+
mapping[key] = loader.construct_object(value_node, deep=deep)
|
|
38
|
+
return mapping
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
StrictLoader.add_constructor(yaml.resolver.BaseResolver.DEFAULT_MAPPING_TAG, _construct_mapping)
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def read_yaml(path):
|
|
45
|
+
try:
|
|
46
|
+
return yaml.load(path.read_text(), Loader=StrictLoader)
|
|
47
|
+
except yaml.YAMLError as err:
|
|
48
|
+
sys.exit(f"error: {path}: {err}")
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def add_input_flags(parser):
|
|
52
|
+
"""The flags shared by the build and the serve commands."""
|
|
53
|
+
parser.add_argument("--model", type=Path, default=Path("context-map.yml"),
|
|
54
|
+
help="the model file (default: %(default)s)")
|
|
55
|
+
parser.add_argument("--diagrams", type=Path, default=Path("context-map.style.yml"),
|
|
56
|
+
help="the style file (default: %(default)s)")
|
|
57
|
+
parser.add_argument("--out", type=Path, default=Path("public"),
|
|
58
|
+
help="the directory to build into (default: %(default)s)")
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def parse_args(argv=None):
|
|
62
|
+
parser = argparse.ArgumentParser(
|
|
63
|
+
prog="context-mapper",
|
|
64
|
+
description="Build a context map site from a model file (what it describes) "
|
|
65
|
+
"and a style file (how it looks).",
|
|
66
|
+
epilog="Run 'context-mapper serve --watch' to serve the site and rebuild it "
|
|
67
|
+
"whenever the YAML files change.")
|
|
68
|
+
add_input_flags(parser)
|
|
69
|
+
return parser.parse_args(argv)
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def load(model_path, diagrams_path):
|
|
73
|
+
model = read_yaml(model_path)
|
|
74
|
+
diagrams = read_yaml(diagrams_path) or {}
|
|
75
|
+
data, errors = graph.normalize(model, diagrams)
|
|
76
|
+
|
|
77
|
+
for key in diagrams:
|
|
78
|
+
if key not in DIAGRAMS_KEYS:
|
|
79
|
+
errors.append(f"context-map.style.yml: {key}: unknown section. Known: {', '.join(sorted(DIAGRAMS_KEYS))}")
|
|
80
|
+
|
|
81
|
+
mermaid_cfg, mermaid_errors = mermaid.settings(diagrams.get("mermaid"))
|
|
82
|
+
errors += mermaid_errors
|
|
83
|
+
|
|
84
|
+
if not errors:
|
|
85
|
+
errors += mermaid.check(data, mermaid_cfg)
|
|
86
|
+
|
|
87
|
+
if errors:
|
|
88
|
+
for err in errors:
|
|
89
|
+
print(f"error: {err}", file=sys.stderr)
|
|
90
|
+
sys.exit(1)
|
|
91
|
+
|
|
92
|
+
# Contexts may depend on each other across domains in both directions without
|
|
93
|
+
# forming a context cycle. At domain level that is still worth knowing about.
|
|
94
|
+
cycle = graph.find_cycle(graph.level_graph(data, "domain"))
|
|
95
|
+
if cycle:
|
|
96
|
+
_, _, _, names = graph.index(data)
|
|
97
|
+
print("warning: domains depend on each other: " + " -> ".join(names[node] for node in cycle), file=sys.stderr)
|
|
98
|
+
|
|
99
|
+
return data, diagrams.get("mermaid")
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
def render_index(payload):
|
|
103
|
+
"""The interactive page: the skeleton with the stylesheet, the script and the model spliced in."""
|
|
104
|
+
html = (TEMPLATE_DIR / "index.html").read_text()
|
|
105
|
+
css = (TEMPLATE_DIR / "style.css").read_text().strip()
|
|
106
|
+
js = (TEMPLATE_DIR / "app.js").read_text().replace("/*__MODEL__*/null", payload).strip()
|
|
107
|
+
return html.replace("/*__STYLE__*/", css).replace("/*__SCRIPT__*/", js)
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
def build_site(args):
|
|
111
|
+
"""Build the whole site into args.out. Exits on missing or invalid input."""
|
|
112
|
+
for flag, path in (("--model", args.model), ("--diagrams", args.diagrams)):
|
|
113
|
+
if not path.exists():
|
|
114
|
+
sys.exit(f"error: {path} not found. Pass {flag} to set the path.")
|
|
115
|
+
data, mermaid_section = load(args.model, args.diagrams)
|
|
116
|
+
mermaid_cfg, _ = mermaid.settings(mermaid_section)
|
|
117
|
+
payload = json.dumps({**data, "mermaid": mermaid.client_settings(mermaid_cfg)}, ensure_ascii=False).replace("</", "<\\/")
|
|
118
|
+
html = render_index(payload)
|
|
119
|
+
index = args.out / "index.html"
|
|
120
|
+
args.out.mkdir(parents=True, exist_ok=True)
|
|
121
|
+
index.write_text(html)
|
|
122
|
+
print(f"built {index}: {len(data['domains'])} domains, "
|
|
123
|
+
f"{len(data['contexts'])} bounded contexts, {len(data['edges'])} dependencies")
|
|
124
|
+
count = mermaid.build(data, mermaid_section, args.out)
|
|
125
|
+
print(f"built {count} Mermaid views in {args.out}/mermaid/ and {args.out}/markdown/")
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
def main(argv=None):
|
|
129
|
+
argv = sys.argv[1:] if argv is None else list(argv)
|
|
130
|
+
if argv and argv[0] == "serve":
|
|
131
|
+
from .serve import serve
|
|
132
|
+
return serve(argv[1:])
|
|
133
|
+
build_site(parse_args(argv))
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
if __name__ == "__main__":
|
|
137
|
+
main()
|