Bausteinsicht User Manual

Bausteinsicht is an architecture-as-code tool that keeps a JSONC model and draw.io diagrams in bidirectional sync. You define your architecture in a text file, and Bausteinsicht generates and updates visual diagrams automatically.

Installation

Build from Source

git clone https://github.com/docToolchain/Bausteinsicht.git
cd Bausteinsicht
go build -o bausteinsicht ./cmd/bausteinsicht/

Move the binary to a directory in your PATH:

sudo mv bausteinsicht /usr/local/bin/

Verify the installation:

bausteinsicht --version

Prerequisites

  • draw.io Desktop or the VS Code draw.io extension

  • A text editor with JSON support (VS Code recommended for autocompletion via JSON Schema)

Quick Start

mkdir my-architecture && cd my-architecture
bausteinsicht init
bausteinsicht sync

This creates a sample Online Shop architecture with three views. Open architecture.drawio in draw.io to see the generated diagrams.

For a detailed walkthrough, see the Getting Started Tutorial.

Daily Workflow

The typical workflow alternates between editing the model and arranging diagrams:

┌─────────────────┐     sync      ┌─────────────────┐
│  architecture   │ ───────────►  │  architecture   │
│    .jsonc       │ ◄───────────  │    .drawio      │
│  (text editor)  │               │  (draw.io)      │
└─────────────────┘               └─────────────────┘

Forward Sync (Model → Diagram)

  1. Edit architecture.jsonc in your text editor

  2. Run bausteinsicht sync

  3. Reload the .drawio file — new elements appear with a red dashed border

  4. Drag elements to arrange the layout, then save

Reverse Sync (Diagram → Model)

  1. Open architecture.drawio in draw.io

  2. Edit element text — each element contains child text cells for title, technology, and description that can be edited independently

  3. Save the .drawio file

  4. Run bausteinsicht sync

  5. Check architecture.jsonc — your changes are reflected

Watch Mode

For continuous synchronization while you work:

bausteinsicht watch

Bausteinsicht watches both files and syncs automatically on save. Press Ctrl+C to stop.

The Architecture Model

The model file (architecture.jsonc) is a JSONC file with four sections.

Specification

Defines the element kinds and relationship kinds available in your model. This is like a vocabulary for your architecture:

"specification": {
  "elements": {
    "actor":     { "notation": "Actor",           "description": "A person or external system" },
    "system":    { "notation": "Software System",  "container": true },
    "container": { "notation": "Container",        "container": true },
    "component": { "notation": "Component",        "container": true }
  },
  "relationships": {
    "uses":  { "notation": "uses" },
    "async": { "notation": "async", "dashed": true }
  }
}

Set container: true for kinds that can hold children.

Model

Defines your architecture elements in a hierarchy. Element keys are unique IDs, children nest naturally:

"model": {
  "customer": {
    "kind": "actor",
    "title": "Customer",
    "description": "End user of the webshop"
  },
  "webshop": {
    "kind": "system",
    "title": "Webshop",
    "children": {
      "api": {
        "kind": "container",
        "title": "REST API",
        "technology": "Go"
      }
    }
  }
}

Nested elements are referenced with dot notation: webshop.api.

Relationships

Connections between elements:

"relationships": [
  {
    "from": "customer",
    "to": "webshop.api",
    "label": "uses",
    "kind": "uses",
    "description": "Sends HTTP requests"
  }
]

Views

Views define which elements appear on each diagram page. See Multi-View Architecture for details.

Adding Elements and Relationships

Via Text Editor

Edit architecture.jsonc directly, then run bausteinsicht sync.

Via CLI

Add elements without editing JSON:

bausteinsicht add element \
  --id emailservice \
  --kind container \
  --title "Email Service" \
  --technology "Go" \
  --parent onlineshop \
  --description "Sends transactional emails"

Add relationships:

bausteinsicht add relationship \
  --from onlineshop.api \
  --to onlineshop.emailservice \
  --label "sends emails" \
  --kind uses

After adding, run bausteinsicht sync to update the diagram.

Multi-View Architecture

Views control which elements appear on each diagram page. Each view becomes a tab in the draw.io file.

Basic View

A simple view lists elements to include:

"context": {
  "title": "System Context",
  "include": ["customer", "webshop"]
}

Wildcard Includes

Use .* to include all direct children of an element:

"containers": {
  "title": "Container View",
  "include": ["customer", "webshop.*"]
}

webshop.* matches webshop.api, webshop.frontend, webshop.db — but not webshop itself.

Scope and Bounding Boxes

The scope property renders the parent element as a visual boundary (swimlane) with its children nested inside:

"containers": {
  "title": "Container View",
  "scope": "webshop",
  "include": ["customer", "webshop.*"]
}

This renders webshop as a labeled box containing its children, with customer outside as an external actor.

Exclude

Remove specific elements from a view:

"overview": {
  "title": "Overview",
  "include": ["webshop.*"],
  "exclude": ["webshop.db"]
}

Relationship Lifting

When a relationship endpoint is not on a view page but its parent is, the connector is automatically "lifted" to the parent.

Example: the model has customer → webshop.frontend, but the System Context view only includes customer and webshop. Bausteinsicht renders this as customer → webshop on the context page.

This happens automatically — no configuration needed.

Template Customization

Templates control the visual style of elements in draw.io.

Template File Structure

The template (template.drawio) is a draw.io file with sample elements tagged via bausteinsicht_template:

  • Element templates: bausteinsicht_template="actor", "system", "container", "component"

  • Boundary templates: bausteinsicht_template="system_boundary", "container_boundary"

  • Connector template: bausteinsicht_template="relationship"

Customizing Styles

  1. Open template.drawio in draw.io

  2. Modify colors, fonts, shapes, sizes of the template elements

  3. Save the file

  4. Run bausteinsicht sync — new elements use the updated styles

Existing elements keep their current style. Only newly created elements pick up template changes.

Template Properties Used

From each template element, Bausteinsicht extracts:

  • style — the full mxCell style string (must include container=1;)

  • width and height — default dimensions from mxGeometry

  • sub-cell styles — font size, color, weight, and vertical position for title, technology, and description text cells (from child <mxCell> elements with -title, -tech, -desc ID suffixes)

Validation

Check your model for errors before syncing:

bausteinsicht validate

Output: Model is valid. or a list of errors.

For machine-readable output:

bausteinsicht validate --format json
{
  "valid": true,
  "errors": []
}

LLM Integration

Bausteinsicht is designed for AI-assisted architecture work. All commands support --format json for machine-readable output.

AI Agent Workflow

An LLM can drive architecture changes entirely through CLI commands:

# Add elements
bausteinsicht add element --id cache --kind container \
  --title "Cache" --technology "Redis" --parent webshop --format json

# Add relationships
bausteinsicht add relationship --from webshop.api --to webshop.cache \
  --label "caches" --kind uses --format json

# Sync and verify
bausteinsicht sync --format json
bausteinsicht validate --format json

JSON Schema Support

The model file references a JSON Schema for IDE autocompletion and validation:

{
  "$schema": "https://raw.githubusercontent.com/docToolchain/Bausteinsicht/main/schema/bausteinsicht.schema.json",
  ...
}

This enables autocompletion in VS Code, IntelliJ, and other editors without plugins.

Troubleshooting

"no such file or directory" on sync

The .drawio file must exist before syncing. Run bausteinsicht init first, or ensure both architecture.jsonc and architecture.drawio are present.

Elements appear with red dashed borders

This is intentional. New elements are marked with a red dashed border (strokeColor=#FF0000;dashed=1;) so you can spot them in draw.io. Edit the element’s style in draw.io to remove the marker after arranging.

Changes not appearing after sync

  • draw.io: Close and reopen the file, or press Ctrl+Shift+R to reload

  • Watch mode: Verify the watcher is running and the correct files are being watched

  • Relationships missing: Check that both endpoints are included in the view’s include list

Sync conflict

When both the model and draw.io change the same field between syncs, Bausteinsicht reports a conflict. Resolve by choosing one version and running sync again.

PNG/SVG export fails in headless or container environments

The bausteinsicht export command uses the draw.io Desktop CLI (Electron app) to render images. In headless environments (Docker, devcontainers, CI, WSL2), this requires:

  1. A virtual X display — provided by xvfb. The drawio-export wrapper script handles this automatically.

  2. A running D-Bus system daemon — Electron requires D-Bus for IPC. Without it, export fails with "Export failed" or "input file/directory not found".

    # Start dbus (required once per container session)
sudo mkdir -p /run/dbus
sudo dbus-daemon --system --fork

  3. The --no-sandbox flag — required in containers without user namespace support. The drawio-export wrapper includes this flag.

The Bausteinsicht devcontainer (.devcontainer/) handles all of this automatically. If you build your own container, ensure dbus and xvfb are installed and dbus is started before exporting.

Note
 GPU errors like "Exiting GPU process due to errors during initialization" in stderr are harmless — draw.io falls back to software rendering.

draw.io pages look identical

If element IDs collide across pages, draw.io may render pages incorrectly. Bausteinsicht uses page-scoped IDs (viewID—​elementID) to prevent this. If you see this issue, delete .bausteinsicht-sync and architecture.drawio, then re-init and sync.

Exporting Diagrams

Export views as PNG or SVG images for embedding in documentation:

bausteinsicht export --image-format png
bausteinsicht export --image-format svg --view context
bausteinsicht export --image-format png --scale 2.0 --output ./images/

Export as text-based diagrams:

bausteinsicht export-diagram --diagram-format plantuml
bausteinsicht export-diagram --diagram-format mermaid

Export element tables:

bausteinsicht export-table --table-format adoc --output elements.adoc
bausteinsicht export-table --table-format markdown
Note
 Image export requires the draw.io Desktop CLI. In containers, the drawio-export wrapper handles headless rendering via xvfb. See Command Reference for common export issues.

Command Reference

See the CLI Specification for full command details.

Command Description

bausteinsicht init

Initialize a new project with sample model and template

bausteinsicht sync

Run one bidirectional sync cycle

bausteinsicht validate

Validate model without syncing

bausteinsicht watch

Continuously sync on file changes

bausteinsicht add element

Add element to model

bausteinsicht add relationship

Add relationship to model

bausteinsicht export

Export views as PNG/SVG images

bausteinsicht export-diagram

Export views as PlantUML or Mermaid diagrams

bausteinsicht export-table

Export element list as AsciiDoc or Markdown table

bausteinsicht --version

Display version number

Global Flags

Flag Description

--format json|text

Output format (default: text)

--model <path>

Path to model file (default: auto-detect)

--template <path>

Path to template file

--verbose

Enable debug output

Further Reading