Solution Strategy

Technology Decisions

Decision Choice Rationale

Implementation language

Go (ADR-002)

Single-binary distribution, LLM-friendly code generation, compile-time type safety

Architecture model format

JSONC with JSON Schema (ADR-001)

Universal IDE support, zero parser effort, LLM-native read/write

draw.io XML processing

beevik/etree (with emicklei/mxgraph as optional accelerator)

Flexible DOM-style XML manipulation for dynamic attributes on <object> elements

CLI framework

Cobra

Battle-tested (kubectl, gh, terraform), built-in help generation, shell completion

File watching

fsnotify

Cross-platform file system events, no polling overhead

Top-Level Decomposition

Bausteinsicht follows a pipes-and-filters architecture with a clear separation between data formats:

solution decomposition

  • Model package reads/writes the JSON model. Knows nothing about draw.io XML.

  • DrawIO package reads/writes mxGraph XML. Knows nothing about the JSON model.

  • Sync Engine orchestrates the bidirectional sync between both formats, using a state file for three-way merge.

  • CLI layer is a thin shell delegating to these packages.

This decomposition ensures that model format changes (e.g., switching from JSONC to YAML) or draw.io format changes do not ripple across the codebase.

Quality Goal Strategies

Quality Goal Strategy

Learnability

bausteinsicht init scaffolds a working example. JSON Schema provides IDE autocompletion. draw.io template gives visual starting point. User is productive without reading documentation.

IDE Support

JSON Schema is published and referenced via $schema in the model file. Works out of the box in VS Code, IntelliJ, and any JSON Schema-aware editor. No plugin required.

LLM Friendliness

All CLI commands support --format json for structured output. add element and add relationship commands allow LLMs to modify the model without parsing JSON directly. The JSONC format is natively understood by all major LLMs.

Key Design Patterns

Three-Way Merge for Bidirectional Sync

Rather than simple overwrite, Bausteinsicht uses a .bausteinsicht-sync state file to detect which side changed. This prevents data loss when both the model and draw.io are edited between syncs. See Sync Specification for details.

Template-Based Styling

Visual styles are not hardcoded. A draw.io template file defines the appearance of each element kind via bausteinsicht_template attributes. Users can customize templates without modifying source code.

Thin CLI, Rich Library

The cmd/ layer contains only argument parsing and output formatting. All logic lives in internal/ packages that can be tested independently and reused (e.g., for a future LSP server or web API).