Runtime View

Sync Command

The most important runtime scenario. Shows what happens when the user runs bausteinsicht sync.

runtime sync

Key Observations

  • The sync engine receives all data as parameters — it performs no I/O itself

  • Forward sync runs before reverse sync in the same cycle

  • The state file is only written after both directions complete successfully

  • If any step fails, no files are written (atomic operation)

  • Forward sync adds metadata (title, source, author, timestamp) and a legend to each view page

Watch Mode

Shows the continuous sync loop triggered by file changes.

runtime watch

Debounce Strategy

File editors often trigger multiple save events in rapid succession (write + metadata update). The watcher debounces events with a 300ms window: after the first change event, it waits 300ms for additional events before triggering a sync.

Init Command

runtime init

LLM-Driven Modification

Shows how an LLM agent uses CLI commands to modify the architecture.

runtime llm

Design Decision: Separate Add and Sync

The add commands only modify the JSON model. They do not trigger a sync automatically. This keeps commands predictable (single responsibility) and allows LLMs to batch multiple model changes before syncing.

Import from Structurizr / LikeC4

Shows how an existing model is brought into Bausteinsicht (bausteinsicht import <file> --from structurizr|likec4).

runtime import

The result is immediately syncable with bausteinsicht sync. The importer never touches draw.io — it only produces the model.

REPL Save: Patch vs. Full-Save Fallback

The REPL keeps the model in memory and, on save, chooses how to persist so JSONC comments survive when possible. This is the key data-integrity flow.

runtime repl save

Key Observations

  • Validation runs before any write — an invalid model is never persisted.

  • Pure additions take the comment-preserving patch path; modifications/deletions conservatively fall back to a full rewrite with a visible warning about comment loss.

  • The same patch primitives back the non-interactive add commands.

Stale Detection

Shows how bausteinsicht stale flags forgotten elements using git history.

runtime stale

When run outside a git repository the git lookups degrade gracefully (no date), and detection falls back to the view/relationship membership checks.

Error & Recovery: Failed Write During Sync

The contract requires at least one error/recovery scenario. This shows why a failed or interrupted sync never corrupts the working files.

runtime recovery

Key Observations

  • The engine computes everything in memory first; files are written only afterwards, each via a temp-file-plus-rename so a partial write cannot truncate a real file.

  • The state file is written last. If any earlier write fails, the state is left untouched, so the next run re-detects the same change and retries — the operation is effectively idempotent and self-healing.

  • The state file carries a SHA-256 checksum, so external tampering or truncation is detected on load rather than silently trusted.