Building Block View

Level 1: Overall System

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

Motivation

The system decomposes into four internal packages plus a thin CLI layer. The key separation is between model (JSON world) and drawio (XML world), with sync as the mediator. This ensures changes to one format never leak into the other package.

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

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, state, templates) → Result

Executes one full bidirectional sync cycle. Returns a result 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.

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 following directory structure maps directly to the building blocks above:

bausteinsicht/
├── cmd/
│   └── bausteinsicht/
│       ├── main.go              // Entry point
│       ├── root.go              // Root command, global flags
│       ├── init.go              // bausteinsicht init
│       ├── sync.go              // bausteinsicht sync
│       ├── validate.go          // bausteinsicht validate
│       ├── watch.go             // bausteinsicht watch
│       ├── add_element.go       // bausteinsicht add element
│       └── add_relationship.go  // bausteinsicht add relationship
├── internal/
│   ├── model/
│   │   ├── types.go             // BausteinsichtModel, Element, ...
│   │   ├── loader.go            // JSONC read/write
│   │   ├── resolve.go           // ID resolution, wildcards
│   │   └── validate.go          // Model validation
│   ├── drawio/
│   │   ├── document.go          // mxfile/diagram parsing
│   │   ├── element.go           // <object> + <mxCell> CRUD
│   │   ├── connector.go         // Edge/connector CRUD
│   │   ├── template.go          // Template loading
│   │   └── label.go             // HTML label gen/parse
│   ├── sync/
│   │   ├── engine.go            // Main sync orchestration
│   │   ├── forward.go           // Model → draw.io
│   │   ├── reverse.go           // draw.io → Model
│   │   ├── state.go             // .bausteinsicht-sync I/O
│   │   ├── diff.go              // Change detection
│   │   └── conflict.go          // Conflict resolution
│   └── watcher/
│       └── watcher.go           // fsnotify file watcher
├── go.mod
└── go.sum

Conventions

  • cmd/bausteinsicht/ contains only CLI wiring — no business logic

  • internal/ ensures packages cannot be imported by external code

  • Each package has a clear single responsibility

  • Cross-package dependencies flow inward: cmd → sync → model + drawio

  • The model and drawio packages never depend on each other