Part 19: Health Score — Rating Architecture Quality with A–F Grades

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 Category Weight What 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 Score Grade ≥ 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 Command Purpose Exit 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: Generated PlantUML diagrams via bausteinsicht export-diagram: What Comes Next Part 20: Element Lifecycle — Track element status from proposed to archived in the model Part 21: As-Is / To-Be — Define the target architecture directly in the model Official documentation: User Manual · Tutorial on doctoolchain.org