Managing Artifacts in Spec-Driven Development: The Model Atlas

Part of the series Domain-Driven Design Meets AI.

In spec-driven development, the specification is not a single document. It is every artifact a team produces along the way, from the first brainstorm to the API contracts. This post shows how a domain knowledge graph keeps those artifacts together with their history, and how the Model Atlas makes them visible.

Where modeling knowledge gets lost

Every collaborative modeling effort leaves a trail of artifacts behind. A brainstorming wall, a Business Model Canvas, an Impact Map, a Capability Map, a handful of Domain Stories, an EventStorming board, a Context Map, Visual Glossaries, API Product Canvases, and finally OpenAPI and AsyncAPI specifications.

Most of them end up as pictures in a shared folder. Different people create them in different workshops, probably weeks apart. By the time a developer writes the first API contract, nobody remembers why the Notification aggregate lost its status field, or which sticky on which board first named the Notification context.

Domain-Driven Design rests on a shared Ubiquitous Language (Evans, 2003). If that language is scattered across photos, screenshots, and memories, it is not shared. It is merely stored.

In our book DDD Meets AI, we follow a fictitious community cooking platform called Larder through the Synergetic Blueprint: a guided sequence of collaborative modeling steps from the first brainstorm to the implementation. Every accepted artifact of every step goes into one domain knowledge graph, and the Model Atlas shows how they connect. Together, these artifacts form the specification.

One graph for every artifact

The domain knowledge graph is a single Resource Description Framework (RDF) graph written in Turtle (Beckett et al., 2014). It follows the general idea of a knowledge graph: entities and their relationships, plus the context needed to interpret them (Hogan et al., 2021). Each artifact is ingested one at a time by an AI skill, and each ingest merges into the existing graph instead of creating a new one.

For Larder, the graph grew in 62 ingests: from the brainstorm through Impact Maps, Capability Maps, Domain Stories, EventStorming boards, and Context Maps, to API Product Canvases, per-aggregate Visual Glossaries, and finally the OpenAPI and AsyncAPI contracts.

Three design decisions make the graph trustworthy rather than just big:

• Provenance on every node. Each term, relationship, or message records which artifact it came from and where on that artifact (for example, “Shopping branch, sticky 3 (yellow)”).
• Honest confidence. Each statement is marked as read directly from the artifact, implied by it, or inferred by the AI. In the Larder graph, 863 statements sit on the artifacts, 73 are implied, and 35 are inferred.
• Original spelling kept. Terms are stored with SKOS labels (Miles & Bechhofer, 2009), so “re ceiver” on a hand-drawn glossary stays visible as an alternative label of “receiver” instead of silently disappearing.

A typical node looks like this:

The graph also records what it does not know. When the first Context Map introduced Consent Management and Notification, no story, board event, glossary term, or capability had mentioned them before. The ingest did not paper over this; it raised an open question in the graph. Larder’s graph holds 86 such questions.

History instead of overwrite

The graph never overwrites. When a new picture arrives, the ingest first decides whether it grows the model or revises an earlier artifact. It compares the new artifact with existing ones: how much of the new content is already known, and how much of the old content the new one still covers. When the second Capability Map arrived, 95% of its content was shared with the first one, and it covered 90% of it, so it was recorded as a revision. In unclear cases, the skill asks instead of guessing.

A revision keeps the old statements and links the new ones to them:

• dkg:revisionOf connects the new artifact to its predecessor.
• dkg:supersedes connects a changed statement, such as a reclassified capability or a redrawn cardinality, to the statement it replaces.
• dkg:absentFrom records that something was dropped, rather than deleting it.

The Notification aggregate shows why this matters. Version 1 of its Visual Glossary attached receiver and status directly to the Notification. In version 2, the team introduced a delivery value object: a Notification contains one or more deliveries, and each delivery carries its receivers and a delivery status (NEW or READ). Version 2 also added an audience type (single or community).

In a folder of photos, version 1 simply disappears or it is available, a diff is highly difficult. In the graph, both versions remain, and the move of status to delivery is an explicit, queryable fact:

This lets a team challenge earlier decisions with today’s knowledge, instead of re-arguing them from memory. It is a form of living documentation: knowledge captured as a by-product of the work, not written up afterward (Martraire, 2019).

The Model Atlas: seeing the graph

A Turtle file with almost 6,000 lines is complete, but nobody reads it. The Model Atlas is a single HTML page that loads any graph of this kind (drop in a .ttl file, e.g., Larder) and lays it out as a map of artifacts rather than a hairball of nodes that only a cat could enjoy.

The Atlas groups artifacts by what they are: workshop artifacts (brainstorm, canvases, maps, stories, boards), design artifacts (aggregate glossaries, Bounded Context Canvases, ADR logs), and specifications (OpenAPI and AsyncAPI). Per Bounded Context, it then draws one lane from left to right: the context, its API Product Canvases, its aggregate glossaries, and the API specifications derived from them.

Three things become visible at a glance:

• Dependencies. You can see which canvas fed which glossary, and which glossary fed which contract. The Notification context, for example, has an asynchronous and a synchronous canvas, both pointing to the Notification model v2, which in turn feeds the AsyncAPI and the OpenAPI specification.
• Versions. Superseded artifacts stay on the map, dimmed and dashed. When comparing two versions, the Atlas distinguishes what was added in the newer version, what exists only in the older one, and what was explicitly recorded as dropped.
• Gaps. A lane without a glossary or without a contract stands out immediately. In the excerpt, the Grandma Avatar AI context goes straight from its canvas to its AsyncAPI specification, with no aggregate glossary in between.

The Atlas can also replay the graph. A slider steps through the ingests in order, so you watch the model grow: first the brainstorm, then the strategy artifacts with their revisions, then the stories and the language.

![Replay at step 11 of 62: the brainstorm, three Impact Map versions, two Business Model Canvas versions, three Capability Map versions, and the first two Domain Stories.(https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/cmvcgk7bywivh07uq5287tru7)

Replay turns the graph into a story of the project. New team members can follow how the model came to be, and the team can stop at any step and ask whether a decision taken then still holds now.

Why this matters for API contracts

The graph pays off at every step of the blueprint, and the API contracts are where it becomes most tangible. In our book, we generated OpenAPI and AsyncAPI specifications twice: once from the API Product Canvases and once from the domain model. Both versions go into the same graph as the artifacts they were derived from.

That makes consistency checks cheap. An AI skill can compare a contract against the valid Visual Glossary of its Bounded Context and flag every term that drifts from the Ubiquitous Language: a field named receiver in one place and recipient in another, a status value the glossary never mentions, or a property that still reflects the superseded version 1 of an aggregate.

Following Böckeler, interface definitions belong to the specification rather than to the code (Böckeler, 2025). The specifications belong to the domain knowledge graph, next to the workshop artifacts that justify it. Only after such a check do the API definitions become real contracts between provider and consumers (Junker & Lazzaretti, 2025).

Try it yourself

Everything is public in the samples repository of DDD Meets AI:

• Model Atlas: download the HTML file and open it in a browser. It ships with the Larder graph and a Bike Rental example; you can also drop in your own .ttl file.
• Domain knowledge graph for Larder: the full graph, including its history.
• Source artifacts: the pictures of every ingested artifact, numbered in ingest order.

Start with the replay. Step through the Impact Maps and watch the goal metric change from version to version. Then jump to the Notification lane and compare the two aggregate models.

The whole blueprint is the specification

Spec-driven development often starts with a requirements document or an API contract. Along the Synergetic Blueprint, the specification starts much earlier: with the brainstorm, the canvases, the maps, the stories, and the glossaries that justify every later decision.

A domain knowledge graph keeps all of them in one place, with their sources, their uncertainty, and their history. The Model Atlas makes that history visible, so a team can see where a decision came from before changing it, and can check each new artifact against everything it has learned so far.

This post is based on Chapter 14, “AI-Enhanced REST API and Event Design,” of the upcoming book DDD Meets AI by Annegret Junker.

References

References

Beckett, D., Berners-Lee, T., Prud’hommeaux, E., & Carothers, G. (2014). RDF 1.1 turtle: Terse RDF triple language [W3C Recommendation]. World Wide Web Consortium. https://www.w3.org/TR/turtle/

Böckeler, B. (2025). Understanding spec-driven-development: Kiro, spec-kit, and Tessl. martinfowler.com, “Exploring Gen AI” series. https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html

Evans, E. (2003). Domain-driven design: Tackling complexity in the heart of software. Addison-Wesley.

Hogan, A., Blomqvist, E., Cochez, M., d’Amato, C., Melo, G. de, Gutierrez, C., Kirrane, S., Labra Gayo, J. E., Navigli, R., Neumaier, S., Ngonga Ngomo, A.-C., Polleres, A., Rashid, S. M., Rula, A., Schmelzeisen, L., Sequeda, J., Staab, S., & Zimmermann, A. (2021). Knowledge graphs. ACM Computing Surveys, 54(4), 71:1–71:37. https://doi.org/10.1145/3447772

Junker, A., & Lazzaretti, F. (2025). Crafting great APIs with Domain-Driven Design: Collaborative craftsmanship of asynchronous and synchronous APIs. Apress. https://doi.org/10.1007/979-8-8688-1457-0

Martraire, C. (2019). Living documentation: Continuous knowledge sharing by design. Addison-Wesley.

Miles, A., & Bechhofer, S. (Eds.). (2009). SKOS simple knowledge organization system reference. W3C Recommendation. https://www.w3.org/TR/skos-reference/