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 two test-only helper packages). The complete map is in the Package Map below; the core engine is decomposed further in the Level 2 sections.

Building Blocks (core)

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

Export

container

Go

Diagram export to PNG and SVG formats via draw.io CLI

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

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 three (model, drawio, sync) 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 and LikeC4 (import)

internal/importer/ (structurizr/, likec4/)

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) and internal/benchmarks 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

Diagram export to PNG and SVG 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

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/                                       // 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.