Bausteinsicht Tutorial

Architecture documentation goes stale faster than code. Architecture-as-Code is the attempt to change that — and Bausteinsicht solves the problem in a way other tools cannot.

Install Bausteinsicht, initialize a project, generate the first diagram, and synchronize in both directions — in under 10 minutes.

All fields and sections of the Bausteinsicht data model: specification, model, views, relationships, and optional extensions such as asIs/toBe, dynamicViews, and constraints.

How the Bausteinsicht sync algorithm works: forward sync, reverse sync, conflict resolution, relationship lifting, and the .bausteinsicht-sync state file.

How Bausteinsicht generates multiple diagram perspectives (Context, Container, Component) from a single model — with scope bounding boxes, drill-down links, and back navigation.

Bausteinsicht as an export hub: PNG/SVG via draw.io CLI, PlantUML, Mermaid C4, DOT, D2, HTML5, Structurizr DSL, AsciiDoc/Markdown tables, and sequence diagrams.

Capture, compare, and restore architecture states with bausteinsicht snapshot — plus changelog for generating an automatic architecture changelog from Git history.

Define architecture rules as machine-checkable constraints and automatically enforce them in the CI pipeline with bausteinsicht lint + health.

bausteinsicht-lsp brings inline validation, error messages, and CodeLens directly into VS Code — plus JSON Schema as a lightweight alternative without LSP setup.

Bausteinsicht as an LLM-friendly CLI: --format json for machine-readable output, bausteinsicht find and status as context providers for AI assistants like Claude Code.

Link Architecture Decision Records directly to the Bausteinsicht model: define ADRs in the specification, attach them to elements and relationships, and navigate them with bausteinsicht adr list/show.

Overlay external metrics like error rate, coverage, or latency as a heatmap onto draw.io elements — and remove them again with a single command.

bausteinsicht graph analyzes the dependency graph: detect cycles, calculate centrality metrics, identify strongly connected components.

bausteinsicht layout calculates hierarchical auto-layout for draw.io diagrams — with pinning for elements that should remain manually positioned.

bausteinsicht generate-template creates a draw.io template file with visual styles for all element types — in four presets: default, c4, minimal, dark.

Combining multiple team models with a workspace.jsonc: workspace merge, validate and list — plus cross-model relationships between subsystems.

Define dynamic views in architecture.jsonc and export them as PlantUML or Mermaid sequence diagrams using bausteinsicht export-sequence.

Add elements, relationships, views, and specification types directly to the model via the command line — without manually editing the JSONC file.

bausteinsicht health evaluates the architecture in five categories and produces a score from 0–100 plus a grade from A+ to F — for dashboards, PRs, and architecture reviews.

The status field in Bausteinsicht elements: managing proposed through archived in the model, filtering with bausteinsicht status, and evaluating results in the Health Score.

asIs and toBe sections in architecture.jsonc for migration planning — and bausteinsicht diff for an annotated comparison of the current and target architecture.

bausteinsicht find searches the model by free text — bausteinsicht show displays all details of an element including relationships and views.

Define tags in specification.tags, assign them to elements, and populate views precisely with filter-tags and exclude-tags — without listing every element individually in include.

Bausteinsicht in GitHub Actions: validate as a build gate, diff as a PR comment, and automatic SVG export — with complete workflow YAMLs ready to copy-paste.

Migrating existing architecture documentation to Bausteinsicht: what works automatically for draw.io, PlantUML C4, and Structurizr, what needs to be transferred manually, and why a view-by-view strategy works better than a big bang.

Multiple people on the same model: which parts of the JSONC are merge-friendly, how ownership conventions prevent conflicts, and what an architecture review looks like in a pull request.

Beyond C4: defining custom element types with custom shapes in draw.io — using an AUTOSAR notation and an embedded hardware notation as examples.

Bausteinsicht with 50+ elements: when you need focused views instead of an overview, how to split a grown model into subsystems, and when the Workspace feature is the right solution.

Migrating the Big Bank Example by Simon Brown (Structurizr) to Bausteinsicht in three steps — using bausteinsicht import --from structurizr, a full walkthrough of the generated JSONC, and the visual result.

The same JSONC model, seven different diagrams: how to generate focused views for the security team, mobile developers, and stakeholders from a single Big Bank model — without duplicating the model.