Building Block View

Level 1: Overall System

Container View
Figure 1. Container View (generated from architecture model)

Motivation

At the centre sits a small core engine — model (the JSONC world), drawio (the XML world), and sync as the mediator between them, so changes to one format never leak into the other package. Around this core, a set of feature packages add analysis, evolution, interop, and styling, and a thin CLI layer (cmd/bausteinsicht) wires commands to them. A second binary (cmd/bausteinsicht-lsp) reuses the same library code to serve editors over the Language Server Protocol.

In total the system is two binaries over ~23 production packages (plus three test-only helper packages). The complete map is in the Package Map below; the core engine and the CLI layer are decomposed further in the Level 2 sections.

Building Blocks (core)

Element Kind Technology Description

Changelog

container

Go

Architecture changelog generation between two git refs

CLI

container

Go / Cobra

Command-line interface providing validate, sync, export, and watch commands

Constraints

container

Go

Validation constraints for model linting and consistency checking

Diagram

container

Go

Text-based diagram export to Mermaid C4 and PlantUML formats with markdown wrapping

Diff

container

Go

As-is vs. to-be architecture comparison

draw.io

container

Go / etree

draw.io XML document handling — elements, connectors, templates, and labels

Export

container

Go

Export diagrams to PNG, SVG, and other visual formats via draw.io CLI

Exporter

container

Go

Architecture export to Structurizr DSL and other formats

Graph

container

Go

Relationship graph analysis — cycle detection and dependency depth

Health

container

Go

Architecture health scoring — completeness, conformance, and complexity

Importer

container

Go

Import architecture from Structurizr DSL, LikeC4, and XMI/Enterprise Architect formats

Layout

container

Go

Auto-layout algorithms for positioning elements in draw.io diagrams

Language Server

container

Go

Language Server Protocol implementation for VS Code and other editors

Model

container

Go

JSONC architecture model management — loading, validation, and mutation

Overlay

container

Go

Metric heatmap overlay application and removal on draw.io diagrams

Schema

container

Go

JSON Schema generation from Go model types for IDE autocompletion

Search

container

Go

Element and relationship search with filtering and pattern matching

Snapshot

container

Go

Versioned architecture snapshot storage and restore

Stale

container

Go

Detects unused or forgotten architecture elements via git history and ADR/status metadata

Sync Engine

container

Go

Bidirectional synchronization engine between JSONC model and draw.io diagrams

Table

container

Go

Export architecture to CSV and Markdown table formats

Template

container

Go

draw.io template generation from element specification (shapes, layout)

Watcher

container

Go / fsnotify

File system monitoring for automatic sync on model or diagram changes

Workspace

container

Go

Multi-model workspace configuration loading and merging

Developer

actor

Developer using the Bausteinsicht CLI to manage architecture models

draw.io App

external_system

draw.io desktop or web application for visual diagram editing

IDE

external_system

IDE with JSON Schema support for JSONC editing with autocompletion

Important Interfaces

Interface Description

model.Load(path) → BausteinsichtModel

Parses a JSONC file into the Go model struct. Validates against schema constraints.

model.Save(path, BausteinsichtModel)

Writes the model back to JSONC, preserving comments where possible.

drawio.LoadDocument(path) → Document

Parses a draw.io XML file into a manipulable document structure.

drawio.SaveDocument(path, Document)

Writes the document back to uncompressed draw.io XML.

drawio.LoadTemplate(path) → TemplateSet

Reads a template file and extracts styles keyed by bausteinsicht_template kind.

sync.Run(model, document, lastState, templates, newPageIDs, …​opts) → *SyncResult

Executes one full bidirectional sync cycle — a pure function with no I/O. newPageIDs marks pages created in this run (so their elements are not mistaken for deletions); opts are optional ForwardOptions (e.g. relayout). Returns a SyncResult describing all changes and conflicts.

sync.LoadState(path) → SyncState

Reads the .bausteinsicht-sync state file.

sync.SaveState(path, SyncState)

Writes the updated sync state after successful sync.

Package Map (all building blocks)

Every production package, grouped by role. Each row is a Level-1 building block: its responsibility and its source location. The core engine (model, drawio, sync) and the CLI layer (cli) are decomposed further in the Level 2 sections below.

Table 1. Core engine
Package Responsibility Source

model

DSL types, JSONC loader (comment-preserving patch + full save), validation, ID/wildcard resolution

internal/model/

drawio

Read/write draw.io XML: document, element, connector, template, HTML label

internal/drawio/

sync

Bidirectional sync: diff, forward/reverse apply, conflict resolution, state, layout, badges, metadata

internal/sync/

watcher

fsnotify file watcher driving --watch mode (300 ms debounce)

internal/watcher/
Table 2. Analysis
Package Responsibility Source

constraints

Evaluate architectural rules from the model (lint)

internal/constraints/

graph

Relationship-graph analysis: cycles, dependency depth, centrality (graph)

internal/graph/

health

Architecture health score across weighted categories (health)

internal/health/

stale

Detect unused/forgotten elements, using git history (stale)

internal/stale/

search

Full-text search over elements, relationships, views (find)

internal/search/

workspace

Group, merge, and validate multiple models together as one workspace (workspace)

internal/workspace/
Table 3. Evolution
Package Responsibility Source

snapshot

Versioned model captures, semantically diffable (snapshot)

internal/snapshot/

diff

As-is vs. to-be model comparison (diff)

internal/diff/

changelog

Architecture changelog between two git points (changelog)

internal/changelog/
Table 4. Layout & styling
Package Responsibility Source

layout

Hierarchical auto-layout engine (layout, sync --relayout)

internal/layout/

template

Generate a draw.io template from the specification (generate-template)

internal/template/

overlay

Apply/remove metric heatmap overlays on diagrams (overlay)

internal/overlay/
Table 5. Interop & export
Package Responsibility Source

importer

Import models from Structurizr DSL, LikeC4, and XMI/Enterprise Architect (import). The XMI sub-package buffers the entire file in memory and converts Windows-1252 to UTF-8 before parsing, so peak RSS is ~2× the raw file size (e.g. ~230 MB for a 114 MB AUTOSAR export); a 200 MB read cap is enforced.

internal/importer/ (structurizr/, likec4/, xmi/)

exporter

Export the model as Structurizr DSL

internal/exporter/structurizr/

diagram

Render views as text diagrams: C4-PlantUML, Mermaid, DOT, D2, HTML, sequence (export-diagram, export-sequence)

internal/diagram/

table

Render element attributes as AsciiDoc/Markdown tables (export-table)

internal/table/

export

Export diagram pages to PNG/SVG via headless draw.io (export)

internal/export/

schema

Generate the JSON Schema from the Go model types (schema)

internal/schema/
Table 6. IDE integration
Package Responsibility Source

lsp

Language Server Protocol server: diagnostics, code lenses; backs the cmd/bausteinsicht-lsp binary and the VS Code extension

internal/lsp/
Note
 internal/chaos (fault-injection helper), internal/benchmarks, and internal/e2eplan (the e2e-test-plan report generator’s plan-ID registry, see #519) are test-only utilities, not production building blocks.

Level 2: Sync Engine

The sync engine is the most complex package. It decomposes into five sub-components.

Sync Engine Components
Figure 2. Sync Engine Components (generated from architecture model via draw.io export)

Building Blocks

Element Kind Technology Description

CLI

container

Go / Cobra

Command-line interface providing validate, sync, export, and watch commands

draw.io

container

Go / etree

draw.io XML document handling — elements, connectors, templates, and labels

Model

container

Go

JSONC architecture model management — loading, validation, and mutation

Conflict

component

Go

Conflict detection and resolution when both model and diagram changed

Diff

component

Go

Three-way change detection comparing model, diagram, and last-sync state

Engine

component

Go

Main sync orchestrator coordinating diff, forward, reverse, and conflict resolution

Forward Sync

component

Go

Applies model changes to draw.io diagrams (model → drawio)

Reverse Sync

component

Go

Applies draw.io changes back to the JSONC model (drawio → model)

State

component

Go

Sync state persistence using SHA256 hashes for change detection

Watcher

container

Go / fsnotify

File system monitoring for automatic sync on model or diagram changes

Level 2: DrawIO Package

The draw.io package handles all mxGraph XML concerns.

draw.io Package Components
Figure 3. draw.io Package Components (generated from architecture model via draw.io export)

Building Blocks

Element Kind Technology Description

Connector

component

Go

Connector/relationship CRUD for edges between elements

Document

component

Go

XML parsing, page management, and file I/O for .drawio files

Element

component

Go

Element CRUD operations on mxGraphModel objects and mxCells

Label

component

Go

HTML label generation and parsing for element display text

Template

component

Go

Template loading and style lookup from .drawio template files

Export

container

Go

Export diagrams to PNG, SVG, and other visual formats via draw.io CLI

Sync Engine

container

Go

Bidirectional synchronization engine between JSONC model and draw.io diagrams

draw.io App

external_system

draw.io desktop or web application for visual diagram editing

Level 2: Model Package

Model Package Components
Figure 4. Model Package Components (generated from architecture model via draw.io export)

Building Blocks

Element Kind Technology Description

CLI

container

Go / Cobra

Command-line interface providing validate, sync, export, and watch commands

Loader

component

Go

JSONC read/write with comment stripping and trailing comma handling

Patch

component

Go

Comment-preserving JSONC mutations for reverse sync

Resolve

component

Go

Dot-notation element resolution and wildcard pattern matching

Types

component

Go

Core struct definitions for elements, relationships, views, and specification

Validate

component

Go

Model validation rules for elements, relationships, and views

Sync Engine

container

Go

Bidirectional synchronization engine between JSONC model and draw.io diagrams

IDE

external_system

IDE with JSON Schema support for JSONC editing with autocompletion

Level 2: CLI Package

The CLI is the thinnest layer (no business logic — see Conventions below), but at 41 files across ~15 subcommands it’s grouped into 7 components by concern rather than one component per file, for the same reason `model’s 7 files map to 5 components above: file-level granularity would be noise at this diagram’s zoom level.

CLI Package Components
Figure 5. CLI Package Components (generated from architecture model via draw.io export)

Building Blocks

Element Kind Technology Description

Add

component

Go

Add element/relationship/view/specification/pattern subcommands

Analysis

component

Go

find, show, status, stale, health, graph, and lint subcommands

Core

component

Go

Root command wiring, init, sync, validate, watch, and template resolution

Evolution

component

Go

snapshot (save/list/diff/restore/delete), diff, and changelog subcommands

Export Commands

component

Go

export, export-diagram, export-table, and export-sequence subcommands

Interactive

component

Go

repl, overlay, and adr subcommands

Tooling

component

Go

import, generate-template, layout, schema, and workspace subcommands

Model

container

Go

JSONC architecture model management — loading, validation, and mutation

Sync Engine

container

Go

Bidirectional synchronization engine between JSONC model and draw.io diagrams

Watcher

container

Go / fsnotify

File system monitoring for automatic sync on model or diagram changes

Level 2: Diagram Package Components

Text-based diagram export components (Mermaid C4, PlantUML) and markdown wrapping.

Diagram Package Components
Figure 6. Diagram Package Components (generated from architecture model via draw.io export)

Building Blocks

Element Kind Technology Description

CLI

container

Go / Cobra

Command-line interface providing validate, sync, export, and watch commands

Markdown

component

Go

Markdown document wrapper for multiple diagram pages

Mermaid C4

component

Go

Mermaid C4 diagram generation with C4 level detection

Model

container

Go

JSONC architecture model management — loading, validation, and mutation

Level 2: Importer Package Components

Import components for Structurizr DSL and LikeC4 format conversion to Bausteinsicht model.

Importer Package Components
Figure 7. Importer Package Components (generated from architecture model via draw.io export)

Building Blocks

Element Kind Technology Description

CLI

container

Go / Cobra

Command-line interface providing validate, sync, export, and watch commands

LikeC4

component

Go

LikeC4 DSL parsing and model conversion

Structurizr

component

Go

Structurizr DSL parsing and model conversion

XMI

component

Go

XMI/Enterprise Architect parsing and model conversion. Buffers the whole file in memory and converts Windows-1252 to UTF-8 before parsing (peak RSS ~2x file size); a 200MB read cap is enforced.

Model

container

Go

JSONC architecture model management — loading, validation, and mutation

Level 2: Exporter Package Components

Export components for converting Bausteinsicht model to external formats (Structurizr DSL).

Exporter Package Components
Figure 8. Exporter Package Components (generated from architecture model via draw.io export)

Building Blocks

Element Kind Technology Description

CLI

container

Go / Cobra

Command-line interface providing validate, sync, export, and watch commands

Structurizr

component

Go

Structurizr DSL export with smart variable naming

Model

container

Go

JSONC architecture model management — loading, validation, and mutation

Level 2: Search Package Components

Element and relationship search with pattern matching and filtering.

Search Package Components
Figure 9. Search Package Components (generated from architecture model via draw.io export)

Building Blocks

Element Kind Technology Description

CLI

container

Go / Cobra

Command-line interface providing validate, sync, export, and watch commands

Model

container

Go

JSONC architecture model management — loading, validation, and mutation

Search

container

Go

Element and relationship search with filtering and pattern matching

Go Package Layout

The directory structure maps directly to the building blocks above (packages, not every file):

bausteinsicht/
├── cmd/
│   ├── bausteinsicht/      // main CLI — one file per command (init, sync, add, repl, export*, …)
│   └── bausteinsicht-lsp/  // Language Server Protocol binary
├── internal/
│   ├── model/  drawio/  sync/  watcher/                          // core engine
│   ├── constraints/  graph/  health/  stale/  search/            // analysis
│   ├── snapshot/  diff/  changelog/                              // evolution
│   ├── layout/  template/  overlay/                              // layout & styling
│   ├── importer/  exporter/  diagram/  table/  export/  schema/  // interop & export
│   ├── lsp/                                                      // IDE integration
│   └── chaos/  benchmarks/  e2eplan/                              // test-only helpers
├── go.mod
└── go.sum

Conventions

  • cmd/bausteinsicht/ contains only CLI wiring — no business logic; all logic lives in internal/ packages (so the LSP binary can reuse it).

  • internal/ ensures packages cannot be imported by external code.

  • Each package has a clear single responsibility (see the Package Map).

  • Cross-package dependencies flow inward toward the core: cmd → feature packages → sync → model + drawio.

  • The model and drawio packages never depend on each other — sync is the only mediator.

  • chaos and benchmarks are imported only from _test.go files, so production code never depends on them. e2eplan is imported by the standalone scripts/e2e-test-report-gen tool (not a _test.go file, but also not shipped in the bausteinsicht/bausteinsicht-lsp binaries).