Context and Scope

Business Context

Bausteinsicht sits between the architecture model (JSON files) and draw.io diagrams, synchronizing both bidirectionally.

Architecture Maintenance Process

The following activity diagram shows how Bausteinsicht fits into the daily architecture workflow. The architect chooses between editing the text model or the visual diagram — Bausteinsicht synchronizes both directions.

business context process

System Context

System Context
Figure 1. System Context (generated from architecture model)
Element Kind Technology Description

Bausteinsicht

system

Architecture-as-code tool with draw.io as visual frontend and bidirectional synchronization

Developer

actor

Developer using the Bausteinsicht CLI to manage architecture models

draw.io App

external_system

draw.io desktop or web application for visual diagram editing

IDE

external_system

IDE with JSON Schema support for JSONC editing with autocompletion
Note
 The generated diagram above is itself produced from a Bausteinsicht model and shows the principal technical partners (developer, draw.io, IDE). The table below is the authoritative, complete set of communication partners — including the human architect, LLM agents, and git, which act on the system rather than appearing inside its own context view.
Communication Partner Input Output

Software Architect

Edits to architecture model (JSONC) or draw.io diagrams

Synchronized model and diagrams

Developer

—

Up-to-date architecture diagrams in draw.io

LLM Agent

CLI commands (add element, sync, validate)

Updated model files, validation results

draw.io

Visual edits to diagram elements and relationships

Generated/updated diagram XML

IDE (VS Code, IntelliJ, etc.)

JSON Schema

Autocompletion, validation, hover docs for model files

Git

Version-controlled model and diagram files

Diff-friendly text-based file changes

Technical Context

Interface Technology Description

Architecture Model

JSONC files on filesystem

The model is stored as .jsonc files in the project directory. Validated against a JSON Schema.

draw.io Diagrams

mxGraph XML files on filesystem

Standard .drawio files that can be opened in draw.io desktop, VS Code extension, or draw.io online.

Templates

mxGraph XML files on filesystem

draw.io files containing styled reference elements for each element kind.

CLI

Go binary (stdin/stdout)

Command-line interface for sync, validate, watch, and model manipulation commands.

File System Watcher

OS-native (inotify/FSEvents/ReadDirectoryChanges)

Watches model and diagram files for changes in watch mode.

JSON Schema

Published schema file (local or SchemaStore.org)

Enables IDE support without Bausteinsicht-specific plugins.

draw.io CLI

External process (auto-detected on PATH)

export invokes the headless draw.io binary to render diagram pages to PNG/SVG.

Git

External process (git log)

stale and changelog read element history from the repository; optional (graceful degradation outside git).

Import / export formats

Files on filesystem

In: Structurizr DSL (.dsl), LikeC4 (.c4). Out: C4-PlantUML, Mermaid, DOT, D2, HTML, Structurizr DSL, sequence diagrams, AsciiDoc/Markdown tables.

Language Server (LSP)

JSON-RPC over stdio

The bausteinsicht-lsp binary serves diagnostics and code lenses to editors (e.g. the VS Code extension).

Snapshot store

Files on filesystem (.bausteinsicht-snapshots/)

Versioned model captures written and read by the snapshot commands.