The ATAM is a structured method for evaluating software architectures against quality attribute requirements. It identifies sensitivity points (architectural decisions that critically affect a single quality attribute), tradeoff points (decisions that affect multiple quality attributes in tension), risks (decisions that may cause problems), and non-risks (decisions confirmed as safe).

This review covers the Bausteinsicht v1 architecture as documented in the arc42 template (chapters 1-11), the four Architecture Decision Records (ADR-001 through ADR-004), and the sync specification. It is a retrospective review performed before the v1 public release.

Maintainers, contributors, and adopters evaluating Bausteinsicht for use in their organizations.

The utility tree maps quality attributes to concrete scenarios with importance (H/M/L) and difficulty (H/M/L) ratings.

Reference: ADR-001

The architecture model is defined in JSONC (JSON with Comments) and validated against a JSON Schema. JSONC provides universal IDE support via SchemaStore, is natively readable by LLMs, and requires no custom parser. The schema serves as living documentation and enables autocompletion without plugins.

Addresses: QS-1 (learnability via familiar format), QS-2 (IDE support), QS-3 (LLM friendliness), QS-6 (schema allows arbitrary nesting).

Reference: ADR-002

The tool is implemented in Go, producing a statically linked binary with no runtime dependencies. Go provides compile-time type safety, fast startup (<10 ms), cross-compilation from a single build machine, and a minimal supply chain (no post-install script execution).

Addresses: QS-5 (installability), BG-4 (zero dependencies), security concerns (no npm supply chain).

Element appearance in draw.io is controlled by template files that are themselves draw.io diagrams. The sync engine looks up element kinds in the template and copies the visual style. This avoids a custom style language and lets users design templates in the same tool they use for viewing.

Addresses: QS-1 (no new style syntax to learn), BG-1 (draw.io as frontend).

Bidirectional synchronization uses a .bausteinsicht-sync state file containing SHA-256 hashes of the last known model and draw.io state. On sync, the engine compares current model, current draw.io, and last-known state to determine which side changed. Conflicts (same field changed on both sides) produce warnings; non-conflicting changes merge cleanly.

Addresses: QS-4 (sync reliability), BG-1 (bidirectional flow with draw.io).

The codebase is organized into four packages with clear data flow: model (JSON world) → sync (three-way merge) → drawio (XML world), orchestrated by a thin CLI layer. Each package operates on its own data representation, with the sync engine mediating between them.

Addresses: maintainability, testability, separation of concerns.

Reverse sync (draw.io → model) uses a byte-level JSONC patcher (PatchSave) rather than full JSON round-trip. This preserves user comments, formatting, and trailing commas in the model file.

Addresses: QS-1 (users expect their comments to survive), QS-4 (no silent formatting loss).

All functionality is exposed exclusively through CLI commands (sync, validate, watch, add-element, add-relationship, export-diagram, export-table). There is no GUI, web UI, or language server.

Addresses: QS-3 (LLM agents invoke CLI), QS-5 (nothing to install beyond the binary), BG-2 (automation).

Sensitivity: SP-3: JSON Schema Completeness (MEDIUM) — Schema completeness directly impacts learnability; incomplete schemas degrade the experience.

Sensitivity: SP-3: JSON Schema Completeness (MEDIUM) — Schema must cover all valid model constructs to provide accurate suggestions.

Tradeoff: TP-2: JSONC vs. Custom DSL — JSONC verbosity vs. custom DSL conciseness; JSON wins for LLMs but is more verbose for humans.

Sensitivity: SP-1: RenderedElements in Reverse Sync (HIGH) (RenderedElements), SP-2: JSONC PatchSave Boundaries (MEDIUM) (PatchSave boundaries), SP-4: add-element / Sync State Coordination (MEDIUM) (add-element coordination).
Tradeoff: TP-3: Byte-Level Patcher vs. Full Round-Trip (byte-level patcher vs. full round-trip), TP-4: Model-Wins vs. Interactive Merge (model-wins vs. interactive merge).

No sensitivity or tradeoff points identified. This is a solved problem with Go.

Sensitivity: SP-5: AutoDetect First-Match Behavior (LOW) — AutoDetect first-match behavior may misclassify elements at unusual nesting levels.

The reverse sync must determine which draw.io elements correspond to model elements. This mapping relies on bausteinsicht_id attributes embedded in the XML. If an element lacks this attribute (e.g., manually drawn shapes), it is treated as a new element and imported with a sanitized ID.

Impact: Incorrect mapping causes duplicate elements or lost edits.
Affected QS: QS-4 (sync reliability).
Current mitigation: Collision guards prevent duplicate IDs; sanitization is deterministic.
Residual risk: Complex manual edits in draw.io may produce unexpected import results.

The PatchSave function performs byte-level patching of the JSONC model file, replacing only the values of known fields while preserving surrounding comments and formatting. This approach has inherent boundaries: it cannot handle structural changes (adding/removing entire elements) and relies on pattern matching to locate fields.

Impact: If the patcher cannot locate a field, it falls back to full file rewrite, losing comments.
Affected QS: QS-1 (comments are part of learnability), QS-4 (formatting preservation).
Current mitigation: E2E test 4.16 confirms that preamble comments before the root { are lost during reverse sync (known issue, LOW severity).
Residual risk: Edge cases with unusual JSONC formatting may trigger fallback.

IDE autocompletion quality depends entirely on JSON Schema coverage. Missing or incorrect schema definitions result in no suggestions or false validation errors.

Impact: Incomplete schema directly degrades QS-1 (learnability) and QS-2 (IDE support).
Affected QS: QS-1, QS-2.
Current mitigation: Schema is tested via validate command; E2E tests cover all model constructs.
Residual risk: Schema may lag behind new features if not updated in the same PR.

The add-element CLI command modifies the model file directly. If the sync state file is stale (not updated after the addition), the next sync may treat the new element as a conflict or may miss it.

Impact: Stale state causes spurious conflict warnings or missed forward sync of new elements.
Affected QS: QS-4 (sync reliability), QS-3 (LLM workflows rely on add-element + sync sequences).
Current mitigation: add-element does not update sync state; a subsequent sync resolves this naturally.
Residual risk: Users who run add-element without sync may see unexpected behavior on later sync.

When a template contains multiple element kinds, AutoDetect assigns the first matching kind based on nesting level. If the template order changes, element styling may silently change.

Impact: Unexpected visual changes after template modification.
Affected QS: QS-1 (confusing for users who edit templates).
Current mitigation: Template handling E2E tests verify style assignment.
Residual risk: Low; templates are typically authored once and rarely reordered.

Decision: Bausteinsicht performs no automatic layout. Elements are placed side-by-side with fixed offsets; users arrange them manually in draw.io.

Affected QS: QS-1 (learnability — manual layout adds a step), QS-3 (LLM friendliness — automated diagrams look poor).

Reference: ADR-001

Decision: JSONC with JSON Schema, not a custom DSL (like Structurizr DSL or LikeC4).

Decision: PatchSave patches specific fields in-place rather than parsing and re-serializing the entire JSONC file.

Affected QS: QS-4 (reliability — see SP-2: JSONC PatchSave Boundaries (MEDIUM)), QS-1 (comments preserved).

Decision: On true conflicts (same field changed in both model and draw.io), the model value wins and a warning is printed.

Affected QS: QS-3 (LLM friendliness — deterministic wins), QS-4 (sync reliability — data loss path exists for draw.io edits).

Decision: No language server, no web UI, no editor extension. CLI only.

Decision: A default template ships via bausteinsicht init, but templates are user-provided draw.io files referenced by path. No built-in template gallery or marketplace.

Affected QS: QS-1 (learnability — mitigated by init command).

Likelihood: Medium — the tool accepts --model and --template paths without validation.
Impact: Medium — an attacker who controls CLI arguments could read or write files outside the intended directory.
Reference: SEC-001 in the security review.
Mitigation: The tool is a local CLI invoked by the user; the user already has filesystem access. Risk is relevant only when CLI is invoked by automated agents with untrusted input.
Recommendation: [A] Document the trust model. Consider optional --restrict-to-dir flag for agent use cases.

Likelihood: Low — the .bausteinsicht-sync file is a plain JSON file written atomically.
Impact: High — a corrupted state file causes the next sync to treat everything as new, potentially duplicating elements or losing conflict detection.
Mitigation: The state file is committed to version control; git checkout recovers it. The sync engine handles missing state files gracefully (treats as first sync).
Recommendation: [B] Add state file integrity check (e.g., embedded checksum) and clear error message on corruption.

Likelihood: Medium — draw.io is actively developed and the XML format is not formally versioned.
Impact: High — breaking changes in draw.io’s XML structure could break the sync engine’s XML processing.
Mitigation: The sync engine uses bausteinsicht_id attributes for element identification, which are custom attributes unlikely to conflict with draw.io changes. XML processing uses beevik/etree for DOM-style access, not hardcoded XPath.
Recommendation: [B] Pin a tested draw.io version in documentation. Add integration tests against multiple draw.io versions.

Likelihood: Low — current users have small models (<100 elements).
Impact: Medium — the sync engine processes all elements on every run; O(n*m) complexity for element-view matching could become noticeable at scale.
Mitigation: Go’s performance characteristics make this unlikely to be a problem below ~1000 elements.
Recommendation: [C] Profile with a 500-element model. Add benchmarks to CI.

Likelihood: Medium — every new model field requires PatchSave support.
Impact: Medium — missing patcher support causes comments to be lost when the new field is modified via reverse sync.
Mitigation: Property-based tests with rapid cover label roundtrips. E2E tests verify comment preservation.
Recommendation: [A] Add a development checklist: "When adding a model field, update PatchSave and add a comment-preservation test."

Likelihood: Low — template format is not versioned.
Impact: Medium — future changes to element rendering may require template updates, breaking existing user templates.
Mitigation: Templates are simple draw.io files with convention-based element kind names.
Recommendation: [B] Version the template format. Document migration path for breaking changes.

Likelihood: Low — fsnotify delivers events asynchronously; rapid file saves may trigger multiple syncs.
Impact: Low — concurrent syncs on the same files could produce inconsistent results.
Mitigation: Watch mode debounces events. Data race in watcher fixed in PR #77 (SEC-003).
Recommendation: [B] Add mutex or single-flight guard for sync execution in watch mode.

Likelihood: Low — requires a maliciously crafted model with extreme nesting.
Impact: Low — stack overflow on deeply recursive model processing.
Mitigation: Practical models have <10 nesting levels. Go stack grows dynamically.
Recommendation: [C] Add configurable depth limit (default 50) with clear error message.

The XML parser (beevik/etree) uses RawToken which does not expand external entities. XML bomb attacks are structurally impossible. Confirmed in security review.

Go’s encoding/json package does not execute code during deserialization. No equivalent of Python’s pickle or Java’s ObjectInputStream risks.

The codebase contains no os/exec calls. All processing is in-process string and XML manipulation. Confirmed by gosec scan.

The tool has no JavaScript or Node.js dependencies. Go module verification (go mod verify) passes. Only 5 direct Go dependencies, all with no known CVEs.

215 E2E tests (188 pass, 26 skip, 0 unexpected fail) cover all major features. Property-based tests validate roundtrip invariants. Pre-commit hooks run gofmt, go vet, golangci-lint, and gitleaks.

Temporary files use os.CreateTemp (fixed in PR #77, SEC-002). File permissions are appropriate for a user-space CLI tool.

Explicitly excluded by ADR-002. draw.io CLI is used only in the devcontainer for PNG/SVG export, not in the distributed binary.