This post continues from the eighteenth part. bausteinsicht validate and bausteinsicht lint check whether the model is correct. bausteinsicht health goes further: it evaluates how good the model is — completeness, conformance, complexity, and more.

bausteinsicht health

bausteinsicht health --model architecture.jsonc

Output:

Architecture Health Report
==========================

Overall Score: 78.5/100 [B]
Summary: Good architecture documentation with room for improvement
Timestamp: 2025-06-11T06:00:00Z

Model Statistics
----------------
Elements:      18
Relationships: 14
Views:          4

Category Scores
---------------
Completeness:    82.0/100 (weight: 40%)
  Details: 15/18 elements have descriptions
Conformance:     95.0/100 (weight: 30%)
  Details: 1 constraint violation
Complexity:      65.0/100 (weight: 20%)
  Details: High relationship density detected
Deprecation:     70.0/100 (weight: 5%)
  Details: 2 deprecated elements still in use
Documentation:   80.0/100 (weight: 5%)
  Details: 3 elements without title

Findings
--------
Completeness (3 findings):
  [MAJOR] Missing descriptions
          shop.legacy, shop.legacy.api, eventbus: description is empty

Complexity (1 finding):
  [MINOR] High coupling
          shop.api has 6 outgoing relationships — consider splitting

Deprecation (1 finding):
  [MAJOR] Deprecated element referenced
          shop.legacy: status=deprecated but still used by shop.frontend

Evaluation Categories

CategoryWeightWhat is evaluated

Completeness

40 %

Share of elements with description, title, technology

Conformance

30 %

Constraint violations from bausteinsicht lint

Complexity

20 %

Relationship density, maximum depth, cycles

Deprecation

5 %

Deprecated/archived elements that are still referenced

Documentation

5 %

Elements without a title field

Grade Scale

ScoreGrade

≥ 97

A+

≥ 93

A

≥ 90

B+

≥ 87

B

≥ 80

C+

≥ 70

C

≥ 60

D

< 60

F

Summary View for Dashboards

bausteinsicht health --model architecture.jsonc --summary
# → Overall Score: 78.5/100 [B]

# As JSON (for CI evaluation)
bausteinsicht health --model architecture.jsonc --summary --format json
{
  "overall": 78.5,
  "grade": "B",
  "summary": "Good architecture documentation with room for improvement",
  "timestamp": "2025-06-11T06:00:00Z"
}

Writing the Report to a File

bausteinsicht health --model architecture.jsonc \
  --output docs/architecture-health.txt

Full JSON Output

bausteinsicht health --model architecture.jsonc --format json

Returns the complete HealthScore object with categories, findings, element counts, and an ISO 8601 timestamp.

CI Integration

- name: Architecture health (informational)
  run: |
    bausteinsicht health --model architecture.jsonc --summary
  continue-on-error: true   # health does not break the build

- name: Architecture health (enforce minimum grade)
  run: |
    GRADE=$(bausteinsicht health --model architecture.jsonc \
      --summary --format json | jq -r '.grade')
    if [[ "$GRADE" == "D" || "$GRADE" == "F" ]]; then
      echo "Architecture health below minimum threshold: $GRADE"
      exit 1
    fi
Unlike bausteinsicht lint, health does not block the build via exit code — it is a quality measurement, not a gate. You can control the exit code yourself via the grade threshold (as shown in the example above).

Difference from validate and lint

CommandPurposeExit code on problem

validate

Structural correctness (references, schema)

1

lint

Constraint violations (architecture rules)

1

health

Quality assessment (score, grade)

0 (always succeeds)

Example Model

The example for this part (model with varying documentation quality — legacy service without description/status) is located at teil_19.jsonc.

This is what the result looks like in draw.io (bausteinsicht sync):

You can find the draw.io file here: teil_19.drawio

Generated PNG files via bausteinsicht export --image-format png:

containers
context

Generated PlantUML diagrams via bausteinsicht export-diagram:

Diagram
Diagram

What Comes Next

Official documentation: User Manual · Tutorial on doctoolchain.org