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
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.