Use Cases

Actors

Actor Description

Software Architect

Primary user who maintains the architecture model and draw.io diagrams. Edits both the JSON DSL and draw.io visually.

Developer

Reads architecture diagrams in draw.io. May occasionally add elements or relationships in draw.io.

LLM Agent

AI assistant that manipulates the architecture model via CLI commands. Reads and writes JSON model files.

UC-1: Initialize Architecture Model

Description

A software architect creates a new architecture model for a project.

Preconditions

  • Bausteinsicht CLI is installed

  • A project directory exists

Flow

uc01 init

Postconditions

  • A valid JSON model file exists with specification and example content

  • A default draw.io template file exists

  • A .bausteinsicht-sync state file exists for change tracking

  • JSON Schema is referenced for IDE support

Error Scenarios

  • Model files already exist → Bausteinsicht warns and aborts (no overwrite)

UC-2: Define Architecture Elements

Description

A software architect adds elements (systems, containers, components) to the architecture model.

Preconditions

  • An initialized architecture model exists

  • IDE has JSON Schema support active

Flow

uc02 define elements

Postconditions

  • Model contains new elements with unique IDs

  • Relationships reference valid element IDs

Error Scenarios

  • Duplicate element ID → JSON Schema validation error in IDE

  • Relationship references non-existent element → validation warning on sync

UC-3: Generate draw.io Diagrams (Forward Sync)

Description

The architect generates or updates draw.io diagrams from the model.

Preconditions

  • A valid architecture model exists

  • A draw.io template exists

  • (Optional) Existing draw.io diagrams with manual layout

Flow

uc03 forward sync

Postconditions

  • draw.io file reflects current model state

  • Existing element positions are preserved

  • New elements are visually marked for manual positioning

  • Relationship connectors are attached to element centers

Error Scenarios

  • Invalid model → validation errors displayed, sync aborted (includes semantic validation)

  • Template file missing → error with instructions to create one

  • draw.io file missing or empty → automatically recreated from template (#149)

  • draw.io file locked by another process → warning

UC-4: Edit in draw.io and Reverse Sync

Description

An architect or developer edits elements in draw.io, and the changes are synced back to the model.

Preconditions

  • draw.io diagrams were previously generated from the model

  • Elements in draw.io carry Bausteinsicht IDs

Flow

uc04 reverse sync

Postconditions

  • Model reflects changes made in draw.io

  • New elements have IDs derived from their label (sanitized: lowercase, hyphen-separated)

  • New elements are assigned the first alphabetically-sorted kind from the specification

  • Elements with colliding IDs are skipped with a warning

  • Navigation buttons (nav-back-*) are ignored during reverse sync

  • Layout changes (element positions) do NOT modify the model

Error Scenarios

  • Element in draw.io has no ID and cannot be auto-matched → warning with manual resolution instructions

  • Generated ID collides with existing element → import skipped with warning (#203)

  • Conflicting changes in both model and draw.io → warning displayed, no silent overwrite

UC-5: Watch Mode

Description

Bausteinsicht continuously watches for file changes and synchronizes automatically.

Preconditions

  • An initialized architecture model exists

  • draw.io diagrams exist

Flow

uc05 watch

Postconditions

  • Model and draw.io diagrams are kept in sync continuously

Error Scenarios

  • Rapid successive changes → debounce to avoid conflicts

  • File watcher fails on network drives → fallback to polling with warning

UC-6: LLM-Driven Architecture Modification

Description

An LLM agent modifies the architecture model using CLI commands.

Preconditions

  • An initialized architecture model exists

  • LLM agent has access to the Bausteinsicht CLI

Flow

uc06 llm

Postconditions

  • Model is valid and updated

  • draw.io diagrams reflect the changes

  • New elements are marked for manual positioning

Error Scenarios

  • LLM generates invalid JSON → validate catches it before sync

  • LLM uses non-existent element ID in relationship → validation error

UC-7: Drill-Down Navigation

Description

An architect navigates between different abstraction levels within a single draw.io diagram using zoom-based drill-down.

Preconditions

  • Multiple views exist at different hierarchy levels

  • Views are placed on a single draw.io page with appropriate spacing

Flow

uc07 drilldown

Postconditions

  • User can navigate between abstraction levels via click

  • Parent views remain visible for orientation

Error Scenarios

  • Target view does not exist → element is not clickable (no link generated)

UC-8: Export Diagram Views

Description

A developer or CI pipeline exports diagram views as PNG or SVG images for use in documentation or reports.

Actors

  • Developer

  • CI pipeline

Preconditions

  • A synced architecture model exists with at least one view

  • draw.io CLI is available (headless via xvfb-run in CI environments)

Flow

uc08 export

Postconditions

  • Image files (PNG or SVG) exist for each exported view

  • File names correspond to view names

  • Exit code is 0 on success

Error Scenarios

  • View name not found → exit code 2, error message mentions "view not found"

  • draw.io CLI not available → error with installation instructions

  • Output directory not writable → error with path information