# 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:

```text
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.