ADR 0005 — A Structurizr model is an authored architecture
- Status: accepted
- Settled: 2026-11-07, decisions D-061 and D-062 of the root
decisions/registry, approved by the owner with the plan of the Structurizr import - Amends: nothing.
architecture syncstill never writes an import, and ADR 0001 ofprotocols/architecturestill forbids turning an observation into a permission. - Scope:
@putnami/sdd(tooling/sdd-extension), theputnami architecture importcommand
Context
Some teams already describe their architecture in Structurizr, as a DSL file
or a JSON workspace. The model names software systems, containers and
components, and the relationships between them. A team like that should not
have to write putnami.architecture.json files from scratch.
The authoring commands have a firm rule: a generator writes only the
mechanical half of a manifest. architecture init writes no export, no import
and no binding. architecture sync writes bindings only for an import a human
already declared. The reason is
ADR 0001:
an observed dependency is evidence, never a permission.
A Structurizr relationship is not an observation. A person wrote it into a model and reviewed it there. Copying it into a manifest moves one declaration from one format to another. It does not turn code into a permission.
Decision
putnami architecture import --from structurizr <file>writes domains, exports and imports from the model. (D-061)- Each container is a domain whose ID is
<system>/<container>. A software system with no containers is a domain whose ID is<system>. Aputnami.domainproperty overrides the ID. On a software system, the property also applies to every container that does not set its own, so one property puts a whole system in one domain. - A container, a component or a software system with no containers whose
pathproperty names a project maps that project to its domain.--path-propertynames another property. The issue that asked for the command also offered a tag. A tag carries no value, so it cannot name a path, and the command reads only a property. - A relationship between two elements in different domains becomes one
import of the consumer domain per producer domain, in mode
reference. Of the five access modes,referenceis the only one that claims no data crosses the boundary. The import reads the producer's generated<domain>.interface.v1export, or the one active export of the producer that allows reference access, and takes that export's facts. A producer with no export gets the generated one. A producer with several such exports, or none, leaves the import to a person, and the relationship is listed. The relationship's description and technology become the justification. A person refines the mode and the facts by hand. - Bindings follow the
architecture syncrule. The command binds a project edge only when the graph observes it, and only to the one import that covers that domain pair. An edge between two domains that the model does not relate stays anarchitecture validateviolation, and the command lists it. - An element the command cannot map is listed with the reason: a person, a component with no path, a path that is no project, or a relationship that stays inside one domain.
- Each container is a domain whose ID is
- A rerun only adds. (D-062) Without
--apply, the command writes nothing and prints the diff. With--apply, it creates the missing manifests and adds the missing projects, exports, imports and bindings. It never changes or removes an entry that already exists, so a hand edit survives every rerun. A domain pair that already has an import gets no second one, even when a person renamed the generated import. A new import takes the version of the export it reads. A changed manifest keeps the order of its entries, and the additions are appended. It is written in the layout of the protocol's canonical writer, so a manifest any Putnami writer produced keeps every existing line, and a manifest in another layout is rewritten in that layout once. It reports an import the manifest holds and the model no longer has, and leaves the removal to a person. A new manifest goes toarchitecture/<domain>/below the workspace root, or below--at. A domain that is already declared keeps its own file. The command refuses, before it writes anything, a new manifest whose path is taken or lies in a directory architecture discovery skips. - The reader uses the standard library only. It reads a JSON workspace
and the DSL statements that describe a model: elements, groups,
relationships, properties and tags. It skips views, styles, deployment
environments, documentation and decision directives. Any other statement,
!includeamong them, stops the command at its line, with the advice to export the model as JSON with the Structurizr CLI.
Consequences
- A Structurizr team gets manifests that
putnami validateaccepts. A code dependency the model does not allow fails the gate. - A rerun after a model change is a reviewable diff, and the git diff of an
applied run is the authorization moment, as for
sync. - Generated exports and imports are deliberately thin: one
referenceexport and one fact per producer domain. A team that needs richer contracts edits the manifest, and later imports keep those edits. - Removal is manual. A relationship deleted from the model leaves its import in place until a person removes it. The command reports it so it does not go unnoticed.