Architecture Constraints

Technical Constraints

Constraint Description

Go as implementation language

The tool is implemented in Go to enable single-binary distribution without runtime dependencies. See ADR-002.

JSON as model format

The architecture model uses JSON (JSONC) with JSON Schema for validation. See ADR-001.

draw.io XML as output format

The visual representation uses draw.io’s mxGraph XML format. This constrains layout capabilities to what draw.io supports.

No JavaScript/Node.js in the product

The CLI and its libraries use no JavaScript/Node.js, avoiding npm supply-chain risk. Exception: the optional VS Code extension (vscode-extension/) is a separate TypeScript/npm artifact, not part of the released binary.

Cross-platform

The tool must run on Linux, macOS, and Windows.

Headless draw.io for image export

export (PNG/SVG) shells out to the draw.io desktop CLI; it must be installed (in containers: via xvfb + dbus). The text exports need no draw.io.

Git for history-based commands

stale and changelog invoke the git binary to derive element history; outside a git repository they degrade gracefully.

Organizational Constraints

Constraint Description

Open Source

The project is developed as open source software.

Documentation in English

All documentation is written in English.

Documentation in AsciiDoc

Architecture documentation uses arc42 template in AsciiDoc format.

ADR format

Architecture decisions follow the Nygard ADR format with a weighted Pugh matrix for option evaluation.

Conventions

Convention Description

Version control

All files (model JSON, draw.io XML, templates) are text-based and Git-friendly.

Version numbering

The tool displays a version number. Semantic versioning is used.

ADR naming

ADRs follow the pattern ADR-NNN-Name.adoc in src/docs/arc42/ADRs/.