Code-generated diagrams and decision-captured diagrams solve different problems

Generating diagrams from code, infrastructure, or runtime telemetry is attractive because it reduces manual maintenance. It does not eliminate the need for human-authored architecture views.

Direct answer: Use generated diagrams for observable structure: services, dependencies, resources, schemas, and runtime calls. Use decision-captured diagrams for intended boundaries, ownership, tradeoffs, and future state. Compare the two to detect drift, but do not expect either view to answer every architecture question.

What code can reveal

Static analysis, manifests, infrastructure definitions, and telemetry can reveal components and relationships with high precision. Generated views are valuable for inventory, dependency analysis, deployment topology, and unexpected runtime calls.

They are especially useful when a large system changes too quickly for manual low-level diagrams.

What code cannot explain by itself

Code rarely states why a queue exists, why one team owns a boundary, which alternative was rejected, or which dependency is temporary. It may also omit external manual processes, planned migration state, and organizational constraints.

A generated graph can be accurate and still be architecturally unhelpful.

What conversation captures

Design discussions contain intent: reliability goals, security concerns, cost tradeoffs, migration sequencing, and stakeholder requirements. A decision-captured diagram selects the relationships relevant to that question.

Its weakness is potential drift from implementation.

Compare intended and observed state

The most useful workflow overlays or compares the two:

• intended dependency absent in code;
• observed dependency absent in the design;

• deprecated component still receiving traffic;
• ownership or boundary mismatch;
• implementation compromise not recorded as a decision.

Differences become review tasks rather than silent confusion.

Avoid the "complete graph" trap

Generated systems often create unreadable hairballs. Filter by domain, request path, deployment environment, or risk question. Architecture is an act of selecting relevant information, not displaying every edge.

Define authority per question

For "what calls this service in production?" telemetry may be authoritative. For "why is the service isolated?" the decision record is authoritative. For "what should the target state be?" an approved design is authoritative.

One universal source of truth is unrealistic; clear source-of-truth boundaries are practical.

Where Arialine fits

Arialine preserves the conversation-derived diagram and reasoning in Slack. Generated views can be imported, linked, or used to propose corrections. The combination gives teams both intent and evidence.

FAQ

Should generated diagrams replace manual diagrams?

Replace manually maintained low-level inventories when generation is reliable. Keep curated views for intent, communication, and decisions.

Can runtime data be the source of truth?

For observed behavior, yes, within its sampling and environment limits. It does not define desired behavior.

How often should the views be compared?

After major changes, during architecture reviews, and when incidents reveal unexpected dependencies.