Risks and Technical Debts

This is the project’s living risk register. Its risk IDs (R-n) and debt IDs (D-n) are local to this chapter. The ATAM Architecture Review (2026-03-06) was the original input and remains the point-in-time analysis with its own separate numbering (sensitivity/tradeoff points); do not assume R-5 here equals R-5 there.

Risks

Priority is derived from likelihood × impact. The table is ordered by priority, resolved items last.

ID Risk Likelihood Impact Priority Mitigation / Status

R-3

draw.io XML format changes — the format is not formally versioned; a breaking change could break the sync engine.

Medium

High

High

Custom bausteinsicht_id attributes are unlikely to conflict; templates carry bausteinsicht_template_version. The draw.io version is pinned in the devcontainer. Open.

R-6

DSL import parsing errors — Structurizr DSL / LikeC4 parsers may fail on valid-but-unexpected syntax, losing data on import.

Medium

High

High

Comprehensive error messages + validation warnings; add roundtrip tests (import → export → import). Open. Burdens internal/importer.

R-5

LSP server crashes or hangs — editor integration depends on its availability.

Medium

Medium

Medium

Health checks, restart logic, timeout handling. Open. Burdens internal/lsp.

R-9

Headless draw.io dependency — PNG/SVG export drives the draw.io Electron app via xvfb + dbus; a fragile setup that fails silently in unusual environments.

Medium

Medium

Medium

Text exports (export-diagram/-sequence/-table) need no draw.io; the devcontainer pins the setup. Open. Burdens internal/export.

R-10

Auto-layout quality — the engine is a layered heuristic, not crossing-minimization; dense diagrams still need manual cleanup.

Medium

Low

Low

none layout mode + draw.io editing as escape hatch; see ADR-005. Open. Burdens internal/layout.

R-4

Large-model sync performance — O(n·m) element/view matching on every run.

Low

Medium

Low

Go keeps this acceptable below ~1000 elements; profile with a 500-element model. Open (v2).

R-7

Large-model export performance — exporting 1000+ elements to text/DSL could be slow.

Low

Medium

Low

Streaming export for large models; profile at 500 elements. Open (v2).

R-8

Search completeness — pattern matching might miss results due to escaping or scope filtering.

Low

Low

Low

Property-based tests for search patterns; edge cases (special chars, deep nesting). Open. Burdens internal/search.

R-11

Supply chain (SEC-014) — the Dockerfile downloads install scripts without checksum verification.

Low

Medium

Low

Deferred; see the security review. Affects the dev/CI image only, not the released binary.

R-1

Path traversal via --model / --template / --output — an agent with untrusted input could read/write outside the working directory.

—

—

Resolved

validatePathContainment rejects ../escaping paths (exit 2), SEC-001/SEC-016; documented in the trust model.

R-2

Sync-state file corruption — a corrupt .bausteinsicht-sync could make the next sync treat everything as new.

—

—

Resolved

The state file carries a SHA-256 checksum verified on load (internal/sync/state.go); it is also committed to git (recoverable).

Technical Debts

Each item names the building block it burdens (see Chapter 5).

  • D-1 — Auto-layout is heuristic (internal/layout, internal/sync): layered/grid placement, not edge-crossing minimization. Adequate for typical C4 diagrams; a force-directed engine remains a future option (ADR-005). (Replaces the former "no auto-layout" debt — auto-layout now ships.)

  • D-2 — REPL full-save loses JSONC comments (cmd/bausteinsicht repl, internal/model patch): pure additions are patched comment-preserving, but any modification/deletion falls back to a full rewrite that drops comments (with a visible warning). Tracked in #410.

  • D-3 — LSP editor support (internal/lsp): the server works but only the VS Code integration is complete; extend to Neovim/Sublime/Emacs.

  • D-4 — Import/export roundtrip is lossy (internal/importer, internal/exporter): Structurizr/LikeC4 import and Structurizr export may drop custom metadata on a full cycle; document lossy fields, plan full roundtrip for v2.

  • D-5 — Coverage gate friction (CI): the SonarCloud new-code-coverage gate (80%) blocks refactors touching untested legacy code while the baseline is ~70%; see #449.

Non-Risks

The following were evaluated and confirmed not to be threats (see ATAM Non-Risks):

  • XXE / XML-bomb — the draw.io XML parser does not expand external entities.

  • JSON deserialization — Go’s encoding/json is memory-safe.

  • Command injection from input — the tool does invoke external binaries (internal/export → draw.io, internal/stale & internal/changelog → git, internal/lsp re-exec), but they are resolved from PATH and their names/arguments are never derived from model or template content, so untrusted input cannot inject a command. Harden PATH in restricted environments.

  • Supply chain — the product binary uses no npm and only 4 direct Go modules (beevik/etree, fsnotify, cobra, pgregory.net/rapid), with module verification; the optional VS Code extension is a separate TypeScript/npm artifact, not part of the CLI.

  • Regression safety — 863 test functions (9 skipped), property-based tests (pgregory.net/rapid), and pre-commit hooks guard the build.