Skip to content

README.adoc

Latest commit

 

History

History
200 lines (147 loc) · 7.35 KB

README.adoc

File metadata and controls

200 lines (147 loc) · 7.35 KB

Bausteinsicht

Architecture-as-code tool with draw.io as visual frontend and bidirectional synchronization.

Define your architecture in a JSONC text file, and Bausteinsicht generates and updates draw.io diagrams automatically — in both directions.

System Context diagram generated by Bausteinsicht

Example: JSON in, diagram out

This JSONC model produces the diagram above:

{
  "specification": {
    "elements": {
      "actor":    { "notation": "Actor" },
      "system":   { "notation": "Software System", "container": true },
      "container": { "notation": "Container", "container": true }
    },
    "relationships": {
      "uses": { "notation": "uses" }
    }
  },
  "model": {
    "customer": { "kind": "actor", "title": "Customer" },
    "onlineshop": {
      "kind": "system", "title": "Online Shop",
      "children": {
        "frontend": { "kind": "container", "title": "Web Frontend", "technology": "React" },
        "api":      { "kind": "container", "title": "REST API", "technology": "Go" },
        "db":       { "kind": "container", "title": "Database", "technology": "PostgreSQL" }
      }
    }
  },
  "views": {
    "context":    { "title": "System Context", "include": ["customer", "onlineshop"] },
    "containers": { "title": "Container View", "scope": "onlineshop", "include": ["customer", "onlineshop.*"] }
  }
}

Jobs to be Done

Define architecture in text, get diagrams automatically — write a JSONC model and run bausteinsicht sync. See the Getting Started Tutorial.

Edit diagrams visually, keep the model in sync — move boxes in draw.io and sync changes back to JSON. See the Sync Specification.

Navigate multi-level views like a map — zoom into a system to see its containers, then into a container to see components. See the User Manual — Multi-View.

Let AI agents modify your architecture — every CLI command supports --format json for LLM-driven workflows. See the User Manual — LLM Workflows.

Installation

Binary Download (recommended)

Download the latest release for your platform from the Releases page.

# Linux (amd64)
curl -Lo bausteinsicht.tar.gz https://github.com/docToolchain/Bausteinsicht/releases/latest/download/bausteinsicht_linux_amd64.tar.gz
tar xzf bausteinsicht.tar.gz
sudo mv bausteinsicht /usr/local/bin/

# macOS (Apple Silicon)
curl -Lo bausteinsicht.tar.gz https://github.com/docToolchain/Bausteinsicht/releases/latest/download/bausteinsicht_darwin_arm64.tar.gz
tar xzf bausteinsicht.tar.gz
sudo mv bausteinsicht /usr/local/bin/

Go Install

Requires Go 1.25+:

go install github.com/docToolchain/Bausteinsicht/cmd/bausteinsicht@latest

Build from Source

git clone https://github.com/docToolchain/Bausteinsicht.git
cd Bausteinsicht
make build

Quick Start

# Initialize a sample project
mkdir my-architecture && cd my-architecture
bausteinsicht init

bausteinsicht init creates a sample JSONC model (architecture.jsonc) and a default template — everything you need to get started. Now run sync to generate diagrams:

bausteinsicht sync

Open architecture.drawio in draw.io to see the generated diagrams. Edit the JSONC model or the draw.io file and run sync again — changes flow in both directions.

For continuous sync on save, use watch mode:

bausteinsicht watch

See the Getting Started Tutorial for a step-by-step walkthrough, or browse the Online Shop example to see a complete model.

Features

  • Bidirectional sync — model → diagram and diagram → model

  • Watch mode — bausteinsicht watch for continuous sync on save

  • Multi-view — multiple diagram pages from one model (context, container, component views)

  • Scope & bounding boxes — visual boundaries around parent elements

  • Relationship lifting — connectors auto-lift to parent when endpoint is not on a view

  • CLI-first — all commands support --format json for LLM/AI agent workflows

  • JSON Schema — IDE autocompletion without plugins

Development

Devcontainer (recommended)

The .devcontainer/ provides a fully reproducible environment with all tools pre-installed. Works with VS Code Dev Containers, GitHub Codespaces, or the devcontainer CLI.

# Start the devcontainer
devcontainer up --workspace-folder .

# Run commands inside
devcontainer exec --workspace-folder . make check

Included tools: Go, staticcheck, gosec, nilaway, govulncheck, golangci-lint, gitleaks, draw.io (headless), Claude Code, human CLI, GitHub CLI.

Manual Setup

Requires Go 1.25+. Install analysis tools with:

make install-tools

Build & Test

make build          # build binary
make test           # run tests
make check          # all analysis tools + race-detected tests

Security

Bausteinsicht is a local CLI tool with no network access. See the Trust Model for details on trust boundaries and threat assessment.

For security findings and mitigations, see the Security Review.

Related Projects

Bausteinsicht is part of a growing ecosystem of architecture-as-code tools. If you are evaluating alternatives or want to understand the landscape, these projects are worth a look:

  • Structurizr — the original C4 model tooling by Simon Brown. Offers a dedicated DSL, a web-based renderer, and export to many formats. Source-of-truth is the DSL (no bidirectional sync with diagrams).

  • C4 model — the methodology behind the 4-level architecture abstraction (Context, Container, Component, Code). Bausteinsicht is C4-inspired but not limited to 4 fixed levels.

  • LikeC4 — a modern C4-inspired tool with a custom DSL, VS Code extension, and live web preview. Like Bausteinsicht, it supports user-defined element kinds and flexible nesting.

  • Isoflow — a visual-first architecture diagramming tool with an isometric rendering style. Focused on the visual editing experience rather than text-based modeling.

  • C4InterFlow — extends the C4 model with interface and flow concepts for documenting system interactions at a more granular level.

Bausteinsicht’s unique contribution is bidirectional synchronization between a text model (JSONC) and draw.io diagrams — edits in either direction are merged. See ADR-001 for a detailed comparison of DSL formats.

License

See LICENSE.