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:

  • Elements: Customer (actor), Online Shop (system) with Frontend, REST API, and Database containers

  • Relationships: Customer uses Frontend, Frontend calls API, API reads/writes Database

  • Views: System Context, Container View, API Components

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)

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.