Beyond code: where else does a stable, evidence-backed diagram earn its keep? #369

Implementation clarification — September 12

The original exploration below mixed capabilities on main with the prototype in draft PR #367. Locate and two-level drilldown bundles remain under review. Comparison currently supports architecture diagrams; draft bundles allow the other diagram types as children of an architecture map. The proposed BI and process-map uses are hypotheses, not a promise of native comparison or parent-node drilldown for every diagram type.

The portability statement applies specifically to successful Locate receipts, not every CLI receipt or failure diagnostic. Locate's architecture-only stale state checks authored source paths; bundle digest freshness is a separate check and applies to children of all supported diagram types. The comments about current usage and what people value are observations to validate, not measured findings. The request for concrete examples at the end still stands.

Original exploration — September 9

Read references to “today” and “free” below as the original proposal, subject to the implementation boundaries above.

Almost everything Archify is used for today is code understanding. I want to test whether the primitives are narrower than that, or wider. Before listing candidates, here is what a diagram gets for free right now: stable authored component ids; evidence pointers pinned to a repository revision; deterministic receipts with no timestamps and no absolute paths; compare, which reports what changed between two authored snapshots without inferring impact; two-level drilldown bundles bound by digest, with an explicit stale state instead of a silent render; and locate, which projects a Git range onto a map through path globs.

That list has one hard edge worth naming first, because it constrains every candidate below. All of the pinned-evidence machinery is git-path-shaped. sources verification, ownership globs, locate, and stale detection all assume the evidence is a file at a revision in one repository. Only architecture maps carry sources, so only they can go stale; the other four types get a receipt-only view from locate. Any domain whose evidence is a log line, a dataset version, a cloud resource, or a signed document gets the ids, the digests, the delta, and the drilldown for free — and gets none of the evidence checking, which is the part people actually value.

BI dataflow and metric lineage. Grounded: discussion #270 describes SQL sources, in-memory aggregation, remote calls, sensitivity boundaries, and persistence, from someone who already has a local implementation. Free today: dataflow diagrams, classifications, drilldown into a stage, delta between two snapshots. Genuinely new: a companion file for executable SQL, and evidence that points at a query rather than a path. Reason not to: this may be authoring guidance rather than product surface, and once evidence stops being a file path, none of the verification applies.

Endpoint inventory beside topology. Grounded: #227 asks for the HTTP endpoints a service exposes, next to the diagram, so a reader does not leave the artifact to grep. Free today: drilldown from a component into a child diagram, ownership globs scoped to that component. Genuinely new: an authored inventory that can be checked against the repository at a revision. Reason not to: for most frameworks the inventory is only extractable by inference, which is declined.

Repository-checked process maps. Grounded: #251 and #248 ask for coverage of gates and recovery paths — a workflow that renders cleanly but omits a real failure branch. Free today: workflow and lifecycle types, stable ids, delta, ownership at the node level. Genuinely new: a coverage statement the author writes and the tool checks. Reason not to: what "complete" means is domain-specific, and a coverage check that cannot be decided becomes advisory noise.

Infrastructure topology pinned to IaC. Partly grounded: the deployment-ownership profile already fails closed on owners, regions, private databases, and crossing mechanisms, and #196 asks for evidence across multiple repositories. Nobody has explicitly asked for IaC-revision pinning. Free today: the whole evidence path, if the IaC lives in the same repository. Genuinely new: multi-repository evidence, which #196 shows is a real gap. Reason not to: the diagram would describe declared infrastructure, never running infrastructure, and that distinction is easy for a reader to lose.

Three more I have heard nothing about in this repository, and I would rather say so than pretend: incident timelines pinned to log evidence, ML pipeline and experiment provenance, and regulated-domain process maps where a box is backed by a document at a revision. Structurally they fit — every one of them is a diagram whose value depends on "this box is backed by that thing, at that version". But there is no demand signal here for any of them, and each one needs an evidence kind that is not a file path, which is the expensive part.

What I am asking for is not votes. If one of these is real for you, describe the specific artifact you maintain today, what goes stale in it, how you currently notice, and what evidence you would be willing to pin by hand. A single concrete example with those four parts is worth more than agreement from ten people. If your case is one of the three I said has no signal, that is exactly the reply I want.