Skip to content

§2.2 Structural Models: What Is Connected to What?

Structural models hold a system still. They suppress most behavior and keep the entities, boundaries, containment, dependency, and flow — what parts exist and which rest on which. This is the most familiar reduction in engineering, and the natural place to begin.

2.2.1 The Canonical Move: Structure and Dependency

A component diagram names which services exist; a dependency graph names which modules rest on which; a call graph names which procedures may invoke which; a data-flow diagram names how information moves through transformations; a deployment topology names what is connected across execution locations. The graphical forms differ, but the reduction is the same: keep the entities and the declared relations, discard the behavior (Figure 2.2-1).

Canonical structural model: a read-through cache architecture A linear dependency example: WEB depends on API; API reads through CACHE; CACHE loads from DATABASE. These arrows declare structural relations, not a timeline of requests. A crossed dashed route from WEB directly to DATABASE is a forbidden bypass. Question: what exists, and what is connected to what? Semantics: entities and declared structural relations. Analysis: reachability, paths/cuts and cycles. Structural model Read-through cache example WEB API CACHE DATABASE depends on reads through loads from forbidden bypass Question: What exists, and what is connected to what? Semantics: Entities and declared structural relations Analysis: Reachability, paths/cuts and cycles.
Figure 2.2-1. The structural move: entities and defined relations. This model states an intended architecture, rather than recording an execution. Every solid arrow denotes a direct dependency; the crossed arrow marks a forbidden bypass. Checking paths makes the obligation precise: every path from Web to Database must pass through API.

The model selects both the entities and the relations. A graph of service boundaries should not carry every helper function; if the question is about architecture, that detail only makes the model worse. The edge label specifies the relationship being modeled. "A depends on B," "A calls B," and "a record is stored in a database" are different relations; collapsing them into a generic "related-to" edge throws away exactly the distinction the model was built to preserve.

Once structure is explicit, the claims an engineer wants become graph properties. Some are local: component A may not depend directly on component C. Some concern paths: every route from ordinary logic to a format-specific library must cross a sanctioned seam. Some concern the whole graph: the dependency relation must be acyclic. The analyses follow — reachability, reverse traversal to find what depends on a node, cycle detection, impact analysis over a proposed change, and conformance of an observed graph against a declared one. A question that would otherwise mean reading imports, configuration, and deployment manifests becomes an operation over a declared graph.

Static analysis can sometimes derive the graph from the implementation; in other cases engineers declare the architecture as intent. Those are different claims: one describes what the system appears to do, the other what it is supposed to do. Chapter 3 treats the distinction carefully.

2.2.2 Choose the Relation for the Question

Suppose a web application's user interface should reach its database only through an application service. A three-layer model can represent that boundary: user interface, application service, database. The property concerns paths. Every route from the interface to the database must cross the service; a direct interface-to-database edge would violate the intended architecture. The model can omit the service's internal algorithms because those details do not decide whether the boundary is crossed.

A build dependency graph answers a different question. Suppose two independent source files are compiled and their object files are then linked into one executable. Model the compilation tasks and the link task as nodes, with an edge from each compilation to linking. The two edges express what linking needs. A change to one compilation result affects the link task, but the graph gives no reason to rerun the other compilation. This is a dependency question, so the useful entities are tasks and their products rather than architectural layers.

The relation's meaning also matters within one workflow. A task may consume an earlier result as data, or inspect a condition solely to decide whether it should run. Both create dependencies, but they support different questions about how information contributes to the output. A model that records only an undifferentiated arrow cannot answer those questions. DocAble's document-processing pipeline provides a worked example of both architectural boundaries and typed computation dependencies.

WORKED EXAMPLEDEEP DIVE

Worked example — Two structural views of document repair

DocAble is a service that repairs accessibility problems in documents, such as missing alternative text, unmarked table headers, or incorrect reading order. The same operation may need a different implementation for a Word document and a PDF. Its structural models let engineers separate two questions: where format-specific changes belong, and how the repair computations depend on one another.

Where may a document change?

DocAble supports several structured document formats through libraries powerful enough to alter their underlying object structures. Those libraries are necessary, but they sit behind a deliberate architectural boundary: most remediation logic works through DocAble's structured-document abstractions rather than reaching into a format-specific implementation directly.

Document-mutation model · Structural

  • Engineering question — Where is document mutation supposed to occur?
  • Model — a layered structural relation: remediation logic operates through a structured-document model, with a separate implementation for each format: DOCX, PPTX, XLSX, and PDF.
  • Property — the intended architecture places format-specific mutation behind one sanctioned seam; ordinary remediation logic is not intended to bypass it.
  • Quality attribute — architectural integrity and modifiability.

The necessary model is small. Figure 2.2-2 draws it: remediation logic operates through a structured-document model, which has a separate implementation for each format—DOCX, PPTX, PDF, LaTeX, etc. It says nothing about queues, retries, deployment, user sessions, or the mechanics of individual repairs. Those facts are real but irrelevant to the question; the reduction preserves only the architectural boundary that matters.

DocAble's document-mutation model: mutation reaches formats through a sanctioned seam Remediation logic operates through a structured document model, the sanctioned seam. That model is implemented by a format-specific implementation, which reaches the concrete formats DOCX, PPTX, XLSX, and PDF. The structured document model marks where mutation is supposed to occur; it does not by itself prevent code from bypassing the seam. DOCUMENT-MUTATION MODEL remediation logic operates through structured document model the sanctioned seam implemented by format-specific implementation DOCX PPTX XLSX PDF The model marks where mutation is supposed to occur.
Figure 2.2-2. Document-mutation structural model. The reduction preserves one architectural relation: ordinary remediation reaches format-specific mutation through a structured-document seam. Enforcement of that relation is a separate Alignment decision.

The principal property is a path constraint: every ordinary route to format-specific mutation must cross the structured-document seam. The model makes that requirement explicit so that a checker can look for bypasses. Enforcement requires a further step: DocAble's static analyses reject code that reaches a raw format library directly. In Chapter 3, we discuss mechanisms for enforcing this architectural relation.

A structural model carries the opposite risk too. The code moves and the drawing does not, so the boundary it shows quietly stops matching the system. That gap between a model and the system it describes is model drift. Later sections make the correspondence explicit by deriving, generating, or tracing between model and implementation.

What computations depend on one another?

The document-mutation model asked where one kind of change belongs. A second structural question reaches further inside the system: what computations make up remediation, and how do they depend on one another? DocAble runs a document through a collection of registered remediation passes. A pass may detect a condition, produce information a later pass uses, decide whether remediation should proceed, apply a bounded change to the intermediate representation, or edit a larger region directly. That structure exists in the implementation whether or not a model names it. The first reduction is the obvious one: treat each registered pass as a node, and suppress the statements, library calls, and loops inside it.

Remediation-computation model · Structural

  • Engineering question — What computations make up remediation, and how does information move among them?
  • Model — a static directed graph whose nodes are registered computations and whose typed edges represent declared composition among them.
  • Property — declared data dependencies and control dependencies are distinguishable and consistent with pipeline ordering; each modeled computation also states its mutation behavior — read-only, a typed, comparable patch for all or a declared subset of its edits, or a direct in-place edit — and, on a separate axis, which apply seam a patch producer uses.
  • Quality attribute — analyzability, modifiability, and architectural integrity.

DocAble's remediation-computation model represents registered computations as nodes and distinguishes two kinds of composition. A data-flow edge means one computation produces information another consumes in producing its result. A control edge means one computation produces information another consults only to decide whether it should run. Treating both as a generic dependency would obscure a consequential distinction: information that contributes to a result is different from information that controls whether the computation occurs. Figure 2.2-3 draws an illustrative fragment of the graph. These relationships are visible without reconstructing them from type declarations and function bodies.

Figure 2.9: Remediation Graph (Typed) Illustrative remediation computations with read-only, typed-patch and direct-edit behaviors; solid data flow and dashed control dependencies. The apply seam is shown separately. A typed structural model of DocAble’s remediation computations.Classify(format, needs)Repairstructure(typed patch)Repairmetadata(typed patch)Apply patches(direct edit)Check alt-text(read-only)Computation:a registeredremediation step(e.g., classify, repair,check).Control gate:classificationData flow:producesinformationused by anothercomputation.Apply seam:where patches areapplied to theNode (computation) typeDependency (edge) type= Direct edit (mutates document)= Typed patch (produces a patch)= Data flow (payload)= Control gate125 registered computations; 57 typed composition relations.The model preserves computation identity, mutation behavior, apply seams, anddeclared dependencies—not the code implementing each computation.determines whichrepairs run.document.(executes if condition holds)Mutation behavior:•typed patch —produces a patch•direct edit —edits document•read-only —no document edits= Read-only (no document edits)
Figure 2.2-3. From computations to composition. This illustrative fragment distinguishes data flow (solid arrows) from control dependencies (dashed arrows). Ellipses identify read-only computations, diamonds typed patch producers, and rounded boxes direct document edits. The apply seam is the boundary where patches are applied; the final alt-text check reports findings without changing the document.

The first model preserves one architectural relation. The second preserves a family of typed compositional relations over the same system.

The same model also records each computation's mutation behavior: some only inspect the document and report information, some produce typed patches, some produce them for part of their work and edit directly for the rest, and most edit document state directly. These distinctions do not declare one form universally better. They make previously implicit differences available for engineering questions about composition and mutation.

The computation model remains static with respect to any one run: it records no per-job invocation history, retries, or model fingerprint. Other views can nevertheless attach observations to its stable computation identities. DocAble joins staged-run telemetry to those identities, so measured latency and cost can be queried alongside the structural model without turning the structural graph into an execution log. The per-session mutation record remains separate: it records what happened to one artifact, not the execution history of the computation graph.

The same identities can support additional engineering views without enlarging the structural schema each time. Separate providers can record complexity, bounded execution, latency, test coverage, or checker trust against the same computation identity. Declared properties state engineering intent. Measured properties report observations and may have incomplete coverage. An unmeasured latency is therefore unknown, not zero. Joining these views lets engineers ask questions about combinations of properties while keeping each representation focused on its own question.

The two reductions keep different relations because they support different changes. To investigate a bypass of the document abstraction, inspect the architectural paths. To investigate the effect of changing a repair pass, inspect its declared inputs, outputs, and dependents. Neither question requires a complete model of the product.

A structural model earns its detail by the question it helps answer. Architectural paths, data dependencies, and control dependencies preserve different facts even when each is drawn with boxes and arrows. The next section adds time: what states a thing occupies, and what sequences of changes the model admits.

© James C. Davis, 2026–present