92 lines
5.2 KiB
Markdown
92 lines
5.2 KiB
Markdown
# 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.
|