NexCanvas Draw.io

Most diagram automation stops when XML is valid. NexCanvas treats that as the beginning, not the finish line. It addresses four recurring failures in agent-generated architecture diagrams:

• unsupported architecture invented from an incomplete prompt;
• every problem forced into the same columns or generic card grid;
• logos that disappear after cloning or silently represent the wrong product;
• connectors, labels, badges, icons, and boundaries that collide in the final render.

The result is an editable .drawio artifact backed by evidence, semantic models, local assets, machine-readable QA reports, and an inspected preview.

Compact phase architecture	Hub-and-spoke analytical architecture
Sparse five-phase RAG flow with platform foundation	Central analytical hub, source and consumer towers, and a lower AI enrichment zone

The dense 27-node reference, compact RAG reference, and hub-and-spoke reference are complete projects, not flattened screenshots. Each includes source/model/lock contracts, local SVG assets, editable Draw.io XML, a PNG with embedded diagram data, and QA reports.

The multi-agent workflow reference demonstrates the same Microsoft-inspired phase grammar for an executable process: coordinator delegation, parallel specialist groups, bounded retry, human escalation, terminal outcomes, and separate connector lanes. It is explicitly modeled as workflow, not as a generic component inventory.

Describe the system or process and specify the diagram language. That is enough to start; you do not need to choose a diagram category, style, or canvas.

For example: "Draw a multi-agent system with one coordinator and specialist agents. Use English." The agent derives the structure, compares layouts, builds an editable diagram, and inspects the rendered result. Unspecified conceptual roles are recorded as assumptions. When documenting an existing system, the agent inspects its sources.

The agent asks only for missing language or a content ambiguity that would change the meaning of the diagram. Explicit visual references and output preferences remain active for later examples and revisions until changed. See the intake contract.

The five intents describe the question being answered, not the appearance of the diagram:

The agent derives this intent from the brief, then selects a specialized route such as C4, deployment, RAG, agent orchestration, CI/CD, ETL, or state machine. The selected visual grammar remains independent, so any compatible view can still use the Microsoft/reference treatment and remains editable in Draw.io. See semantic intents and repository evidence.

The default project location is deliberately outside the installed skill:

<your-current-repository>/
└── nexcanvas-output/
    └── <project-slug>/
        ├── source_model.json
        ├── diagram_lock.json
        ├── diagram_model.json
        ├── project_state.json
        ├── repository_snapshot.json      # after a completed repository sync
        ├── assets/
        │   ├── asset_manifest.json
        │   └── icons/
        ├── artifacts/
        │   ├── diagram.drawio
        │   └── diagram.drawio.png
        └── reports/
            ├── runtime.json
            ├── repository_evidence.json
            ├── layout_brainstorm.json
            ├── build.json
            ├── diagram_qa.json
            ├── render.json
            ├── visual_qa.json
            ├── semantic_sync.json
            └── postflight.json

repository_evidence.json is emitted only for repository-backed diagrams. Other reports are produced as their corresponding build, render, and review stages run.

New projects use diagram_model.json schema 3.0. Its three layers prevent a layout adjustment from masquerading as an architecture change:

Generated Draw.io, previews, and QA reports stay outside the canonical model. V3 output carries both a full model hash and a semantics-only fingerprint, so repository sync can distinguish meaning from presentation edits. See the Semantic Model V3 contract.

The tracked nexcanvas-output/README.md makes this location visible in a fresh clone, while generated contents stay ignored. An explicit project path can still be supplied.

NexCanvas follows the open Agent Skills directory convention: keep this entire repository together so SKILL.md can reach its scripts, references, schemas, configuration, and assets.

mkdir -p .agents/skills
git clone https://github.com/sunniie/nexcanvas-drawio.git .agents/skills/nexcanvas-drawio

Codex discovers repository skills from .agents/skills; user-scoped skills can live under $HOME/.agents/skills. See the official Codex skills documentation.

mkdir -p .github/skills
git clone https://github.com/sunniie/nexcanvas-drawio.git .github/skills/nexcanvas-drawio

GitHub documents project skill locations including .github/skills, .claude/skills, and .agents/skills, plus personal Copilot skill folders. See Adding agent skills to GitHub Copilot.

mkdir -p .claude/skills
git clone https://github.com/sunniie/nexcanvas-drawio.git .claude/skills/nexcanvas-drawio

Claude Code discovers project skills under .claude/skills and personal skills under ~/.claude/skills. See Extend Claude with skills.

Use NexCanvas Draw.io to investigate this repository and create a deployment
architecture for engineering onboarding. Ask only for unresolved decisions.

Recreate this Microsoft architecture reference as editable Draw.io. Preserve its
visual grammar, but derive the topology from my system description.

Repair this .drawio: eliminate overlapping connector lanes and keep all labels
clear of icons, step badges, and container outlines. Render and verify it.

Requirements:

• Python 3.10 or newer for authoring and structural QA;
• Draw.io Desktop for deterministic PNG/SVG/PDF export and complete visual QA;
• network access only when an icon must be synced and is not already local.

Install an editable checkout for development:

git clone https://github.com/sunniie/nexcanvas-drawio.git
cd nexcanvas-drawio
python -m pip install -e .
nexcanvas --version

For a downloaded release bundle, run python -m pip install . instead. The package includes the pinned route, theme, schema, and icon-catalog data needed to run from any working directory. A clone-only host may use python <skill-root>/scripts/nexcanvas_cli.py as an installation-free launcher.

Inspect runtime capabilities:

nexcanvas doctor

Initialize from only a title, brief, and output language. The skill infers the semantic intent and a compatible default route:

nexcanvas init --name "Checkout request" --brief "Trace one checkout API request through payment and inventory" --language en

Or choose an explicit directory:

nexcanvas init docs/architecture --name "My architecture" --family software --profile c4-container

init creates a canonical V3 diagram model. Existing V2 projects remain readable in v0.6.x, but incremental repository sync requires V3. To migrate without overwriting the original:

nexcanvas migrate v2-to-v3 docs/architecture/diagram_model.json \
  --source-model docs/architecture/source_model.json \
  --output docs/architecture/diagram_model.v3.json
nexcanvas contract diagram-model docs/architecture/diagram_model.v3.json

Inspect and test the new file before adopting it as the active diagram_model.json.

After completing the generated contracts and resolving assets, run the hash-bound pipeline. It plans, builds, runs diagram QA, renders, and then stops at the explicit visual-review boundary:

PROJECT=nexcanvas-output/checkout-request
nexcanvas generate "$PROJECT"

Exit code 3 means the current preview is ready for external review—not that generation failed. Inspect the PNG at target size and connector terminals at enlarged scale, fix the model if needed, and only then approve that exact render:

nexcanvas generate "$PROJECT" --approve-visual --reviewer "Your name" --notes "Inspected at target size and traced connector terminals at 200%"

The second run reuses every unchanged passing stage, records the approval, and runs postflight. Later runs do the same: changed inputs or outputs invalidate the affected stage and everything downstream; unchanged stages are reused. See deterministic pipeline state.

When the diagram must reflect a real codebase, capture the current Git identity before authoring facts:

nexcanvas analyze capture . --source-model "$PROJECT/source_model.json" --source-id repo-1

Add repo-relative file and line ranges to fact evidence, then verify the exact origin, full commit, optional blob hash, and range. Pass the repository root again to release QA and postflight so provenance is rechecked rather than trusted from an old report:

nexcanvas analyze verify "$PROJECT/source_model.json" --repo-root . --output "$PROJECT/reports/repository_evidence.json"
nexcanvas generate "$PROJECT" --repo-root .
nexcanvas generate "$PROJECT" --repo-root . --approve-visual --reviewer "Your name" --notes "Inspected at target size and traced connector terminals at 200%"

This verifies the authored evidence. It does not claim to discover live infrastructure, infer unknown ownership, or prove runtime behavior.

When a repository-backed V3 diagram already exists, preview the semantic update before changing project files:

nexcanvas sync "$PROJECT" --repo-root . --dry-run

The analyzer reads Git-tracked Python, TypeScript, JavaScript, TSX, JSX, MTS, CTS, MJS, and CJS modules at the pinned HEAD. It extracts public top-level symbols and statically resolvable internal imports. Use repeated --include and --exclude options to keep the analysis aligned with the diagram's scope.

After reviewing operations, conflicts, pendingRemovals, and diagnostics, apply safe changes:

nexcanvas sync "$PROJECT" --repo-root . --apply

Removals are retained until each stable semantic ID is explicitly approved:

nexcanvas sync "$PROJECT" --repo-root . --apply \
  --confirm-removal repo-module-example \
  --confirm-removal repo-import-example

Three-way reconciliation compares the last applied repository snapshot, the new source revision, and the current user-edited model. Source-only fields update; user-only fields remain; same-field conflicts preserve the current value and are reported. Existing annotations, positions, assets, boundaries, labels, ports, and unaffected connector lanes are not regenerated. Complete the update by running generate --repo-root ., inspecting the new render, and approving that exact artifact. See the repository-sync workflow.

PowerShell users can replace the first line with $Project = "nexcanvas-output/my-architecture" and $PROJECT with $Project.

Catalog assets are resolved before drawing:

nexcanvas asset search postgresql
nexcanvas asset sync nexcanvas-output/my-architecture postgresql

Azure reference projects can sync exact assets from Microsoft's official Architecture Icons package:

nexcanvas asset sync nexcanvas-output/my-architecture azure-functions --provider microsoft-azure-official --accept-terms
nexcanvas asset sync nexcanvas-output/my-architecture azure-ai-search --provider microsoft-azure-official --accept-terms

AWS and Google Cloud projects accept an official provider ZIP through --source-archive. The resolver checks SVG safety, records source/version/hash and license metadata, copies the asset into the project, and embeds it in the editable Draw.io XML. If no exact verified logo exists, the skill uses a neutral semantic glyph or reports NeedsManual; it does not improvise a brand mark.

NexCanvas does not equate “architecture diagram” with one template. It chooses composition after the semantic model is stable:

• phase columns for short left-to-right pipelines;
• dense phase columns for parallel hot/cold paths and substantial lifecycle views;
• phase rows when vertical progression shortens routes;
• compact pipeline for a small number of strong stages;
• hub-and-spoke for a real analytical, integration, or control center;
• hybrid grid when a main flow needs subordinate feedback, governance, or topology.

Provider-reference mode uses restrained neutral zones, official icon-led services, numbered handoffs, orthogonal routing, and a foundation band. See reference image patterns, layout brainstorming, and the enterprise reference style.

A project is complete only when:

1. one dominant semantic intent is resolved and compatible with the specialized route;
2. source facts are confirmed or explicitly marked as assumptions, and repository ranges are revision-verified when present;
3. route/profile requirements and model references are valid;
4. requested assets are exact, local, embedded, and renderable;
5. connectors have explicit semantics, independent lanes, correct direction, and distinct service ports for independent fan-in/fan-out relationships;
6. labels do not overlap nodes, icons, badges, connector strokes, or visible boundary outlines;
7. incoming and outgoing edges cannot form an accidental visual relay through a service, and title/legend chrome matches the model;
8. automated QA has zero errors and zero actionable warnings;
9. the rendered image was traced end to end at delivery size and connector terminals were inspected enlarged;
10. postflight confirms that source, model, lock, render, and approval hashes still match.

When Draw.io Desktop is unavailable, the portable tier can still generate and structurally validate editable .drawio, but visual approval remains pending.

SKILL.md                          portable agent instructions
agents/openai.yaml               optional Codex interface metadata
workflows/                       generate, repository-sync, repair, and reference-conversion flows
references/                      notation, intake, layout, asset, and QA contracts
config/                          route, theme, archetype, and provider registries
schemas/                         JSON contracts
src/nexcanvas/                   installable compiler and unified CLI package
scripts/nexcanvas_cli.py         installation-free source-checkout launcher
scripts/*.py                     deprecated v0.1 compatibility entry points
tests/                           unit and reference-project tests
examples/v2-rag-reference/       compact phase reference
examples/v3-dense-industrial-ai/ dense industrial AI reference
examples/v4-hub-spoke-industrial/ hub-and-spoke reference
examples/v5-multi-agent-workflow/ multi-agent orchestration workflow
nexcanvas-output/                documented default generated-output root

python -m pip install -e .
python -m unittest discover -s tests -v
python scripts/test_drawio_qa.py -v
python scripts/validate_conformance.py
nexcanvas doctor
python scripts/package_smoke.py

The implementation uses the Python standard library for its core contract, layout, build, and QA pipeline. This keeps the same skill usable by Codex, GitHub Copilot, Claude Code, and other hosts that implement Agent Skills.

The complete command surface, exit-code contract, installation behavior, and compatibility window are documented in the CLI reference.

NexCanvas does not call two prompts equivalent merely because their screenshots look similar. The Phase 6 harness evaluates semantic coverage, source evidence, assets, routing/layout decisions, and completed delivery gates against a versioned five-intent corpus. Fixture baselines test the evaluator and never verify a host.

nexcanvas conformance doctor
nexcanvas conformance prepare multi-agent-workflow --host codex --output conformance-run
nexcanvas conformance evaluate conformance-run/request.json --project conformance-run/project --mode observed --execution conformance-run/execution.json

Read the method and trust model, the run workflow, and the current host capability matrix.

NexCanvas is developed on a protected, always-releasable main branch. Changes are proposed through short-lived branches and pull requests, and releases follow Semantic Versioning with separate versioning for persisted JSON schemas.

• Roadmap and phase gates
• Project scope
• Public contracts
• Versioning and releases
• Contributing
• Support
• Security policy

Code and documentation are licensed under MIT. Technology marks and provider icon packs remain subject to their owners' licenses and trademark policies; asset provenance is recorded in each project manifest.