Problem
When an architecture diagram is authored from repository evidence, rendering and showcase validation can succeed even when the diagram omits material runtime relationships.
Examples include:
- an API-exposed workflow has no API-to-workflow edge;
- an application-lifecycle scheduler or background worker is not represented;
- a direct management path to an external dependency is omitted;
- an external-system edge has no operation label, making read/write/sync semantics unclear.
These are not layout failures. The JSON is valid and the artifact renders correctly, but the resulting diagram can be misleading in design review or operational handoff.
This proposal is different from API inventory: the goal is not to display every endpoint, but to detect whether important repository-backed architectural relationships are represented or explicitly declared out of scope.
Proposal
Add an optional semantic coverage phase for repository-backed architecture diagrams.
The phase should emit warnings, without blocking rendering, when:
- a discovered lifecycle scheduler or background worker has no corresponding component or declared omission;
- a material API/controller family has no represented downstream workflow or component;
- a direct external-dependency management path is absent from the authored topology;
- a relationship to an external system has no semantic operation label.
Authors should be able to suppress a warning with an explicit, machine-readable omission reason when a relationship is intentionally excluded from a high-level diagram.
Expected result
Validation output should distinguish:
layout: geometry, overlap, containment;semanticCoverage: inferred relationships that are represented, missing, or explicitly omitted.
This would keep the renderer lightweight while making repository-derived diagrams safer to use as architecture documentation.
Problem
When an architecture diagram is authored from repository evidence, rendering and showcase validation can succeed even when the diagram omits material runtime relationships.
Examples include:
These are not layout failures. The JSON is valid and the artifact renders correctly, but the resulting diagram can be misleading in design review or operational handoff.
This proposal is different from API inventory: the goal is not to display every endpoint, but to detect whether important repository-backed architectural relationships are represented or explicitly declared out of scope.
Proposal
Add an optional semantic coverage phase for repository-backed architecture diagrams.
The phase should emit warnings, without blocking rendering, when:
Authors should be able to suppress a warning with an explicit, machine-readable omission reason when a relationship is intentionally excluded from a high-level diagram.
Expected result
Validation output should distinguish:
layout: geometry, overlap, containment;semanticCoverage: inferred relationships that are represented, missing, or explicitly omitted.This would keep the renderer lightweight while making repository-derived diagrams safer to use as architecture documentation.