ArchitectureAsCode
- Part 1: What is Architecture-as-Code — and what makes Bausteinsicht different?
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.
- Part 2: From Zero to Your First Architecture Diagram with Bausteinsicht
Install Bausteinsicht, initialize a project, generate the first diagram, and synchronize in both directions — in under 10 minutes.
- Part 3: The Bausteinsicht JSONC Data Model in Detail
All fields and sections of the Bausteinsicht data model: specification, model, views, relationships, and optional extensions such as asIs/toBe, dynamicViews, and constraints.
- Part 4: Bidirectional Synchronization — How draw.io and JSONC Stay in Sync
How the Bausteinsicht sync algorithm works: forward sync, reverse sync, conflict resolution, relationship lifting, and the .bausteinsicht-sync state file.
- Part 5: Multi-View — Multiple Diagram Perspectives from One Model
How Bausteinsicht generates multiple diagram perspectives (Context, Container, Component) from a single model — with scope bounding boxes, drill-down links, and back navigation.
- Part 6: Export Features — Mermaid, Structurizr DSL, PNG and More
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.
- Part 7: Snapshots & Changelog — Versioning Architecture Over Time
Capture, compare, and restore architecture states with bausteinsicht snapshot — plus changelog for generating an automatic architecture changelog from Git history.
- Part 8: Validation & Linting — Automatically Enforcing Architecture Rules
Define architecture rules as machine-checkable constraints and automatically enforce them in the CI pipeline with bausteinsicht lint + health.
- Part 9: LSP Integration — Autocompletion in the Editor
bausteinsicht-lsp brings inline validation, error messages, and CodeLens directly into VS Code — plus JSON Schema as a lightweight alternative without LSP setup.
- Part 10: LLM/AI Workflows — AI-Assisted Architecture Modeling
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.
- Part 11: ADR Integration — Linking Architecture Decision Records to the Model
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.
- Part 12: Overlay & Heatmap — Overlaying Metrics onto Architecture Diagrams
Overlay external metrics like error rate, coverage, or latency as a heatmap onto draw.io elements — and remove them again with a single command.
- Part 13: Graph Analysis — Uncovering Cycles and Dependencies
bausteinsicht graph analyzes the dependency graph: detect cycles, calculate centrality metrics, identify strongly connected components.
- Part 14: Auto-Layout — Automatically Arranging Diagrams
bausteinsicht layout calculates hierarchical auto-layout for draw.io diagrams — with pinning for elements that should remain manually positioned.
- Part 15: Templates — Defining Custom Visual Styles
bausteinsicht generate-template creates a draw.io template file with visual styles for all element types — in four presets: default, c4, minimal, dark.
- Part 16: Workspace — Combining Multiple Architecture Models
Combining multiple team models with a workspace.jsonc: workspace merge, validate and list — plus cross-model relationships between subsystems.
- Part 17: Sequence Diagrams — Exporting Dynamic Views as PlantUML and Mermaid
Define dynamic views in architecture.jsonc and export them as PlantUML or Mermaid sequence diagrams using bausteinsicht export-sequence.
- Part 18: CLI Modeling — Building Architecture Directly from the Command Line
Add elements, relationships, views, and specification types directly to the model via the command line — without manually editing the JSONC file.
- Part 19: Health Score — Rating Architecture Quality with A–F Grades
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.
- Part 20: Element Lifecycle — Tracking Status from proposed to archived
The status field in Bausteinsicht elements: managing proposed through archived in the model, filtering with bausteinsicht status, and evaluating results in the Health Score.
- Part 21: As-Is / To-Be — Defining the Target Architecture Directly in the Model
asIs and toBe sections in architecture.jsonc for migration planning — and bausteinsicht diff for an annotated comparison of the current and target architecture.
- Part 22: find & show — Navigating the Model and Exploring Elements
bausteinsicht find searches the model by free text — bausteinsicht show displays all details of an element including relationships and views.
- Part 23: Tags & View Filtering — Organizing Elements and Populating Views Precisely
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.
- Part 24: CI/CD Integration — validate, diff, and Export in GitHub Actions
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.
- Part 25: Migration — From draw.io, PlantUML, and Structurizr to Bausteinsicht
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.
- Part 26: Team Workflows — Merge Conflicts, Ownership, and Architecture Reviews in PRs
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.
- Part 27: Custom Notations — Custom Element Types, Shapes, and Domain Languages
Beyond C4: defining custom element types with custom shapes in draw.io — using an AUTOSAR notation and an embedded hardware notation as examples.
- Part 28: Performance with Large Models — Scoping, Partial Views, and Subsystems
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.
- Part 29: Real-Life Example — Structurizr Big Bank with bausteinsicht import
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.
- Part 30: More Views from One Model — Focused Diagrams per Audience
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.