@miragon/team-topologies-schema-model 0.1.0 → 0.3.1
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.
- package/README.md +172 -0
- package/package.json +4 -4
package/README.md
ADDED
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
# @miragon/team-topologies-schema-model
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@miragon/team-topologies-schema-model)
|
|
4
|
+
[](https://github.com/Miragon/team-topologies-modeler/blob/main/LICENSE)
|
|
5
|
+
|
|
6
|
+
The **DOM-free core** of the [Team Topologies Modeler](../../README.md): the data model, the notation
|
|
7
|
+
specification, runtime validation, version migrations and deterministic JSON serialization for
|
|
8
|
+
[Team Topologies](https://teamtopologies.com/) diagrams.
|
|
9
|
+
|
|
10
|
+
This package has **no view, no DOM and no diagram-js** — it is plain TypeScript that runs anywhere
|
|
11
|
+
(browser, Node, an edge function, a CLI). The browser renderer
|
|
12
|
+
([`@miragon/team-topologies-renderer`](../renderer)), the web app and the VS Code extension all build
|
|
13
|
+
on top of it. The DOM-freedom is enforced in CI (ESLint `no-restricted-imports` /
|
|
14
|
+
`no-restricted-globals` **and** `dependency-cruiser`), so a stray `diagram-js`/`window`/`document`
|
|
15
|
+
reference fails the build.
|
|
16
|
+
|
|
17
|
+
## Install
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
npm install @miragon/team-topologies-schema-model
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## What's inside
|
|
24
|
+
|
|
25
|
+
- **The notation spec** — the four team types and three interaction modes, with their official
|
|
26
|
+
shapes, colours and stroke styles as plain data you can read and render against.
|
|
27
|
+
- **The document model** — a small, stable shape (`TtDocument`) with `version`, `title`, `nodes`,
|
|
28
|
+
`interactions` and `flows`.
|
|
29
|
+
- **Runtime validation** — Zod schemas + `parseDocument()` for everything that comes from a file, a
|
|
30
|
+
URL or `localStorage`.
|
|
31
|
+
- **Forward migrations** — `parseDocument()` migrates older documents up to the current version
|
|
32
|
+
before validating, keyed by the document `version`.
|
|
33
|
+
- **Deterministic serialization** — sorted, rounded and version-stamped output, so `.tt` /
|
|
34
|
+
`.ttm.json` files diff cleanly and share URLs stay stable.
|
|
35
|
+
- **Factories & a sample** — helpers that create well-formed elements and documents, plus a complete
|
|
36
|
+
example topology.
|
|
37
|
+
|
|
38
|
+
## The document format
|
|
39
|
+
|
|
40
|
+
A diagram is a single JSON object. Interactions are **placed shapes** that overlap the teams they
|
|
41
|
+
relate to (spatial overlap, the Team Topologies convention) — there is no source/target reference.
|
|
42
|
+
|
|
43
|
+
```jsonc
|
|
44
|
+
{
|
|
45
|
+
"version": 2,
|
|
46
|
+
"title": "Online retail — team topology",
|
|
47
|
+
"nodes": [
|
|
48
|
+
{
|
|
49
|
+
"id": "team_checkout",
|
|
50
|
+
"type": "stream-aligned",
|
|
51
|
+
"label": "Checkout Stream",
|
|
52
|
+
"position": { "x": 320, "y": 110 },
|
|
53
|
+
"size": { "width": 240, "height": 96 },
|
|
54
|
+
},
|
|
55
|
+
],
|
|
56
|
+
"interactions": [
|
|
57
|
+
{
|
|
58
|
+
"id": "int_platform_checkout",
|
|
59
|
+
"mode": "x-as-a-service",
|
|
60
|
+
"position": { "x": 384, "y": 396 },
|
|
61
|
+
"size": { "width": 96, "height": 96 },
|
|
62
|
+
},
|
|
63
|
+
],
|
|
64
|
+
"flows": [],
|
|
65
|
+
}
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
| Field | Type | Notes |
|
|
69
|
+
| -------------- | -------------------- | ------------------------------------------------------------------------------------ |
|
|
70
|
+
| `version` | `2` | `DOCUMENT_VERSION`; older versions are migrated up on parse. |
|
|
71
|
+
| `title` | `string` | Diagram name. |
|
|
72
|
+
| `nodes` | `TeamNode[]` | A team: `type`, `label`, `position`, `size`, optional `description`/`fill`/`stroke`. |
|
|
73
|
+
| `interactions` | `InteractionShape[]` | A placed interaction: `mode`, `position`, `size`, optional `label`/`fill`/`stroke`. |
|
|
74
|
+
| `flows` | `FlowShape[]` | A flow-of-change band: `position`, `size`, optional `label`. |
|
|
75
|
+
|
|
76
|
+
## Notation
|
|
77
|
+
|
|
78
|
+
The single source of truth for the visual notation. Shapes and colours follow the official
|
|
79
|
+
[Team-Shape-Templates](https://github.com/TeamTopologies/Team-Shape-Templates) — every element is
|
|
80
|
+
distinguished by shape **and** colour, so diagrams survive colour-vision deficiency and greyscale
|
|
81
|
+
printing. Team shapes are **solid** (long-lived); interaction shapes are **dashed and translucent**
|
|
82
|
+
(short-lived).
|
|
83
|
+
|
|
84
|
+
### Team types — `TEAM_TYPE_SPECS`
|
|
85
|
+
|
|
86
|
+
| `type` | Label | Shape | Fill / Stroke |
|
|
87
|
+
| ----------------------- | --------------------- | ---------------------------- | --------------------- |
|
|
88
|
+
| `stream-aligned` | Stream-aligned | horizontal rounded rectangle | `#FFEDB8` / `#FFD966` |
|
|
89
|
+
| `enabling` | Enabling | vertical rounded rectangle | `#DFBDCF` / `#D09CB7` |
|
|
90
|
+
| `complicated-subsystem` | Complicated Subsystem | octagon | `#FFC08B` / `#E88814` |
|
|
91
|
+
| `platform` | Platform | square-cornered rectangle | `#B7CDF1` / `#6D9EEB` |
|
|
92
|
+
|
|
93
|
+
### Interaction modes — `INTERACTION_MODE_SPECS`
|
|
94
|
+
|
|
95
|
+
| `mode` | Label | Glyph | Fill / Stroke |
|
|
96
|
+
| ---------------- | -------------- | ------------------------------------- | --------------------- |
|
|
97
|
+
| `collaboration` | Collaboration | parallelogram | `#C6BEDF` / `#967EE2` |
|
|
98
|
+
| `x-as-a-service` | X-as-a-Service | triangle (points provider → consumer) | `#B4B4B4` / `#999696` |
|
|
99
|
+
| `facilitating` | Facilitating | circle | `#C9DFBE` / `#78996B` |
|
|
100
|
+
|
|
101
|
+
The **flow of change** is described separately by `FLOW_SPEC` (a left-to-right dashed band).
|
|
102
|
+
|
|
103
|
+
## Usage
|
|
104
|
+
|
|
105
|
+
```ts
|
|
106
|
+
import {
|
|
107
|
+
emptyDocument,
|
|
108
|
+
createTeamNode,
|
|
109
|
+
createInteractionShape,
|
|
110
|
+
serializeDocument,
|
|
111
|
+
parseDocument,
|
|
112
|
+
SAMPLE_DOCUMENT,
|
|
113
|
+
} from "@miragon/team-topologies-schema-model";
|
|
114
|
+
|
|
115
|
+
// Build a document with the factories (notation defaults applied automatically)
|
|
116
|
+
const doc = emptyDocument("Online retail");
|
|
117
|
+
doc.nodes.push(createTeamNode("stream-aligned", { x: 320, y: 110 }));
|
|
118
|
+
doc.interactions.push(createInteractionShape("x-as-a-service", { x: 384, y: 396 }));
|
|
119
|
+
|
|
120
|
+
// Serialize deterministically (sorted, rounded, version-stamped) — diff- and URL-stable
|
|
121
|
+
const json = serializeDocument(doc);
|
|
122
|
+
|
|
123
|
+
// Validate + migrate anything untrusted (file / URL / localStorage)
|
|
124
|
+
const result = parseDocument(JSON.parse(json));
|
|
125
|
+
if (result.ok) {
|
|
126
|
+
console.log(result.document.title);
|
|
127
|
+
} else {
|
|
128
|
+
console.error(result.error);
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
// A ready-made example topology
|
|
132
|
+
console.log(SAMPLE_DOCUMENT.title);
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
### API surface
|
|
136
|
+
|
|
137
|
+
| Export | Purpose |
|
|
138
|
+
| ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
|
|
139
|
+
| `TtDocument`, `TeamNode`, `InteractionShape`, `FlowShape`, `Position`, `Size` | The document model types. |
|
|
140
|
+
| `TeamType`, `InteractionMode`, `TEAM_TYPES`, `INTERACTION_MODES` | The notation's discriminator unions + their value lists. |
|
|
141
|
+
| `TEAM_TYPE_SPECS`, `INTERACTION_MODE_SPECS`, `FLOW_SPEC`, `dashArray()` | The visual notation spec (shapes, colours, strokes) as data. |
|
|
142
|
+
| `documentSchema`, `teamNodeSchema`, `interactionSchema`, `flowSchema` | Zod schemas for each shape. |
|
|
143
|
+
| `parseDocument()`, `ParseResult` | Validate **and migrate** unknown input into a `TtDocument`. |
|
|
144
|
+
| `serializeDocument()`, `canonicalize()` | Deterministic JSON serialization (sorted, rounded, fixed key order). |
|
|
145
|
+
| `emptyDocument()`, `createTeamNode()`, `createInteractionShape()`, `createFlowShape()`, `newId()` | Factories with notation defaults + id generation. |
|
|
146
|
+
| `SAMPLE_DOCUMENT` | A complete example topology. |
|
|
147
|
+
| `DOCUMENT_VERSION` | The current document version (`2`). |
|
|
148
|
+
|
|
149
|
+
## Determinism & migrations
|
|
150
|
+
|
|
151
|
+
- **Determinism** — `serializeDocument()` runs `canonicalize()` first: arrays are sorted by `id`,
|
|
152
|
+
coordinates are rounded to two decimals, optional fields with no value are dropped, and keys are
|
|
153
|
+
written in a fixed order. The same logical diagram always produces byte-identical JSON, which is
|
|
154
|
+
what makes Git diffs small and share URLs stable.
|
|
155
|
+
- **Migrations** — `parseDocument()` upgrades older documents before validating (keyed by `version`).
|
|
156
|
+
The `1 → 2` step drops the legacy `showFlowOfChange` flag and the old edge-based interactions,
|
|
157
|
+
keeping only interactions that carry geometry (the placed-shape model).
|
|
158
|
+
|
|
159
|
+
## Development
|
|
160
|
+
|
|
161
|
+
This package is part of the [Team Topologies Modeler](../../README.md) monorepo and is normally
|
|
162
|
+
consumed from source. From the repo root:
|
|
163
|
+
|
|
164
|
+
```bash
|
|
165
|
+
npm run build -w packages/schema-model # tsup → dist/ (publish build)
|
|
166
|
+
npm test # Vitest unit tests
|
|
167
|
+
npm run typecheck # tsc, compiled WITHOUT the DOM lib
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
## License
|
|
171
|
+
|
|
172
|
+
[MIT](../../LICENSE).
|
package/package.json
CHANGED
|
@@ -1,15 +1,15 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@miragon/team-topologies-schema-model",
|
|
3
|
-
"version": "0.1
|
|
3
|
+
"version": "0.3.1",
|
|
4
4
|
"description": "The Team Topologies data model with types, the notation specification, runtime validation, migrations and deterministic JSON serialization.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
7
7
|
"type": "git",
|
|
8
|
-
"url": "git+https://github.com/
|
|
8
|
+
"url": "git+https://github.com/Miragon/team-topologies-modeler.git",
|
|
9
9
|
"directory": "packages/schema-model"
|
|
10
10
|
},
|
|
11
|
-
"homepage": "https://github.com/
|
|
12
|
-
"bugs": "https://github.com/
|
|
11
|
+
"homepage": "https://github.com/Miragon/team-topologies-modeler/tree/main/packages/schema-model#readme",
|
|
12
|
+
"bugs": "https://github.com/Miragon/team-topologies-modeler/issues",
|
|
13
13
|
"type": "module",
|
|
14
14
|
"sideEffects": false,
|
|
15
15
|
"exports": {
|