@teurons/vds-diagrams 0.0.0-stage → 0.3.0
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 +170 -2
- package/dist/cli.js +2244 -0
- package/dist/diagrams.css +991 -0
- package/dist/grid.d.ts +1 -0
- package/dist/grid.js +283 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.js +2044 -0
- package/dist/skills/vds-aggregates/SKILL.md +115 -0
- package/dist/skills/vds-ask-or-park/SKILL.md +101 -0
- package/dist/skills/vds-book-to-spec/SKILL.md +136 -0
- package/dist/skills/vds-build-from-published/SKILL.md +89 -0
- package/dist/skills/vds-change/SKILL.md +113 -0
- package/dist/skills/vds-context-map/SKILL.md +125 -0
- package/dist/skills/vds-contexts/SKILL.md +134 -0
- package/dist/skills/vds-diagrams/SKILL.md +88 -0
- package/dist/skills/vds-entities-and-values/SKILL.md +108 -0
- package/dist/skills/vds-language/SKILL.md +106 -0
- package/dist/skills/vds-model-review/SKILL.md +123 -0
- package/dist/skills/vds-ports-and-adapters/SKILL.md +119 -0
- package/dist/skills/vds-publish/SKILL.md +123 -0
- package/dist/skills/vds-reframe/SKILL.md +122 -0
- package/dist/skills/vds-requirements/SKILL.md +128 -0
- package/dist/skills/vds-requirements-review/SKILL.md +121 -0
- package/dist/skills/vds-scenarios/SKILL.md +142 -0
- package/dist/skills/vds-slice-blocks/SKILL.md +127 -0
- package/dist/skills/vds-story-walk/SKILL.md +128 -0
- package/dist/skills/vds-strip-invented/SKILL.md +130 -0
- package/dist/skills/vds-subdomains/SKILL.md +127 -0
- package/dist/skills/vds-which-skill/FILE-SHAPES.md +312 -0
- package/dist/skills/vds-which-skill/SKILL.md +125 -0
- package/dist/types/diagrams/src/grid/camera.d.ts +32 -0
- package/dist/types/diagrams/src/grid/capability.d.ts +11 -0
- package/dist/types/diagrams/src/grid/fold-uj.d.ts +2 -0
- package/dist/types/diagrams/src/grid/grid-canvas.d.ts +95 -0
- package/dist/types/diagrams/src/grid/index.d.ts +5 -0
- package/dist/types/diagrams/src/grid/input.d.ts +93 -0
- package/dist/types/diagrams/src/grid/route.d.ts +21 -0
- package/dist/types/engine/js/bridge.d.ts +12 -0
- package/dist/types/engine/js/index.d.ts +73 -0
- package/dist/types/vds-diagrams/src/canvas.d.ts +43 -0
- package/dist/types/vds-diagrams/src/from-scenarios.d.ts +4 -0
- package/dist/types/vds-diagrams/src/grid-folds.d.ts +1 -0
- package/dist/types/vds-diagrams/src/grid.d.ts +2 -0
- package/dist/types/vds-diagrams/src/index.d.ts +6 -0
- package/dist/types/vds-diagrams/src/types.d.ts +39 -0
- package/dist/types/vds-diagrams/src/user-journey.d.ts +54 -0
- package/dist/types/vds-diagrams/src/workspace.d.ts +25 -0
- package/dist/vds_engine.wasm +0 -0
- package/dist/workspace.d.ts +1 -0
- package/dist/workspace.js +113 -0
- package/package.json +68 -3
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: vds-context-map
|
|
3
|
+
description: "Context map of a VDS workspace, and the external event: which context depends on which, the role of each side, and the facts that arrive. Use when a command is sent to another context, when another system's fact arrives at our edge, or when a relation lacks a direction, a role or a crossing. Where a boundary goes belongs to vds-contexts; building the anticorruption layer belongs to vds-ports-and-adapters; commands and our own events belong to vds-slice-blocks."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Context map
|
|
7
|
+
|
|
8
|
+
A relation between two contexts exists because something crosses between them: a command sent, or an event received. A story that crosses contexts is joined by these commands and events; it has no file of its own.
|
|
9
|
+
|
|
10
|
+
Use it in strategic design, once the two contexts exist. The context map is Vernon's: how the bounded contexts of the solution space relate through integration (p87).
|
|
11
|
+
Whether a context should exist or split, and opening a context of kind external, goes to vds-contexts. Which part of the business a context serves goes to vds-subdomains. The command itself and the event we store from a reply go to vds-slice-blocks. The port where translation is built goes to vds-ports-and-adapters.
|
|
12
|
+
|
|
13
|
+
## Method
|
|
14
|
+
|
|
15
|
+
1. **List what crosses.** Read every command whose `to:` names a context other than the one it sits in, every external event (`source: system`), and every read model that takes an event filed in another context. Add what the person says crosses and is not written yet. One line per crossing: what, from which context, to which.
|
|
16
|
+
Done when every line names one command or one external event by id, or quotes the person.
|
|
17
|
+
2. **Group the lines by pair of contexts.** One pair, one relation, however many commands and events cross it.
|
|
18
|
+
Done when every pair with a line has one relation, and no relation has zero lines.
|
|
19
|
+
3. **Name upstream and downstream.** Upstream is the context whose model and services the other depends on (Vernon p99-100). The context that receives our command and answers is upstream of us. The context an external event comes from is upstream of us.
|
|
20
|
+
Done when each relation has one upstream and one downstream context, both existing contexts.
|
|
21
|
+
4. **Pick the type and the roles with the person.** Walk the table below. Ask one question at a time, about the teams, in plain words.
|
|
22
|
+
Done when the person has answered for each relation, or the open one is handed to vds-ask-or-park.
|
|
23
|
+
`via` is optional. Ask "when we send it, do we wait for the answer, or carry on?": wait is `sync`, carry on is `async`, both is `[sync, async]`. Not known: leave `via` out and park the question in the same hot spot.
|
|
24
|
+
The person does not know, and the command must land now: write `type: upstream-downstream` with no roles, the type that claims no negotiation, and park "Does the team that runs X plan around what we need?" naming the relation in its text. Tell the person the type is a working one.
|
|
25
|
+
5. **Set `via`.** `sync` when we wait for the answer, `async` when the fact arrives later. Take it from the commands that cross (`via:` on the command) and from what the person says.
|
|
26
|
+
Done when every `via` value on the map is `sync` or `async`.
|
|
27
|
+
6. **Write each external event.** One file per fact that arrives, filed with the context it comes from. Format below.
|
|
28
|
+
Done when every event received from another context has a file naming that context and the fields this context uses, in this context's words.
|
|
29
|
+
7. **Write and check.** The check refuses a command to a context that is not on the map, so a relation and the first command that needs it land in one checked change (vds-slice-blocks writes the command, this skill the relation): `vds apply --base <rev>` (MCP: `vds_apply`). One file alone: `vds write <path> --base <rev>` (MCP: `vds_write`). Then `vds check` (MCP: `vds_check`).
|
|
30
|
+
Done when the check reports no problem that starts with `context map:` or ends with `is not on the context map`.
|
|
31
|
+
|
|
32
|
+
## Type and roles
|
|
33
|
+
|
|
34
|
+
| Ask the person | Answer | Write |
|
|
35
|
+
|---|---|---|
|
|
36
|
+
| "Does the team that runs X plan its work around what we need?" | yes, we negotiate | `type: customer-supplier` (Vernon p92-94: downstream priorities factor into upstream planning) |
|
|
37
|
+
| | no, X is what it is | `type: upstream-downstream` |
|
|
38
|
+
| "Do we turn X's data into our own words before we use it?" | yes | `roles: [ACL]` on downstream (p93; p101: the result "reflects a concept in terms of the downstream model") |
|
|
39
|
+
| | no, we use X's model as it comes | `roles: [CF]` on downstream (conformist, p93: no translation) |
|
|
40
|
+
| "Does X offer one documented way in for everyone who integrates?" | yes | `roles: [OHS]` on upstream, plus `PL` when its format is documented and shared (p93, p100) |
|
|
41
|
+
|
|
42
|
+
The check accepts only these role names: `OHS`, `PL` on upstream; `ACL`, `CF` on downstream. Roles are optional: the example's relation to its own notifications context has none. Roles sit only on `upstream-downstream` and `customer-supplier`, and `CF` and `ACL` never share an end: a Conformist takes the upstream model as it is, so it has no translation (Vernon p92-93). The check refuses a translation requirement whose relation has `CF` downstream.
|
|
43
|
+
Several labels may sit on one relation (Vernon fig 3.5: OHS/PL upstream and ACL downstream on the same link).
|
|
44
|
+
|
|
45
|
+
## Rules
|
|
46
|
+
|
|
47
|
+
- **Map what exists.** Vernon: map the present, never an imagined future (p89). A planned context goes on the map once its work has started (p98).
|
|
48
|
+
- **A system is a context.** A provider, a gateway or another team's service is a context of kind external or ours; it is never people. A context of ours can be upstream with no capability in the workspace, as the example's notifications context is.
|
|
49
|
+
- **An external event records their fact as it arrives at our edge, already in this context's words and value objects**, as the example does (`email: VO-AUTH--email`). Dilger (modeling): an external event is "a stable summary of the data" and "serves as a contract with external systems" (p91-92). Our own domain events change freely; this one changes only when the other side changes it.
|
|
50
|
+
- **Take the fewest fields.** Vernon: keep "only the minimal amount of state needed by the local model" (p104); a translated object that looks like the foreign one means "you are using too much" (p103).
|
|
51
|
+
- **Their words stop at the adapter.** The adapter's `does` says the translation (vds-ports-and-adapters). A requirement of type translation says what arrives and what it becomes: the external event, the command that takes it in, then our own event (vds-requirements, vds-slice-blocks). Vernon: the local context subscribes to external events and translates "foreign concepts into those of the local Bounded Context" (p183).
|
|
52
|
+
- **`sync` has a cost the person should hear.** When the other context is down, "the entire local execution must fail" (p103); asynchronous processing is "strategically favored" for autonomy (p104).
|
|
53
|
+
- **The key says `system`, the language says context.** `source: system` and `system: BC-...` are the spec's keys today; say "context" to the person.
|
|
54
|
+
|
|
55
|
+
## Right and wrong
|
|
56
|
+
|
|
57
|
+
Wrong, a relation with nothing behind it and a role on the wrong side:
|
|
58
|
+
|
|
59
|
+
```yaml
|
|
60
|
+
relationships:
|
|
61
|
+
- type: upstream-downstream
|
|
62
|
+
upstream:
|
|
63
|
+
context: BC-AUTH--neptune
|
|
64
|
+
roles: [ACL]
|
|
65
|
+
downstream:
|
|
66
|
+
context: BC-AUTH--cybrilla
|
|
67
|
+
via: [rest]
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
No command goes from one to the other and no event arrives. `ACL` is a downstream role. `via` takes `sync` or `async`.
|
|
71
|
+
|
|
72
|
+
Right, as in the example: a command `to: [BC-AUTH--cybrilla]` crosses and its reply arrives as an external event.
|
|
73
|
+
|
|
74
|
+
```yaml
|
|
75
|
+
relationships:
|
|
76
|
+
- type: upstream-downstream
|
|
77
|
+
upstream:
|
|
78
|
+
context: BC-AUTH--cybrilla
|
|
79
|
+
downstream:
|
|
80
|
+
context: BC-AUTH--investor-access
|
|
81
|
+
roles: [ACL]
|
|
82
|
+
via: [sync]
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
An external event: their fact, their context, in our words and value objects. Wrong is the same file named as our own event (`EVT-AUTH--profile-fetched`), carrying the other context's raw field names, or with no `source:` and `system:`.
|
|
86
|
+
|
|
87
|
+
```yaml
|
|
88
|
+
id: EVT-AUTH--provider-reply
|
|
89
|
+
name: Provider Reply
|
|
90
|
+
source: system
|
|
91
|
+
system: BC-AUTH--cybrilla
|
|
92
|
+
attributes:
|
|
93
|
+
- name: occurredOn
|
|
94
|
+
type: date
|
|
95
|
+
- name: email
|
|
96
|
+
type: VO-AUTH--email
|
|
97
|
+
optional: true
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
The check refuses an external event whose `system:` is no existing context, or one filed with a context other than its `system:`. Attribute types are `string`, `date`, `integer`, `boolean`, `list` or a value object; use a basic type until vds-entities-and-values writes the value object.
|
|
101
|
+
|
|
102
|
+
## Symptoms
|
|
103
|
+
|
|
104
|
+
| What you see or hear | Do |
|
|
105
|
+
|---|---|
|
|
106
|
+
| "we integrate with X", and no command or event names X | ask "what do we send X, or what does X tell us?"; no answer, vds-ask-or-park |
|
|
107
|
+
| the check says `<command>: for <our context>, BC-... is not on the context map`, or `<read model>: reads <event>, and ...` | add the relation joining those two contexts in the same change; a relation to the other context from somewhere else does not count |
|
|
108
|
+
| `go separate ways on the context map, so nothing is sent` | the person said nothing crosses; ask again, or remove the command |
|
|
109
|
+
| a relation whose contexts share no command and no external event | remove it, or find the crossing with the person |
|
|
110
|
+
| `ACL` on every relation | ask the translation question per relation; ours-to-ours may need none |
|
|
111
|
+
| an external event with the other context's raw field names or codes | rewrite in this context's words and value objects; the adapter's `does` says the translation |
|
|
112
|
+
| a person listed as the source of an external event | a system is a context; open it through vds-contexts |
|
|
113
|
+
| the open question "no port to <context>" | hand to vds-ports-and-adapters |
|
|
114
|
+
|
|
115
|
+
Never draw a relation with no command or event behind it. The check accepts such a relation, so only this skill stops it.
|
|
116
|
+
|
|
117
|
+
## Not covered
|
|
118
|
+
|
|
119
|
+
- Gateways and translators that exist only in code count for nothing. A relation is backed only by a command or an external event used in a scenario; a relation drawn from code alone passes the check unbacked, so mark it in a hot spot.
|
|
120
|
+
|
|
121
|
+
- `partnership`, `shared-kernel` and `separate-ways`: the check accepts these types with `contexts:` of exactly two different contexts, no example uses them, and Vernon never says whether partnership or shared kernel carry upstream and downstream. Separate ways means nothing crosses (p93-94), which this skill's Never rule excludes. Ask the person before writing any of the three.
|
|
122
|
+
- Big ball of mud (p93-94): the spec has no word for it. Direction: the check does not test that upstream and downstream match what crosses.
|
|
123
|
+
- Versioning an external event (Dilger p92-98): the spec has no key for it.
|
|
124
|
+
- The translation map (Vernon fig 3.7) and the adapter and translator of an anticorruption layer (p463-469): vds-ports-and-adapters.
|
|
125
|
+
- Drawing: the context map diagram is compiled by `vds compile`.
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: vds-contexts
|
|
3
|
+
description: "Bounded context of a VDS workspace: where one language and one model hold; kind ours, external or legacy; the subdomain it serves. Use on day 1, before the first story walk, to open one working context; between requirement discovery sessions, to read the clues a session left and propose a split or rename; when a step reaches an outside system, vendor picked or not. Core, supporting or generic belongs to vds-subdomains; relations between contexts to vds-context-map; recording terms to vds-language."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Contexts
|
|
7
|
+
|
|
8
|
+
A bounded context is principally a linguistic boundary (Vernon p62), so draw one only where the person's words show two languages, and keep one until they do.
|
|
9
|
+
|
|
10
|
+
Two moments use this skill. Day 1: open exactly one working context before vds-story-walk runs. Between requirement discovery sessions: read the clues the session left and propose candidates; the person decides each one.
|
|
11
|
+
Siblings own the neighbours. The subdomain's type (core, supporting, generic) is vds-subdomains. How contexts depend on each other, and the external events that cross, is vds-context-map. Recording a term or a clash is vds-language; this skill only reads what it recorded. A question nobody can answer goes to vds-ask-or-park.
|
|
12
|
+
|
|
13
|
+
When you write a file whose whole shape no skill shows, read `../vds-which-skill/FILE-SHAPES.md`.
|
|
14
|
+
## Day 1: one working context
|
|
15
|
+
|
|
16
|
+
1. **Check the home.** Run `vds index` (MCP: `vds_index`). If a context of kind ours exists, stop; vds-story-walk takes over. Steps 2 and 3 also open a second working context when the person says a new story is another part of the business (vds-story-walk step 1).
|
|
17
|
+
Done when the index shows no context of kind ours.
|
|
18
|
+
2. **Ask for two names.** Ask what the product is for, in one sentence, then what to call that part of the business. One question at a time. Offer the person's own words back as the working names.
|
|
19
|
+
Done when the person agreed one name for the subdomain and one for the context.
|
|
20
|
+
Ids carry a scope code: 2 to 5 capital letters from the name (Account Recovery: `ACCT`), the same in every id of this part. Say it to the person once; they may change it.
|
|
21
|
+
3. **Ask one question for the mark, then write three files in one change.** "Is this part why your business wins, something every business like yours needs done its own way, or something you could buy?" The answer is the working mark: core, supporting or generic, in that order. Never write a mark unasked. The files: the subdomain, the context serving it, and the context's language with no terms (`terms: []`). The check needs `type`, `does` and `why` on the subdomain: `does` is the person's sentence from step 2, `why` is `"Working mark: <the person's answer>"`; vds-subdomains refines it later. Use `vds apply --base <rev>` (MCP: `vds_apply`), then `vds check` (MCP: `vds_check`). The language file is needed now: the check refuses a capability in a context with no language file.
|
|
22
|
+
Done when the check reports no problem.
|
|
23
|
+
4. **Stop.** Say the names and the mark are working ones and a later session may rename, re-mark or split them. Hand on to vds-story-walk.
|
|
24
|
+
Done when no other context, subdomain, term or capability was written.
|
|
25
|
+
|
|
26
|
+
## Mid-step: a step reaches an outside system
|
|
27
|
+
|
|
28
|
+
A step whose command goes to a system we do not build needs that system as a context before the command can be written. Do this inside the step, so the agreed name is saved and never lives only in the conversation.
|
|
29
|
+
|
|
30
|
+
1. **Ask one question.** "Does your team build this, or does someone else?" We build it: it is ours, and a second ours context waits for the clues between sessions; keep the step in the working context. Someone else: go on.
|
|
31
|
+
Done when the person answered, or the step is held and the question parked with vds-ask-or-park.
|
|
32
|
+
2. **Name it by what it does when no vendor is picked.** "SMS Provider Context", never a guessed vendor name. Tell the person it is a working name; a rename later changes only `name`.
|
|
33
|
+
Done when the person agreed the name.
|
|
34
|
+
3. **Write it now.** Its id keeps the working context's scope code (`BC-AUTH--sms-provider`; the check refuses another). Write the context with `kind: external` and no `serves`, alone, through `vds write <path> --base <rev>`. The relation comes later, with the command that crosses: vds-context-map writes it in the change where vds-slice-blocks writes the command.
|
|
35
|
+
Done when the check passes and the context is in `vds index`.
|
|
36
|
+
|
|
37
|
+
## Between sessions: read the clues
|
|
38
|
+
|
|
39
|
+
1. **Collect the clues.** Read the session's language (each `tried` entry), its open hot spots and its requirements. List each clue with where it was said.
|
|
40
|
+
|
|
41
|
+
| Clue | Where it shows | Source |
|
|
42
|
+
|---|---|---|
|
|
43
|
+
| Two wordings for one thing | `tried` in the language, a hot spot | storming (Brandolini p196, p9) |
|
|
44
|
+
| One word, two meanings, both confirmed | a clash vds-language recorded: a `tried` entry, or a hot spot | Vernon p49, p63-66; modeling (Dilger p133-135) |
|
|
45
|
+
| The story hands over to another team | a narrator change: "this is where Mary's team takes over" | storming (Brandolini p95) |
|
|
46
|
+
| Who cares about which part | different people speak for different steps | Vernon p63-66, Book per lifecycle stage |
|
|
47
|
+
| The story reaches a system we do not build | a step with "no screen: another system answers" | storming (Brandolini p90-91); Vernon p61 |
|
|
48
|
+
|
|
49
|
+
Done when every clue has a quote and a place, or the list is empty.
|
|
50
|
+
2. **Decide each clue.** Walk the table top to bottom; the first row that fits wins.
|
|
51
|
+
|
|
52
|
+
| Question | Yes | No |
|
|
53
|
+
|---|---|---|
|
|
54
|
+
| Is the clue an outside system, built by someone else? | propose a context of kind external; its subdomain goes to vds-subdomains | next row |
|
|
55
|
+
| Is the reason teams, people, deploys, frameworks or services? | keep one context; say why | next row |
|
|
56
|
+
| Did the person confirm two meanings that both hold? | propose a split along the two meanings | keep one context |
|
|
57
|
+
| Does the person know enough to say where the line goes? | propose it | keep one; park the clue with vds-ask-or-park |
|
|
58
|
+
|
|
59
|
+
Done when each clue ends in "propose", "keep one" or "parked", with the row that decided it.
|
|
60
|
+
3. **Propose, one at a time.** Say the candidate, the clue behind it in the person's words, and which capabilities and terms would move. Ask yes or no. Offer no preference.
|
|
61
|
+
Done when the person said yes, no, or parked it, for every candidate.
|
|
62
|
+
4. **Write the yes.** A rename changes the context's `name`. A split writes the new context, moves each capability and each term that goes with it, and keeps a language file in each context that holds a capability. A new context of kind ours names the subdomain it serves in the same change; when that part is new, vds-subdomains writes it in that change. A context of kind external is written with no `serves`; vds-subdomains adds it. Use `vds apply` so the move is one checked change; run `vds show <ID>` first to list where the old id is mentioned.
|
|
63
|
+
Done when `vds check` passes, and vds-context-map has been told which new pair needs a relation.
|
|
64
|
+
|
|
65
|
+
## Rules
|
|
66
|
+
|
|
67
|
+
- **Keep one until the words differ.** Modeling (Dilger): "most of the time ... not split but keep everything in one system until you know more" (p134).
|
|
68
|
+
- **A context is as big as its language.** It holds the "complete Ubiquitous Language", "neither more nor less"; "don't be too quick to miniaturize" (Vernon p68-71).
|
|
69
|
+
- **Never split a context to divide work among people.** Splitting to hand tasks to developers gives fake contexts and a fragmented language (Vernon p68-71). Packaging and deploys are technical, never linguistic (same pages). Use a module for that instead (p68-71).
|
|
70
|
+
- **A context is no service.** Mapping contexts to microservices is "a big mistake"; one context can span many systems (Dilger p134, modeling).
|
|
71
|
+
- **Keep the same word in both.** After a split both contexts may say "Account"; names come from each language, never chosen to differ (Vernon p63-66).
|
|
72
|
+
- **An outside system is a context of kind external.** A system is never people (vds-language). Its language stays its own; we translate at our edge (Vernon p61).
|
|
73
|
+
- **Kind ours and legacy serve a subdomain.** The check refuses either with no `serves`, and refuses a subdomain no context serves. External may serve none.
|
|
74
|
+
- **The name ends in " Context".** Vernon's form is "<Model> Context" (p53-56); the check refuses any other.
|
|
75
|
+
- **Architecture waits for the developer.** Leave `architecture` out on day 1. The check needs `hexagonal` before any port is written (vds-ports-and-adapters).
|
|
76
|
+
|
|
77
|
+
## Right and wrong
|
|
78
|
+
|
|
79
|
+
Right, day 1: one context of kind ours, serving the one working subdomain.
|
|
80
|
+
|
|
81
|
+
```yaml
|
|
82
|
+
id: BC-AUTH--investor-access
|
|
83
|
+
name: Investor Access Context
|
|
84
|
+
serves: [SD-AUTH--investor-access]
|
|
85
|
+
kind: ours
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Wrong, day 1: a split before any session left a clue, cut by team (refused twice: no "Context" in the name, no subdomain).
|
|
89
|
+
|
|
90
|
+
```yaml
|
|
91
|
+
id: BC-AUTH--mobile-team
|
|
92
|
+
name: Mobile Team
|
|
93
|
+
kind: ours
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Right, an outside system the story reaches:
|
|
97
|
+
|
|
98
|
+
```yaml
|
|
99
|
+
id: BC-AUTH--captcha-provider
|
|
100
|
+
name: Captcha Provider Context
|
|
101
|
+
serves: [SD-AUTH--bot-protection]
|
|
102
|
+
kind: external
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Wrong, our own messaging system written as external because another team builds it. Neptune is built in-house, so it is ours:
|
|
106
|
+
|
|
107
|
+
```yaml
|
|
108
|
+
id: BC-AUTH--neptune
|
|
109
|
+
name: Neptune Context
|
|
110
|
+
kind: external
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
## Symptoms
|
|
114
|
+
|
|
115
|
+
| What you hear or see | Do |
|
|
116
|
+
|---|---|
|
|
117
|
+
| "front end and back end should each get a context" | keep one; that divides work (Vernon p68-71) |
|
|
118
|
+
| "let's set up all the contexts first" on day 1 | open one; the rest come from clues |
|
|
119
|
+
| The language has a `tried` entry still open | a clue; take it to step 2 between sessions |
|
|
120
|
+
| "the SMS goes out through Neptune" | ask whether we build it; ours or external |
|
|
121
|
+
| `vds check`: "must serve a subdomain" | the context needs `serves`; ask the person which part it serves |
|
|
122
|
+
| `vds check`: "no context serves it" | a split or rename left a subdomain alone; ask which context serves it |
|
|
123
|
+
| `vds check`: "language.yaml: missing" | the context holds a capability; write its language file |
|
|
124
|
+
|
|
125
|
+
Never split on day 1. Never split a context to divide work among people.
|
|
126
|
+
|
|
127
|
+
## Not covered
|
|
128
|
+
|
|
129
|
+
- Code that already has its contexts. Decided: the agent may read the code as a reference and propose contexts from it, and the person decides each one. The steps for doing so, and the optional fields that point at the code, are not written yet.
|
|
130
|
+
|
|
131
|
+
- Brandolini ch. 6, "Discovering Bounded Contexts with EventStorming" (p117-142): the notes mark it unread. Its clues and "homework time" (p134) are not covered here beyond what ch. 4 and ch. 13 hold.
|
|
132
|
+
- Kind legacy: the notes give no method for finding one. Vernon notes only that one legacy context may span subdomains (p48).
|
|
133
|
+
- Which architecture to pick: the notes in this skill's sources give none; the check knows only `hexagonal`.
|
|
134
|
+
- A working name has no mark in the files; the person is told in words. A working mark shows as a `why:` that starts "Working mark:".
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: vds-diagrams
|
|
3
|
+
description: Validate a VDS workspace, a scenario grid or a user journey, then render scenario diagrams and capability diagrams in React with @teurons/vds-diagrams (Full and user journey views). Use when asked to show, embed, render or check a VDS scenario diagram, capability diagram or user journey in an app, or to validate a VDS workspace or grid JSON before drawing it.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Validate, then render a VDS diagram
|
|
7
|
+
|
|
8
|
+
The order never changes: validate, compile if needed, then render. Never render a grid that has not been validated. A broken grid makes the canvas throw.
|
|
9
|
+
|
|
10
|
+
## 1. What you were given
|
|
11
|
+
|
|
12
|
+
| Input | Next step |
|
|
13
|
+
|---|---|
|
|
14
|
+
| A VDS workspace or its `domain/` folder | `checkWorkspace(files)`, then `compileScenarioGrids(files)` |
|
|
15
|
+
| A `.grid` file or grid JSON (`kind: grid, input: 1`) | `validateScenarioGrid(json)` |
|
|
16
|
+
| Screens and how a person moves between them, with no VDS workspace | Write a **user journey** (below), `validateUserJourney(json)`, render `<CapabilityDiagram userJourney/>` |
|
|
17
|
+
| A workspace that does not exist yet | Write it first with the VDS spec skills (vds-story-walk, vds-requirements, vds-scenarios and the rest of vds-*), shipped in this folder's siblings |
|
|
18
|
+
|
|
19
|
+
`files` (`WorkspaceFiles`) is `{ "<path under domain/>": "<file text>" }`, covering every file under `domain/`.
|
|
20
|
+
|
|
21
|
+
## 2. Validate
|
|
22
|
+
|
|
23
|
+
```ts
|
|
24
|
+
import { checkWorkspace, compileScenarioGrids } from '@teurons/vds-diagrams/workspace';
|
|
25
|
+
const { problems, incomplete } = await checkWorkspace(files);
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
- `problems` not empty: stop. Report each message with its path and line, and fix the workspace. Do not render.
|
|
29
|
+
- `incomplete` lists steps not modelled yet. A draft may hold them, and the scenario grids still compile. Tell the person which steps they are.
|
|
30
|
+
- Then `const grids = await compileScenarioGrids(files)` gives one scenario grid per scenario, keyed `DGSF-<code>-<hash>`.
|
|
31
|
+
|
|
32
|
+
For a grid alone, `validateScenarioGrid(json)` returns `[]` when the grid can be drawn, and otherwise one message per fault.
|
|
33
|
+
|
|
34
|
+
Done when there are no problems and you hold the grids.
|
|
35
|
+
|
|
36
|
+
## 3. Render
|
|
37
|
+
|
|
38
|
+
```tsx
|
|
39
|
+
'use client';
|
|
40
|
+
import { CapabilityDiagram, ScenarioDiagram } from '@teurons/vds-diagrams';
|
|
41
|
+
import '@teurons/vds-diagrams/diagrams.css';
|
|
42
|
+
|
|
43
|
+
<ScenarioDiagram scenarioGrid={grids['DGSF-AUTH-5b88996a']} view="full" />
|
|
44
|
+
<CapabilityDiagram scenarioGrids={Object.values(grids)} view="userJourney" />
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
- Choose the view by who reads it:
|
|
48
|
+
- **Full** for engineers: every lane, including commands, events, read models and other contexts.
|
|
49
|
+
- **User journey** (`view="userJourney"`, labelled UJ) for product people: screens, decisions, SMS, email and a backend summary.
|
|
50
|
+
- A capability diagram takes all the scenario grids of one capability, the ones whose ids share a code. Grids from two capabilities in one call give a wrong merge.
|
|
51
|
+
- The parent needs a height. The canvas fills it.
|
|
52
|
+
- In Next.js the canvas runs in the browser only, so mark the file `'use client'`.
|
|
53
|
+
|
|
54
|
+
Done when the diagram draws and the Full | UJ switch changes it.
|
|
55
|
+
|
|
56
|
+
## 4. A user journey, written directly
|
|
57
|
+
|
|
58
|
+
When someone wants the user journey of a whole capability and has no VDS workspace, write the user journey JSON (`kind: journey, input: 1`). Skip grids, compiling and merging. The grid is derived from it mechanically.
|
|
59
|
+
|
|
60
|
+
1. Screens: every screen the person sees, in the order they first meet it, as `{ id, title, render?, errors?, states? }`. `render` is the screen's json-render spec, exactly as the app renders it. Never simplify it.
|
|
61
|
+
2. Decisions: for each screen with more than one way on, list `{ after, ways: [{ when, to }] }`. One way per condition, each its own check. Never merge two conditions, even when they lead to the same screen. Two ways that turn out to be one fact are a finding to raise, not to merge.
|
|
62
|
+
3. Messages: each SMS or email the person receives, `{ id, channel, title, after }`, under the screen whose step sends it.
|
|
63
|
+
4. Backend: what the system does under a screen, `{ under, title }`, one line each.
|
|
64
|
+
5. Run `validateUserJourney`, fix every message, then render `<CapabilityDiagram userJourney renderScreen />`. With only a user journey there is one view, so no Full | UJ switch shows.
|
|
65
|
+
6. For one scenario, render `<ScenarioDiagram userJourney renderScreen />`. It must be one path: no screen with more than one way out. Check with `validateScenarioUserJourney`; the diagram shows the problems instead of drawing when it fails.
|
|
66
|
+
|
|
67
|
+
Done when the validator returns `[]` and every screen box shows its screen.
|
|
68
|
+
|
|
69
|
+
## 5. Grid@1 shape, for hand-written or generated grids
|
|
70
|
+
|
|
71
|
+
```json
|
|
72
|
+
{
|
|
73
|
+
"kind": "grid", "input": 1, "spec": "0.1",
|
|
74
|
+
"columns": [{ "id": "s0", "number": "1", "label": "Enter mobile" }],
|
|
75
|
+
"rows": [{ "id": "PPL-X--person", "kind": "actor", "label": "Person" }],
|
|
76
|
+
"boxes": [{ "id": "scr:0", "row": "PPL-X--person", "column": "s0", "kind": "scr", "title": "Enter mobile" }],
|
|
77
|
+
"arrows": [{ "from": "scr:0", "to": "scr:1", "label": "Submit Mobile" }]
|
|
78
|
+
}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
The rules `validateScenarioGrid` holds a grid to:
|
|
82
|
+
|
|
83
|
+
- Every id is unique.
|
|
84
|
+
- Every box names a row and a column that exist.
|
|
85
|
+
- Boxes in one row never overlap: a `span` covers that many columns.
|
|
86
|
+
- Arrows join boxes that exist.
|
|
87
|
+
|
|
88
|
+
The user journey fold reads row kinds `actor`, the person, and `inbox`, SMS or email. It reads box kinds `scr` (screen), `msg` (message), `cmd` (command) and `auto`, `call` and `ext` (system work). Keep those kinds so the user journey view folds correctly.
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: vds-entities-and-values
|
|
3
|
+
description: "Entity and value object in a VDS model: identity or value, rules on the value, and typed attributes. Use when a thing needs its identity decided, when an attribute is a bare string or number, when a person states a format, range or closed set, when a value arrives from another context, or when a value object's place is unclear. Aggregate boundaries and modules belong to vds-aggregates; commands, events and read models to vds-slice-blocks."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Entities and value objects
|
|
7
|
+
|
|
8
|
+
Make every modeled thing a value object unless it must be told apart and changes while staying itself, and put every rule about a value on its value object.
|
|
9
|
+
|
|
10
|
+
Use it in tactical modeling, after vds-slice-blocks has written the step's command, events and read model. vds-aggregates owns the boundary, the module and which events an aggregate owns. vds-language owns the term itself; a value object's name must already be a term. vds-ports-and-adapters owns the anticorruption layer. vds-model-review checks the result. A rule nobody stated goes to vds-ask-or-park.
|
|
11
|
+
|
|
12
|
+
## Method
|
|
13
|
+
|
|
14
|
+
1. **List the typed attributes.** Read every attribute on the step's commands, events, read models and entities. Done when each has its type written beside it, and each `string` or `integer` is marked.
|
|
15
|
+
2. **Decide entity or value object.** Walk the table; the first row that fits wins. Done when each thing has a row, and each entity's `why:` names both yes answers.
|
|
16
|
+
|
|
17
|
+
| # | Question | Yes means |
|
|
18
|
+
|---|---|---|
|
|
19
|
+
| 1 | Must it be told apart from another with the same attributes? (Vernon p171, p173) | go to 2; no means value object |
|
|
20
|
+
| 2 | Does it change over time and stay the same thing? (p171-172) | entity |
|
|
21
|
+
| 3 | Otherwise | value object. Vernon's four questions end "Describes, Yes, Yes, No" (p250) |
|
|
22
|
+
|
|
23
|
+
3. **Write the entity's identity.** Name the identity attributes, type them with an id value object (p177-178, p194), pick `source:` (user, application, persistence or another-bc, p173-174), and write `timing: early` so the creating event carries a real identity (p184, p186). The check allows an identity with no `type:` (the example's Session and Code Challenge); add one when other files carry the id. The entity's `commands:` list and its one `creates: true` come from vds-aggregates; a new root is drafted here and landed by vds-aggregates (its step 7) in one change with its aggregate. Done when the new root's draft is back with vds-aggregates, or `vds check` reports nothing for an entity already written.
|
|
24
|
+
4. **Shape the value object.** A closed set of named values gets `values:` (Vernon's Standard Type, p234-236; names only, no description text, p236). Parts that mean nothing apart get `attributes:` in one value object (Whole Value, p223-224). Done when it has `describes:` and either `values:` or `attributes:`.
|
|
25
|
+
5. **Put each rule on the value object.** Each format, length, range or expiry the person stated goes under `rules:` on the value object's attribute. A limit is written `{name}`. No rule stated: leave `rules:` out and park "what is a valid X?" through vds-ask-or-park. A rule here is one the value is checked against when it is made (Vernon p208, p221: a value object guards itself). How it is stored, or when something expires, belongs to the entity or aggregate that holds it. Done when no command, event, read model or entity attribute carries a rule while typed `string` or `integer`, and every rule is one a value can break when typed.
|
|
26
|
+
6. **Type the attributes.** Replace each bare type that names a value object's concept with the value object's id, in every command, event, read model and entity that carries it. Done when `vds check` passes and `vds show <VO-ID>` lists every file you meant to type.
|
|
27
|
+
7. **Place the value object by who shares it.** Count the aggregates whose files use it; commands and read models do not count. Done when each value object sits at its row below.
|
|
28
|
+
|
|
29
|
+
| Used by | Sits | In the example |
|
|
30
|
+
|---|---|---|
|
|
31
|
+
| one aggregate | inside that aggregate | Purpose, inside Code Challenge |
|
|
32
|
+
| two or more aggregates of one module | at the module | Subject and Channel, at Verification; InvestorId, at Access |
|
|
33
|
+
| aggregates in two modules, or none | at the model root | Mobile (Investor and Code Challenge); Code and MPIN (commands only) |
|
|
34
|
+
|
|
35
|
+
The check does not enforce placement (a moved value object still passes). The example puts Blocked Action at the root, though only the MPIN Credential aggregate uses it.
|
|
36
|
+
8. **Integrate with minimalism.** For a value from another context, keep only the attributes this context uses, as a value object (p232-233). Make it an entity here only when it must follow the other context's changes, and avoid that (p233). An identity another context assigned is `source: another-bc`; use it "as conservatively as possible" (p183). An external event file records the fact already in this context's words (vds-context-map), so its attributes take this context's value objects; the translation is said in the adapter's `does` (vds-ports-and-adapters). Done when each attribute of an external event this context reads is typed or kept bare with no rule.
|
|
37
|
+
|
|
38
|
+
## Rules
|
|
39
|
+
|
|
40
|
+
- Prefer value objects. Vernon: "Often a concept should be modeled as a Value" (p172); "strive to model using Value Objects instead of Entities wherever possible" (p219).
|
|
41
|
+
- A self-contained boolean or count with no rule stays bare: `wrongCount: integer`, `valid: boolean` (p232).
|
|
42
|
+
- Guard the value's parts. With an unguarded value "there is no way to guard against setting insane state" in the entity (p209-210).
|
|
43
|
+
- Name the value object from the context's language (p221). The check refuses a name the language lacks.
|
|
44
|
+
- A secret stays inside the aggregate (p200): the entity holds `mpinHash: string`; the rule "only a hash is stored" sits on the MPIN value object.
|
|
45
|
+
- A closed value object makes the check refuse a scenario value outside its set ("channel cannot be sms"). A scenario that used a placeholder ("relation given") gets a real value from the set; read the changed line back to the person, or park it when no person is there. A bare string with a written rule passes the check, so this bar is the only guard on it.
|
|
46
|
+
|
|
47
|
+
Right (the person said "the code is 6 digits and expires"):
|
|
48
|
+
```yaml
|
|
49
|
+
id: VO-AUTH--code
|
|
50
|
+
name: Code
|
|
51
|
+
describes: The one-time code an investor proves a channel with.
|
|
52
|
+
attributes:
|
|
53
|
+
- name: digits
|
|
54
|
+
type: string
|
|
55
|
+
required: true
|
|
56
|
+
rules:
|
|
57
|
+
- exactly 6 digits
|
|
58
|
+
- expires after {codeExpiryMinutes} minutes
|
|
59
|
+
```
|
|
60
|
+
Wrong (the rule sits on a bare string in a command; the check accepts it):
|
|
61
|
+
```yaml
|
|
62
|
+
attributes:
|
|
63
|
+
- name: code
|
|
64
|
+
type: string
|
|
65
|
+
rules:
|
|
66
|
+
- exactly 6 digits
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Right (a closed set):
|
|
70
|
+
```yaml
|
|
71
|
+
id: VO-AUTH--purpose
|
|
72
|
+
name: Purpose
|
|
73
|
+
describes: What a code is for.
|
|
74
|
+
values: [SignIn, VerifyEmail, ResetMpin]
|
|
75
|
+
```
|
|
76
|
+
Wrong (no reason, and a late identity the creating event cannot carry):
|
|
77
|
+
```yaml
|
|
78
|
+
id: ENT-AUTH--code-challenge
|
|
79
|
+
why: It has an id.
|
|
80
|
+
identity:
|
|
81
|
+
attributes: [codeChallengeId]
|
|
82
|
+
source: persistence
|
|
83
|
+
timing: late
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
## Symptoms
|
|
87
|
+
|
|
88
|
+
| The person says, or the draft shows | Do |
|
|
89
|
+
|---|---|
|
|
90
|
+
| "it must be a valid email", "10 digits" | rule on the value object's attribute |
|
|
91
|
+
| "it is one of A, B or C" | value object with `values:` |
|
|
92
|
+
| `no scenario rejects <field>.<part> that breaks "<rule>"` | hand to vds-scenarios for a rejection scenario; a rule nobody can type wrong (storage, expiry) moves off the value |
|
|
93
|
+
| `string` with `rules:` on an event or command | move the rule to a value object and type the attribute |
|
|
94
|
+
| an entity whose `why:` only says it has an id | ask whether it changes over time; if not, value object |
|
|
95
|
+
| amount and currency as two attributes | one value object holding both |
|
|
96
|
+
| a value object with no rules, and an open hot spot asks its format (Email, Mobile) | leave it; the hot spot holds the question |
|
|
97
|
+
| the other system sends ten fields, the step reads one | type only that one |
|
|
98
|
+
|
|
99
|
+
## Never
|
|
100
|
+
|
|
101
|
+
Never leave a rule on a bare string. Never write a rule the person did not state; park it.
|
|
102
|
+
|
|
103
|
+
## Not covered
|
|
104
|
+
|
|
105
|
+
- Writes go through `vds write` or `vds apply --base <rev>` (MCP: `vds_write`, `vds_apply`); check with `vds check` (`vds_check`).
|
|
106
|
+
- The spec has no field for identity stability, local identity inside an aggregate (p177), or whole-object validation (p211-216).
|
|
107
|
+
- `rules:` is free text; the check reads no meaning from it.
|
|
108
|
+
- The notes give no rule for where a value object sits; the placement table is VDS's reading of the example.
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: vds-language
|
|
3
|
+
description: "Language of a VDS bounded context: its terms, their meanings in the person's words, tried wordings, and the people files that name who acts. Use when a person says a new term, when two words name one thing, when one word carries two meanings, when a draft uses a word the language lacks, or when who acts needs a name. Where a boundary goes belongs to vds-contexts; wording and parking a question to vds-ask-or-park."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Language
|
|
7
|
+
|
|
8
|
+
Each bounded context keeps one language, recorded in the person's words, and every requirement, scenario and model block afterwards uses its terms exactly.
|
|
9
|
+
|
|
10
|
+
Use it in any phase, whenever a person names something. Requirement discovery adds most terms; tactical modeling adds the names of model blocks.
|
|
11
|
+
Siblings own the neighbours. Deciding where a boundary goes is vds-contexts; this skill only records a clash as a clue for it. How to word a question, and parking one as a hot spot, is vds-ask-or-park. Typing a step into a requirement is vds-requirements.
|
|
12
|
+
|
|
13
|
+
## Method
|
|
14
|
+
|
|
15
|
+
1. **Catch the word.** When a person uses a noun, verb or name that the spec will need, check the context's language for it.
|
|
16
|
+
Done when the word is either found in the language or marked as new.
|
|
17
|
+
2. **Pick the case.** Walk the table top to bottom; the first row that fits wins.
|
|
18
|
+
|
|
19
|
+
| What happened | Do |
|
|
20
|
+
|---|---|
|
|
21
|
+
| The word names who issues a command or is reached by one, and it is a person | Write a people file with the name only; add the term to the language too |
|
|
22
|
+
| The word names a system | Never a people file; the system is a bounded context, ours or external. Record its name as a term if the person uses it |
|
|
23
|
+
| The word is new and means one thing | Ask "What do you mean by <word>?" and write `means` from the answer. Never write `means` from your own summary of the talk; no answer: leave the term out (the check refuses a term with no meaning) and park it through vds-ask-or-park; a people file still lands when a command needs it |
|
|
24
|
+
| Two words name the same thing | Keep the term already in use. Add the other word under `tried` and ask the person which holds |
|
|
25
|
+
| One word carries two meanings | Ask the person which meaning holds here. If both hold, or the person cannot settle it, record both meanings in this context's language as a clash (step 4); vds-contexts reads these |
|
|
26
|
+
| The draft uses a word the person never said | Replace it with the language's term, or ask what the person calls it |
|
|
27
|
+
|
|
28
|
+
Done when the row that fits can be named.
|
|
29
|
+
3. **Ask, one question.** For a clash, quote both wordings and where each was said, and ask which holds. Offer no answer. If the person cannot say, park it through vds-ask-or-park.
|
|
30
|
+
Done when the person chose, said both hold in two places, or a hot spot is open.
|
|
31
|
+
4. **Record the answer.** Write the chosen term. Under `tried`, set `kept` and write `why` in the person's reason. A clash of two meanings stays in this context's language: `means` holds one meaning, and a `tried` entry with the same word holds the other, its `why` saying both hold (a term cannot be listed twice). If the person cannot settle it, add a hot spot through vds-ask-or-park. vds-contexts reads these entries; terms move to a new context only after it splits on the person's yes.
|
|
32
|
+
Done when `vds check` passes and no clash is left without an answer or a hot spot.
|
|
33
|
+
5. **Use the term everywhere.** Rename the word in every requirement statement, scenario line, screen title and model block of this context, in one `vds_apply` change: a requirement's title and its Feature line must stay equal. This covers a rename whose meaning is unchanged; in a published capability vds-change orders the work and this skill still renames. A changed meaning is never a rename: vds-reframe, or vds-change when published.
|
|
34
|
+
Done when a search of the context finds the old word only under `tried`.
|
|
35
|
+
|
|
36
|
+
## Rules
|
|
37
|
+
|
|
38
|
+
- Record the meaning in the person's words. The language belongs to the whole team, built by consensus, and "not the language of the business" alone (Vernon p20-21).
|
|
39
|
+
- Keep the wordings that did not work, and why. Vernon's glossary lists "alternative terms", the promising ones and the ones that failed (p22).
|
|
40
|
+
- **Never settle a clash by picking a word yourself.** The person decides; a clash left in the open is a clue, and an early agreement hides it.
|
|
41
|
+
- Keep both wordings visible while the clash is open. Storming (Brandolini): different meanings are "not a bad thing"; "resist the temptation to reach a premature agreement" (p196). Duplicates and other wordings stay "for the moment" (p9).
|
|
42
|
+
- Treat a language clash as a clue for a boundary. Storming (Brandolini): "apparent language inconsistencies are often an indicator of multiple Bounded Contexts within the same process" (p196). Vernon: a bounded context is "principally a linguistic boundary" (p62).
|
|
43
|
+
- One language per context. Two contexts may use the same word with different meanings; only the context tells them apart (Vernon p25, p63-66, "Account").
|
|
44
|
+
- The same person gets a name per context. Vernon's Identity and Access says User and Role; Collaboration, downstream, says Moderator (p232-233). Write the name each context speaks.
|
|
45
|
+
- A people file holds a name only. Who acts is a language term; a system is never people (it is a bounded context).
|
|
46
|
+
- Write a people file in the change that lands the first command naming it in `by:` or `reaches:`. Before that the name lives in the walk and the language term.
|
|
47
|
+
- Name model blocks from the language. `vds check` fails a value object, entity, aggregate or module whose name is not a term of its context, and a term listed twice or with no meaning.
|
|
48
|
+
- In tactical modeling the developer is the person who gives a model term its meaning (Vernon p20-21: the language belongs to the whole team). With no one there, write `means` from the requirement's own words and park "Is this what <term> means?" through vds-ask-or-park.
|
|
49
|
+
- Write through `vds_write`, or `vds_apply` for several files, and run `vds check`.
|
|
50
|
+
|
|
51
|
+
## The files
|
|
52
|
+
|
|
53
|
+
The context's language holds `terms`, each with `term`, `means`, and an optional `tried` list of `term`, `kept`, `why`. A people file holds `id` (`PPL-<SCOPE>--<slug>`) and `name`. Commands point at people with `by:` and `reaches:`.
|
|
54
|
+
|
|
55
|
+
Right: the person's meaning, and the wording that was tried and dropped.
|
|
56
|
+
|
|
57
|
+
```yaml
|
|
58
|
+
- term: Lock
|
|
59
|
+
means: "A stop of {lockMinutes} minutes after {lockAfterWrong} wrong tries, shown on the same screen."
|
|
60
|
+
tried:
|
|
61
|
+
- term: Blocked
|
|
62
|
+
kept: false
|
|
63
|
+
why: "It was drawn as a screen; a lock is a message on the screen."
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Wrong: the agent's own definition, and the other wording thrown away.
|
|
67
|
+
|
|
68
|
+
```yaml
|
|
69
|
+
- term: Lock
|
|
70
|
+
means: "Account lockout after N failed authentication attempts (rate limiting)."
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Right: a person, by name only.
|
|
74
|
+
|
|
75
|
+
```yaml
|
|
76
|
+
id: PPL-AUTH--ops
|
|
77
|
+
name: Ops
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Wrong: a system written as people, with fields a people file does not hold.
|
|
81
|
+
|
|
82
|
+
```yaml
|
|
83
|
+
id: PPL-AUTH--neptune
|
|
84
|
+
name: Neptune
|
|
85
|
+
role: "Sends SMS and email"
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Neptune is a bounded context; the language records it as a term ("Our system that sends messages to people").
|
|
89
|
+
|
|
90
|
+
## Symptoms
|
|
91
|
+
|
|
92
|
+
| What you see | Do |
|
|
93
|
+
|---|---|
|
|
94
|
+
| The person says OTP, the spec says Code | Ask which holds; record the other under `tried` |
|
|
95
|
+
| Two people use one word for different things | Ask which holds here; if both, record the clash for vds-contexts |
|
|
96
|
+
| `vds check`: "X is not in the language" | Ask the person what they call it; add the term, or rename the block |
|
|
97
|
+
| `vds check`: "X appears twice" | Two entries for one word: ask which meaning holds |
|
|
98
|
+
| A `means` reads in technical words | Ask the person to say it again; write their words |
|
|
99
|
+
| A requirement says "user" and the language says Investor | Use Investor |
|
|
100
|
+
| A people file for a payment provider or a captcha | Remove it; the system is a context |
|
|
101
|
+
|
|
102
|
+
## Not covered
|
|
103
|
+
|
|
104
|
+
- Brandolini ch6, "Discovering Bounded Contexts with EventStorming": not read in the notes. Not covered.
|
|
105
|
+
- What `kept: true` means beyond the example's one use (OTP kept, "The notes say OTP; the spec says Code"): no rule in the notes or the checks.
|
|
106
|
+
- Where a person's role differs per context: spec 0.1 shares the people files across contexts and has no per-context name. Not covered.
|