The spec and its kinds

Artefacts and revisions#

Every element of the spec is an artefact of one kind. Its id never changes; every edit writes a new, immutable revision. The app shows names, never ids; URLs and the API use ids; YAML uses names, as in kind/Name and Context/Name.

Names are unique per kind in their container: two aggregates of one bounded context cannot share a name, but the same name in two contexts is fine. Archiving is the soft delete: an archived artefact is read-only until it is restored.

The 14 kinds#

The sidebar follows these groups. Aggregates, value objects and enums are reached through their bounded context, on its Model tab.

Main and workstreams#

The spec you read depends on where you read it. Main is the agreed spec; a workstream sees Main plus its own changes; what an agent staged waits in a proposal until a person accepts it.

Every read names its scope: main, workstream:WS-n, or proposal:<id> for what an agent staged. Agents read workstream:WS-n while the spec of a change is in flight: that is where accepted changes are, until a task publishes them to Main. See Workstreams and Tasks and publishing.

References#

Artefacts refer to each other by id: a use case to its roles, a property type to a value object, an event handler to the domain event or integration event that triggers it, a bounded context to the subdomains it implements. Renaming an artefact never breaks a reference.

Editing#

People edit on each artefact's page. Every field saves as you go, with the revision it started from, so two people editing different fields both keep their edits, and an edit to the same field at once is refused with the current version.

Main is read-only. To change it, open a workstream, or use Fix on an artefact of Main, which opens a workstream and a task for it.

Next steps#

• Subdomains and bounded contexts→The business areas and the parts of the system that implement them.
• Workstreams→Where changes to the spec are made before a task publishes them to Main.