Bausteinsicht Mini-ATAM Review Update

.1. Review Context

This is a follow-up Mini-ATAM review assessing the Bausteinsicht architecture 24 days after the initial full ATAM review (2026-03-06). It focuses on three questions:

  1. Which recommendations from the initial review have been implemented?

  2. Have new architectural changes introduced new risks or tradeoffs?

  3. Is the architecture still aligned with its quality goals?

.1.1. Method

Delta review against the initial ATAM findings. No new utility tree or full scenario analysis — the quality scenarios (QS-1 through QS-6) remain unchanged.

.1.2. Input Artifacts

  • Initial ATAM review (2026-03-06)

  • Git history since 2026-03-06 (24 commits)

  • Current test suite (387 passing, 3 skipped)

  • Current go.mod dependencies

.2. Recommendation Tracking

.2.1. Group A — Before v1 Release

ID Recommendation Status Evidence

A.1

Document trust model for CLI flag handling

[check circle] Done

src/docs/spec/07_trust_model.adoc added (#255)

A.2

Add development checklist for new model fields (PatchSave)

[check circle] Done

Documented (#256)

A.3

Ensure init workflow is prominent; consider additional templates

[minus circle] Partial

Getting-started improved (#257); additional template styles not yet added

.2.2. Group B — After v1 Release

ID Recommendation Status Evidence

B.1

Sync state file integrity check

[check circle] Done

Checksum added to .bausteinsicht-sync (#259), internal/sync/state.go

B.2

Pin tested draw.io version

[check circle] Done

Pinned in Dockerfile (#260)

B.3

Version the template format

[check circle] Done

Template versioning in internal/drawio/template.go (#261)

B.4

Add sync mutex in watch mode

[check circle] Done

Mutex in internal/watcher/watcher.go (#262)

B.5

Evaluate auto-layout

[check circle] Done

BFS-based layered layout engine (#3360519), ADR-005 accepted

.2.3. Group C — v2 Considerations

ID Recommendation Status Evidence

C.1

Profile with 500+ element models; add benchmarks

[check circle] Done

Benchmarks in internal/sync/bench_test.go (#263)

C.2

Add configurable recursion depth limit (default 50)

[check circle] Done

Depth limit in internal/model/resolve.go (#258)

C.3

Evaluate LSP implementation

[times circle] Not started

—

C.4

Consider template gallery

[times circle] Not started

—

Summary: 11 of 13 recommendations addressed. Remaining two (C.3 LSP, C.4 template gallery) are v2 scope.

.3. Updated Risk Assessment

.3.1. Resolved Risks

ID Risk Resolution

R-2

Sync state file corruption

Integrity checksum added (#259). Corrupted state now produces clear error message.

R-7

Watch mode race conditions

Mutex guard added (#262). No concurrent sync runs possible.

R-8

Missing recursion depth limit

Depth limit of 50 implemented (#258) with error message.

.3.2. Mitigated Risks (reduced severity)

ID Risk Change

R-1

Path traversal via CLI flags

Trust model documented (#255). --restrict-to-dir flag not yet implemented — risk reduced from Medium to Low for documented use cases.

R-3

draw.io XML format changes

draw.io version pinned in Dockerfile (#260). Integration tests against multiple versions still missing — risk remains Medium likelihood, High impact.

R-5

PatchSave regression with new fields

Dev checklist added (#256). Risk remains Medium but process mitigation is in place.

R-6

Template compatibility across versions

Template versioning implemented (#261). Migration path for breaking changes still needs documentation.

.3.3. New Risk: Auto-Layout Engine

R-9: Auto-Layout Quality for Complex Diagrams

Likelihood: Medium — the BFS-based layered layout does not consider relationships (no edge-crossing minimization).
Impact: Low — layout is only applied to new pages; existing positions preserved. Users can manually adjust or use --relayout.
Affected QS: QS-1 (learnability — first impression of a generated diagram), QS-3 (LLM friendliness — automated diagrams may have crossing edges).
Mitigation: Per-view layout property allows switching to grid or none. --relayout provides re-application.
Recommendation: [C] Monitor user feedback. Consider relationship-aware layout (force-directed) as additional mode if needed.

.4. Updated Sensitivity Points

ID Description Severity Change since initial review

SP-1

RenderedElements mapping in reverse sync

HIGH

Unchanged. Bug fixes in #265, #266, #268 address edge cases but fundamental sensitivity remains.

SP-2

JSONC PatchSave boundaries

MEDIUM

Unchanged. Dev checklist (A.2) reduces regression risk but byte-level patching remains inherently fragile.

SP-3

JSON Schema completeness

MEDIUM

Unchanged. No new model constructs added since review.

SP-4

add-element / sync state coordination

MEDIUM

Unchanged. No architectural change to the two-step workflow.

SP-5

AutoDetect first-match template behavior

LOW

Template versioning (#261) adds metadata but does not change the matching algorithm.

.4.1. New Sensitivity Point

SP-6: Layout Algorithm Tier Assignment (LOW)

The layered layout assigns elements to tiers based on the definition order of kinds in specification.elements. If a user reorders their specification, all auto-layouts change. This is documented in ADR-005 as intended behavior, but could surprise users who don’t expect visual changes from specification reordering.

.5. Updated Tradeoff Analysis

.5.1. TP-1 Resolved: Auto-Layout Now Available

The most significant tradeoff from the initial review — manual layout vs. auto-layout (TP-1) — has been resolved by ADR-005.

Before (TP-1) After (ADR-005)

First sync produced flat row of elements

First sync produces layered layout grouped by element kind

LLM workflows could not produce readable diagrams

LLM workflows get architecturally meaningful layouts automatically

User had to manually arrange every element

User positions preserved after initial layout; --relayout for reset

New tradeoff: The layered layout does not minimize edge crossings (no relationship awareness). This is a conscious decision documented in ADR-005 — relationship-aware layout can be added as an additional mode later.

.5.2. Remaining Tradeoffs (unchanged)

ID Decision Assessment

TP-2

JSONC vs. custom DSL

Still valid. JSON verbosity accepted for IDE/LLM benefits.

TP-3

Byte-level patcher vs. full round-trip

Still valid. Dev checklist mitigates maintenance burden.

TP-4

Model-wins conflict resolution

Still valid. No user requests for interactive merge reported.

TP-5

CLI-only interface

Still valid. LSP (C.3) would address real-time feedback gap but is v2 scope.

TP-6

Embedded templates (no gallery)

Partially addressed — template versioning added, but still only one default template.

.6. Test Suite Health

Metric Initial Review (2026-03-06) Current (2026-03-30)

Total tests

215

387

Passing

188

387

Skipped

26

3

Unexpected failures

0

0

Property-based tests

Present (label roundtrip)

Present (label roundtrip)

Benchmarks

Not present

Added (#263)

Notable improvement: Skipped tests reduced from 26 to 3. Test count nearly doubled (215 → 387).

The 3 remaining skips:

  • TestSyncPreservesJSONCComments — environment-dependent

  • TestSyncConcurrentModelAndDrawioChanges — environment-dependent

  • TestExportPage_Integration — requires draw.io binary

All 9 packages pass. No race conditions detected.

.7. Dependency Status

Dependencies remain minimal and unchanged:

Dependency Version CVEs

beevik/etree

v1.6.0

None

fsnotify/fsnotify

v1.9.0

None

spf13/cobra

v1.10.2

None

pgregory.net/rapid

v1.2.0

None (test only)

golang.org/x/sys

v0.41.0

None

Go

1.24.0

None

Supply chain risk remains minimal: 5 direct dependencies, no npm, no post-install scripts.

.8. Findings Summary

.8.1. What improved since the initial review

  1. 11 of 13 recommendations implemented — including all Group A (pre-release) and all Group B (post-release) items

  2. Auto-layout engine (ADR-005) resolves the most impactful tradeoff (TP-1) from the initial review

  3. Test suite nearly doubled (215 → 387 tests) with only 3 skips remaining

  4. Three risks fully resolved (R-2 state corruption, R-7 watch race, R-8 recursion depth)

  5. Benchmarks added to CI, enabling performance regression detection

.8.2. What remains open

  1. R-3 (draw.io format changes) — version pinned but multi-version integration tests still missing

  2. R-1 (path traversal) — trust model documented, but --restrict-to-dir flag not implemented

  3. TP-5 (CLI-only) — LSP evaluation (C.3) not started

  4. TP-6 (template gallery) — still a single default template

.8.3. New findings

  1. R-9 (auto-layout quality) — new LOW risk from layout engine not considering relationships

  2. SP-6 (tier assignment sensitivity) — specification reordering changes layouts

.8.4. Overall Assessment

The architecture has significantly matured since the initial ATAM review. The rapid implementation of recommendations demonstrates good architectural governance.

The core architecture remains well-aligned with all six quality goals:

  • QS-1 (Learnability): Improved by auto-layout — first diagrams are now immediately readable

  • QS-2 (IDE Support): Unchanged — JSON Schema works well

  • QS-3 (LLM Friendliness): Improved by auto-layout — LLM-driven workflows produce meaningful diagrams

  • QS-4 (Sync Reliability): Strengthened by state file checksums, watch mutex, and depth limits

  • QS-5 (Installability): Unchanged — single binary, zero dependencies

  • QS-6 (Flexible Hierarchy): Unchanged — arbitrary nesting with depth limit safety

Architecture readiness: Ready for v1 release. No blocking risks remain. The two open Group C items (LSP, template gallery) are appropriate for a v2 roadmap.