Getting Started Tutorial

This tutorial walks you through the complete Bausteinsicht workflow in under 10 minutes.

Prerequisites

  • Bausteinsicht binary (build with go build -o bausteinsicht ./cmd/bausteinsicht/)

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

  • A text editor or IDE with JSON support (VS Code recommended)

Step 1: Initialize a Project

Create a new directory and initialize Bausteinsicht:

mkdir my-architecture
cd my-architecture
bausteinsicht init

This creates four files:

File Purpose

architecture.jsonc

Your architecture model (source of truth)

architecture.drawio

Generated draw.io diagram — open this in draw.io

template.drawio

Visual style templates for element kinds

.bausteinsicht-sync

Sync state file (commit to Git alongside the model)

Step 2: Explore the Sample Model

Open architecture.jsonc in your editor. You’ll see a sample Online Shop architecture:

bausteinsicht validate

Output: Model is valid.

The model contains:

  • Actors: Customer and Back-Office User

  • System: Online Shop, containing a Web Frontend, a Mobile App, a REST API (with Product Catalog, Order Processing, and Notification Service components), a Database, a Cache, a Message Queue, and Export Storage

  • External systems: Payment Provider and E-Mail Service

  • Relationships: e.g. the Customer uses the Web Frontend, the REST API reads/writes the Database, the Order Processing component charges the Payment Provider, and the Notification Service sends email asynchronously via the E-Mail Service

  • Views: System Context, Container View, API Components

  • Dynamic views (sequence diagrams): Checkout Flow and Catalog Browse

Note
 The E-Mail Service above is an external system the shop talks to. In Step 4 you will add a separate internal Email Service container — they are different elements that happen to have similar names.

Step 3: Open the Diagram

Open architecture.drawio in draw.io. You’ll see three tabs (pages):

  1. System Context — high-level view with Customer and Online Shop

  2. Container View — internal structure of the Online Shop

  3. API Components — components inside the REST API

New elements appear with a red dashed border as a visual marker. Drag them to arrange the layout.

Step 4: Add an Element via CLI

Add a new Email Service container to the Online Shop:

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

Output: Added element 'onlineshop.emailservice' (kind: container) to model.

Step 5: Add a Relationship

Connect the API to the new Email Service:

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

Output: Added relationship: onlineshop.api → onlineshop.emailservice (sends emails)

Step 6: Sync Model to Diagram

Run sync to update the draw.io diagram with the new element and relationship:

bausteinsicht sync

Output:

Forward (model → draw.io): 2 added, 0 updated, 0 deleted

Reload architecture.drawio in draw.io — the Email Service appears with a red dashed border. Drag it into position inside the Online Shop boundary.

Step 7: Edit in draw.io (Reverse Sync)

Now try the other direction:

  1. Open architecture.drawio in draw.io

  2. Double-click the "Web Frontend" element

  3. Change its title to "Web App"

  4. Save the file

Run sync again:

bausteinsicht sync

Output:

Reverse (draw.io → model): 0 added, 1 updated, 0 deleted

Check architecture.jsonc — the title has been updated to "Web App".

Step 8: Validate the Model

After manual edits, validate the model:

bausteinsicht validate

If everything is correct: Model is valid.

For JSON output (useful for LLM integration):

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

Step 9: Watch Mode

For continuous synchronization while you work:

bausteinsicht watch

Output:

Watching architecture.jsonc and architecture.drawio...

Now edit either file — Bausteinsicht automatically syncs on save. Press Ctrl+C to stop.

Step 10: LLM Integration

All commands support --format json for machine-readable output:

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

# Validate and parse results
bausteinsicht validate --format json

# Sync and get structured summary
bausteinsicht sync --format json

This makes Bausteinsicht ideal for AI-assisted architecture work — an LLM can modify the model via CLI commands without parsing JSON directly.

Next Steps

  • Customize the template — Edit template.drawio in draw.io to change colors, shapes, and sizes for your element kinds. See the Template Guide for details.

  • Add custom element kinds — Define new kinds in specification.elements and add matching template shapes.

  • Set up watch mode — Use bausteinsicht watch during development for automatic sync on every save.

  • Export diagrams — Use bausteinsicht export to generate PNG/SVG images for documentation.

Command Reference

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 (flags: --id, --kind, --title, --parent, --technology, --description)

bausteinsicht add relationship

Add relationship to model (flags: --from, --to, --label, --kind, --description)

bausteinsicht export

Export diagram views as PNG or SVG images (flags: --image-format png/svg, --view, --output, --embed-diagram)

bausteinsicht add view / bausteinsicht add specification

Create a view or extend the specification (LLM-friendly)

bausteinsicht export-diagram

Export views as C4 text diagrams: PlantUML, Mermaid, DOT, D2, HTML, or Structurizr DSL (--diagram-format)

bausteinsicht export-table

Export element attributes per view as an AsciiDoc or Markdown table (--table-format adoc|md)

bausteinsicht export-sequence

Export dynamic views as PlantUML or Mermaid sequence diagrams

bausteinsicht import

Import a model from Structurizr DSL or LikeC4 (--from structurizr|likec4)

bausteinsicht repl

Interactive shell for editing the model (add/remove/list/show/validate/undo/save)

bausteinsicht lint

Check the model against its architectural constraints

bausteinsicht health

Compute an architecture health score (completeness, conformance, complexity)

bausteinsicht graph

Analyse the relationship graph: cycles, centrality, dependency depth

bausteinsicht stale / bausteinsicht status / bausteinsicht find / bausteinsicht show

Inspect the model: flag stale elements, list by lifecycle status, full-text search, show one element

bausteinsicht snapshot / bausteinsicht diff / bausteinsicht changelog

Versioned snapshots, as-is/to-be comparison, and architecture changelog

bausteinsicht generate-template / bausteinsicht layout / bausteinsicht schema / bausteinsicht workspace / bausteinsicht overlay / bausteinsicht adr

Generate a template from the spec, lay out a diagram, generate the JSON Schema, merge multi-model workspaces, overlay metric heatmaps, and list ADRs

For the complete flag-by-flag reference of every command, see CLI Specification.

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
Note
 The --version flag is only available on the root command (bausteinsicht --version), not on subcommands.