Quality Requirements

Quality Requirements Overview

Category (ISO 25010) Quality Requirement

Usability / Learnability

The tool and its DSL must be easy to learn for developers and architects. No prior knowledge of C4, Structurizr, or LikeC4 should be required.

Usability / Operability (IDE Support)

Editing the architecture model must be supported by IDE features (autocompletion, validation, hover docs) without installing tool-specific plugins.

Compatibility / Interoperability (LLM Friendliness)

The model format and CLI must be designed so that LLM agents can reliably read, write, and manipulate architecture models.

Functional Suitability / Correctness (Sync Reliability)

Bidirectional synchronization must never silently lose data. New elements, changed descriptions, and relationships must be correctly propagated in both directions.

Portability / Installability

The tool must be distributable as a single binary without runtime dependencies. Installation must not require package managers, virtual environments, or runtimes.

Maintainability / Modifiability (Flexible Hierarchy)

The element hierarchy must not be hardcoded to a fixed number of levels. Users must be able to define their own element kinds and nesting depth.

Quality Scenarios

QS-1: Learnability

Context

A developer unfamiliar with Bausteinsicht wants to create an architecture model for a new project.

Stimulus

The developer reads the getting-started documentation and opens their IDE.

Acceptance Criteria

Within 30 minutes, the developer has created a valid architecture model with at least 3 elements, 2 relationships, and 1 draw.io view — using only the documentation and IDE autocompletion.

Driven by: ADR-001 (JSON chosen for universal familiarity and IDE support).

QS-2: IDE Support

Context

An architect edits a .jsonc architecture model file in VS Code, IntelliJ, or Neovim.

Stimulus

The architect types a new element definition.

Acceptance Criteria

The editor provides autocompletion for property names, validates values against allowed types, and shows hover documentation for each field — without any Bausteinsicht-specific plugin installed. Only the JSON Schema association is required.

Driven by: ADR-001 (JSON Schema provides free IDE support via SchemaStore).

QS-3: LLM Friendliness

Context

An LLM agent (e.g., Claude) is asked to add a new microservice to an existing architecture model.

Stimulus

The agent reads the current model file and uses CLI commands.

Acceptance Criteria

The agent successfully adds the element with title, description, technology, and relationships, then runs bausteinsicht sync — all without human intervention and without producing invalid JSON.

Driven by: ADR-001 (JSON is the native output format of LLMs).

QS-4: Sync Reliability

Context

An architect modifies an element’s description in draw.io and adds a new element in the JSON model simultaneously.

Stimulus

bausteinsicht sync is executed.

Acceptance Criteria

The description change from draw.io is applied to the model. The new element from the model appears in the draw.io view. No data is silently lost. If a true conflict exists (same field changed in both), a warning is displayed.

QS-5: Installability

Context

A developer on macOS, Linux, or Windows wants to use Bausteinsicht.

Stimulus

The developer downloads the binary and runs bausteinsicht --version.

Acceptance Criteria

The tool runs immediately without installing Go, Python, Node.js, Java, or any other runtime. Total time from download to first successful command is under 1 minute.

Driven by: ADR-002 (Go chosen for single-binary distribution).

QS-6: Flexible Hierarchy

Context

An architect models a system where a component contains sub-components, which in turn contain further sub-components (3+ nesting levels beyond the C4 standard).

Stimulus

The architect defines deeply nested elements in the JSON model.

Acceptance Criteria

The model validates successfully. draw.io views correctly render all nesting levels. There is no artificial limit on hierarchy depth.