Quality Requirements

Quality Requirements Overview

ISO 25010 Characteristic	Quality Requirement	Top-goal link
Usability / Learnability	New users productive within 30 minutes using only docs and IDE autocompletion	Concretises QG-1 (Learnability)
Usability / Operability	IDE autocompletion, validation, hover docs without tool-specific plugin	Concretises QG-2 (IDE Support)
Compatibility / Interoperability	LLM agents can reliably read, write, and manipulate architecture models	Concretises QG-3 (LLM Friendliness)
Functional Suitability / Correctness	Bidirectional sync never silently loses data	Derived (sync reliability enables QG-1–3)
Portability / Installability	Single binary, no runtime dependencies, install in under 1 minute	Derived (prerequisite for all three top goals)
Maintainability / Modifiability	Element hierarchy freely configurable, not hardcoded to C4 levels	Derived (enables diverse team adoption)
Performance Efficiency	10 MB JSONC model processed in under 5 seconds on commodity hardware	Derived (blocks usability at scale)
Reliability / Fault Tolerance	Corrupt or oversized input never corrupts the model file	Derived (trust prerequisite for QG-1)
Security	Path traversal via CLI flags rejected; model files written at 0600	Derived (operating in shared workspaces)

ISO 25010 Characteristic

Quality Requirement

Top-goal link

Usability / Learnability

New users productive within 30 minutes using only docs and IDE autocompletion

Concretises QG-1 (Learnability)

Usability / Operability

IDE autocompletion, validation, hover docs without tool-specific plugin

Concretises QG-2 (IDE Support)

Compatibility / Interoperability

LLM agents can reliably read, write, and manipulate architecture models

Concretises QG-3 (LLM Friendliness)

Functional Suitability / Correctness

Bidirectional sync never silently loses data

Derived (sync reliability enables QG-1–3)

Portability / Installability

Single binary, no runtime dependencies, install in under 1 minute

Derived (prerequisite for all three top goals)

Maintainability / Modifiability

Element hierarchy freely configurable, not hardcoded to C4 levels

Derived (enables diverse team adoption)

Performance Efficiency

10 MB JSONC model processed in under 5 seconds on commodity hardware

Derived (blocks usability at scale)

Reliability / Fault Tolerance

Corrupt or oversized input never corrupts the model file

Derived (trust prerequisite for QG-1)

Security

Path traversal via CLI flags rejected; model files written at 0600

Derived (operating in shared workspaces)

Quality Scenarios

The six-part scenario form used below: Source → Stimulus → Artifact → Environment → Response → Response Measure

QS-1: Learnability

Source	Developer unfamiliar with Bausteinsicht, first contact with the project
Stimulus	Reads the getting-started documentation and opens their IDE
Artifact	Bausteinsicht CLI + JSON Schema + user manual
Environment	Normal developer workstation; IDE with JSON Schema support (VS Code, IntelliJ, or Neovim)
Response	Developer creates and validates an architecture model using IDE autocompletion
Response Measure	Within 30 minutes, the developer has created a valid model with ≥3 elements, ≥2 relationships, and ≥1 draw.io view — using only documentation and IDE features, no Bausteinsicht-specific help

Source

Developer unfamiliar with Bausteinsicht, first contact with the project

Stimulus

Reads the getting-started documentation and opens their IDE

Artifact

Bausteinsicht CLI + JSON Schema + user manual

Environment

Normal developer workstation; IDE with JSON Schema support (VS Code, IntelliJ, or Neovim)

Response

Developer creates and validates an architecture model using IDE autocompletion

Response Measure

Within 30 minutes, the developer has created a valid model with ≥3 elements, ≥2 relationships, and ≥1 draw.io view — using only documentation and IDE features, no Bausteinsicht-specific help

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

QS-2: IDE Support

Source Architect editing a .jsonc model file

Source	Architect editing a `.jsonc` model file
Stimulus	Types a new element definition
Artifact	`.jsonc` model file with `$schema` reference
Environment	VS Code, IntelliJ, or Neovim with JSON Schema plugin; no Bausteinsicht plugin installed
Response	Editor shows autocompletion for property names, validates values, and displays hover documentation
Response Measure	0 additional plugins installed beyond JSON Schema association; all three named IDEs provide autocompletion and validation

Stimulus

Types a new element definition

Artifact

.jsonc model file with $schema reference

Environment

VS Code, IntelliJ, or Neovim with JSON Schema plugin; no Bausteinsicht plugin installed

Response

Editor shows autocompletion for property names, validates values, and displays hover documentation

Response Measure

0 additional plugins installed beyond JSON Schema association; all three named IDEs provide autocompletion and validation

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

QS-3: LLM Friendliness

Source LLM agent (e.g., Claude Code)

Source	LLM agent (e.g., Claude Code)
Stimulus	Instructed to add a new microservice to an existing architecture model
Artifact	JSONC model file + Bausteinsicht CLI
Environment	Automated agent workflow; no human at the keyboard
Response	Agent reads the model, issues `bausteinsicht add element` and `add relationship` commands, then runs `bausteinsicht sync`
Response Measure	0 human interventions required; model remains valid JSON after agent edits; `bausteinsicht validate` reports no new errors

Stimulus

Instructed to add a new microservice to an existing architecture model

Artifact

JSONC model file + Bausteinsicht CLI

Environment

Automated agent workflow; no human at the keyboard

Response

Agent reads the model, issues bausteinsicht add element and add relationship commands, then runs bausteinsicht sync

Response Measure

0 human interventions required; model remains valid JSON after agent edits; bausteinsicht validate reports no new errors

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

QS-4: Sync Reliability

Source Architect (working in draw.io) and developer (working in JSONC) simultaneously

Source	Architect (working in draw.io) and developer (working in JSONC) simultaneously
Stimulus	`bausteinsicht sync` is executed after both sides made changes
Artifact	JSONC model file + draw.io diagram + `.bausteinsicht-sync` state
Environment	Normal development workflow; no true data conflict (different fields changed)
Response	Description change from draw.io is written to the model; new element from the model appears in the draw.io view; conflicts (same field changed on both sides) produce a warning and model wins
Response Measure	0 silent data losses; every changed field appears in the correct destination; conflicts logged to stderr with element ID and field name

Stimulus

bausteinsicht sync is executed after both sides made changes

Artifact

JSONC model file + draw.io diagram + .bausteinsicht-sync state

Environment

Normal development workflow; no true data conflict (different fields changed)

Response

Description change from draw.io is written to the model; new element from the model appears in the draw.io view; conflicts (same field changed on both sides) produce a warning and model wins

Response Measure

0 silent data losses; every changed field appears in the correct destination; conflicts logged to stderr with element ID and field name

Derived from reliability requirement (trust prerequisite for all top goals).

QS-5: Installability

Source Developer on macOS, Linux, or Windows

Source	Developer on macOS, Linux, or Windows
Stimulus	Downloads the binary from a GitHub Release and runs `bausteinsicht --version`
Artifact	Released binary (goreleaser cross-compiled archive)
Environment	Clean workstation; no Go, Python, Node.js, Java, or other runtime installed
Response	Command executes and prints the version string
Response Measure	Under 1 minute from download to first successful command; 0 runtime dependencies required

Stimulus

Downloads the binary from a GitHub Release and runs bausteinsicht --version

Artifact

Released binary (goreleaser cross-compiled archive)

Environment

Clean workstation; no Go, Python, Node.js, Java, or other runtime installed

Response

Command executes and prints the version string

Response Measure

Under 1 minute from download to first successful command; 0 runtime dependencies required

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

QS-6: Flexible Hierarchy

Source Architect modeling a system with deep nesting (e.g., domain → subdomain → system → service → component)

Source	Architect modeling a system with deep nesting (e.g., domain → subdomain → system → service → component)
Stimulus	Defines elements nested 4–49 levels deep in the JSON model
Artifact	JSONC model file
Environment	Normal model editing; `bausteinsicht validate` or `bausteinsicht sync`
Response	Model validates and renders correctly for all depths up to the enforced limit
Response Measure	Nesting depths 1–49 succeed without error; depth 50 returns a clear error message naming the offending element path (enforced by `MaxElementDepth=50` in `internal/model/resolve.go`, introduced as SEC-007 to prevent stack-overflow DoS)

Stimulus

Defines elements nested 4–49 levels deep in the JSON model

Artifact

JSONC model file

Environment

Normal model editing; bausteinsicht validate or bausteinsicht sync

Response

Model validates and renders correctly for all depths up to the enforced limit

Response Measure

Nesting depths 1–49 succeed without error; depth 50 returns a clear error message naming the offending element path (enforced by MaxElementDepth=50 in internal/model/resolve.go, introduced as SEC-007 to prevent stack-overflow DoS)

Note	Prior versions of this document stated "no artificial limit on hierarchy depth." This was corrected in the 2026-06-27 audit. A depth of 50 covers all realistic C4 and custom hierarchy depths while preventing denial-of-service (see SEC-007).

Driven by: ADR-001 (flexible element kinds).

QS-7: Performance at Scale

Source Developer with a large monolith model

Source	Developer with a large monolith model
Stimulus	Runs `bausteinsicht sync` on a JSONC model with 500+ elements and a 10 MB file
Artifact	JSONC model + draw.io diagram
Environment	Commodity developer laptop (≥4 cores, ≥8 GB RAM); no external network dependency
Response	Sync completes without timeout or OOM
Response Measure	Sync finishes in under 5 seconds wall time; benchmarks in `internal/benchmarks/` enforce regression detection in CI

Stimulus

Runs bausteinsicht sync on a JSONC model with 500+ elements and a 10 MB file

Artifact

JSONC model + draw.io diagram

Environment

Commodity developer laptop (≥4 cores, ≥8 GB RAM); no external network dependency

Response

Sync completes without timeout or OOM

Response Measure

Sync finishes in under 5 seconds wall time; benchmarks in internal/benchmarks/ enforce regression detection in CI

Derived from performance efficiency requirement.

QS-8: Reliability Under Bad Input

Source Attacker or misconfigured tool writing a corrupt/oversized JSONC file to the model path

Source	Attacker or misconfigured tool writing a corrupt/oversized JSONC file to the model path
Stimulus	`bausteinsicht sync` is invoked with a 50 MB malformed JSONC file
Artifact	JSONC model file
Environment	Developer workstation; tool runs with normal user permissions
Response	Tool rejects the file with an error; existing draw.io diagram and sync state are not modified
Response Measure	0 model mutations on parse failure; error returned with code 2; existing files intact (atomic write pattern ensures no partial overwrite)

Stimulus

bausteinsicht sync is invoked with a 50 MB malformed JSONC file

Artifact

JSONC model file

Environment

Developer workstation; tool runs with normal user permissions

Response

Tool rejects the file with an error; existing draw.io diagram and sync state are not modified

Response Measure

0 model mutations on parse failure; error returned with code 2; existing files intact (atomic write pattern ensures no partial overwrite)

Derived from reliability and security requirements (T-4 DoS mitigation, SEC-006).

QS-9: Security — Path Containment

Source Malicious JSONC model or untrusted script passing crafted CLI arguments

Source	Malicious JSONC model or untrusted script passing crafted CLI arguments
Stimulus	CLI invoked with `--model ../../etc/passwd` or `--output /tmp/../../root/`
Artifact	CLI argument parser (`cmd/bausteinsicht/root.go`)
Environment	Any OS; normal user privileges
Response	Tool rejects the path with an error before any file I/O
Response Measure	All paths containing `..` are rejected with exit code 2; no reads or writes occur outside the project directory (verified by SEC-001, SEC-016 fixes)

Stimulus

CLI invoked with --model ../../etc/passwd or --output /tmp/../../root/

Artifact

CLI argument parser (cmd/bausteinsicht/root.go)

Environment

Any OS; normal user privileges

Response

Tool rejects the path with an error before any file I/O

Response Measure

All paths containing .. are rejected with exit code 2; no reads or writes occur outside the project directory (verified by SEC-001, SEC-016 fixes)

Derived from security requirement (T-2 path traversal).

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.