corp-v1-channel-architecture/references/diagrams-drawio-canonical-compliance.md

Canonical Draw.io Compliance for C4 Architecture

Use this reference whenever an Architecture change creates, rewrites, or reroutes editable .drawio sources.

Authority and provenance

1. Resolve the canonical global skill from https://gitea.lego-cloud.eu/home-v1-skills-code-agent/diagrams-drawio.
2. Fetch its remote default/test ref and record the exact full commit. Do not treat an unversioned work copy or an old reference directory as authoritative.
3. Read SKILL.md plus references/capabilities.md, rules-layout.md, rules-style.md, and routing-best-practices.md before editing.
4. Ask the installed CLI for its actual supported actions with node scripts/dist/cli/commands.js --help. If prose and CLI action names differ, use the current CLI names and disclose the documentation drift; never silently skip a requested gate.

C4 wording contract

• C1 is the System Context view.
• C2 identifies containers.
• C3 opens one selected C2 container and shows components inside it.
• A C3 page does not turn its subject container into a component.
• Prefer explicit titles such as Web Application — Container and Web Application Container — C3 Component View.
• The container registry is navigation over C2 containers and their C3 views; it is not itself a C4 level and must not be called Containers (C3).

Source invariants

For every governed diagram:

• preserve editable native mxGraph XML;
• use rounded=0;
• keep all relationship edges on root layer parent="1";
• forbid exitX, exitY, entryX, entryY, exitDx, exitDy, entryDx, and entryDy style pins;
• use orthogonal routes and explicit waypoints only where needed;
• place vertex x, y, width, and height on the canonical 40pt grid;
• use a 40pt minimum gap and uniform sibling-row/column spacing;
• keep labels concise (normally at most 80 characters) and move detailed behavior to surrounding prose/tables;
• retain square C4 boundaries and visibly separate source-observed elements from target/unimplemented elements;
• do not add relationships merely to eliminate an intentional orphan.

Add repository-level fail-closed checks for invariants the global CLI does not enforce. Mutation-test these checks—for example, change one vertex from x=40 to x=20 and require validation to fail.

Canonical CLI gate

Run the current CLI against every changed diagram. At the time this workflow was learned, the supported quality actions were:

validate
page-connectors-summary
page-connectors-validation
page-labels-validation
page-shape-bbox-validation
page-orphans
page-recommendations
page-hierarchy-full
page-negative-space-summary

Use task validate -- --file=<path> when the canonical Task wrapper is available. If the wrapper executable is unavailable but the skill explicitly documents the built Node entry point, invoke node scripts/dist/cli/commands.js --file <path> --action validate and the supported quality actions directly. This is an entry-point substitution, not permission to invent replacement checks.

Required acceptance targets:

• valid XML/mxGraph compilation;
• zero connector crossings;
• zero single-port violations;
• zero corner-port violations;
• zero header-edge violations;
• zero leaf-shape connector overlaps;
• zero shape bounding-box overlaps;
• zero empty, duplicate, or overlong labels;
• no forbidden port pins or nested edges.

Connector/shape diagnostics involving only the containing system or swimlane boundary are structural boundary crossings. Report them separately from leaf-shape overlaps; do not call every raw overlap total a blocker.

Visual QA after machine gates

Render every affected route through the real Docusaurus production build and inspect it in the browser. Machine-clean geometry can still look poor. Check specifically for:

• long edge prose rendered too small;
• large perimeter detours introduced only to satisfy fan-in/fan-out rules;
• multiple labels crowding a shared corridor;
• overlapping final connector segments that make source attribution ambiguous;
• labels crossing boxes or headers;
• C2 container versus C3 component wording ambiguity;
• source-observed and target/unimplemented regions blending together.

Prefer moving external actors into aligned lanes, using a shared same-side fan-in/fan-out point, shortening edge labels, and positioning edge labels on distinct route legs. Rerun all machine gates after each visual correction.

Review and publication

1. Run repository validators, tests, TypeScript, strict production build, production audit policy, and git diff --check on the exact final diff.
2. Obtain independent fail-closed review that reads the canonical skill and distinguishes parent-boundary diagnostics from real leaf defects.
3. Fix every blocker and request a fresh review; a pre-fix pass is stale.
4. Refresh the default branch after review. Rebase safely and rerun exact-head validation if it moved.
5. When delivery requires a PR, do not stop at a local commit or rebase. Push, open the PR, return the real URL/head, verify exact-head CI, merge when authorized, and verify integrated-head CI.
6. State publication layers precisely: local, pushed branch, open PR, exact-head CI, merged, integrated-head CI, and deployed page-body verification.