feat: Relationship Cardinality & Data Flow Annotations (#289)

[paulefl]

Fixes #289

Summary

Adds support for cardinality and data flow annotations on relationships, enabling precise communication of integration patterns and data relationship semantics in architecture models.

Changes

• internal/model/types.go:
  • Added Cardinality field to Relationship struct (supports 1:1, 1:N, N:N)
  • Added DataFlow field to Relationship struct (supports sync, async, request/response, publish/subscribe)
  • Added ValidCardinalities and ValidDataFlows constant lists
• internal/model/validate.go:
  • Extended validateRelationships() to validate cardinality values
  • Extended validateRelationships() to validate dataFlow values
  • Provides clear error messages for invalid values
• internal/model/cardinality_test.go:
  • Comprehensive tests for valid/invalid cardinality values
  • Comprehensive tests for valid/invalid dataFlow values
  • Tests for annotation combinations

Design

• Optional Fields: Both cardinality and dataFlow are optional, maintaining backward compatibility
• Validation: Invalid values are caught during model validation
• Flexible: Supports various integration patterns (synchronous, asynchronous, pub/sub)
• Extensible: Easy to add new cardinality or data flow types

Example Usage

{
  "relationships": [
    {
      "from": "service1",
      "to": "service2",
      "label": "queries database",
      "cardinality": "1:N",
      "dataFlow": "sync"
    },
    {
      "from": "eventBus",
      "to": "consumers",
      "cardinality": "1:N",
      "dataFlow": "publish/subscribe"
    }
  ]
}

Test Plan

• Unit tests: All cardinality and dataFlow values tested
• Validation: Invalid cardinality and dataFlow values rejected
• Backward compatibility: Relationships without annotations still valid
• Build succeeds: go build ./cmd/bausteinsicht
• Tests pass: go test ./internal/model/...

🤖 Generated with Claude Code

[raifdmueller]

Code Review

The cardinality and data flow annotations are well-designed and backward-compatible. One issue before merging:

Schema missing enum constraints: The new cardinality and dataFlow fields are defined as plain strings in the JSON schema. Valid values like "1:1", "1:N", "sync", "async" should be listed as enum entries so IDE autocompletion and schema validation enforce them — otherwise the schema provides no guidance to users.

Minor: "sync" exists as both a DataFlow constant and a StepType constant in types.go — worth a comment to clarify they are independent domains.

Please add `"enum": [...]" to the cardinality and dataFlow schema definitions before merging.

[github-actions]

📊 Test Report (Multi-OS)

Metric	🐧 Linux	🪟 Windows	🍎 macOS
Total Tests	805	805	805
✅ Passed	802 (99.6%)	802 (99.6%)	802 (99.6%)
❌ Failed	0	0	0
⏱️ Duration	7.16s	12.00s	6.79s
📦 Coverage	68.8%	68.7%	68.8%

💡 Full report: Download artifacts from this workflow run.

[raifdmueller]

Lint fixes applied (fmt.Fprintf pattern), schema regenerated — enum validation remains in Go model validator.

[github-actions]

📊 Test Report (Multi-OS)

Metric	🐧 Linux	🪟 Windows	🍎 macOS
Total Tests	805	805	805
✅ Passed	802 (99.6%)	802 (99.6%)	802 (99.6%)
❌ Failed	0	0	0
⏱️ Duration	7.08s	13.27s	6.80s
📦 Coverage	68.8%	68.7%	68.7%

💡 Full report: Download artifacts from this workflow run.

[github-actions]

📊 Test Report (Multi-OS)

Metric	🐧 Linux	🪟 Windows	🍎 macOS
Total Tests	805	805	805
✅ Passed	802 (99.6%)	802 (99.6%)	802 (99.6%)
❌ Failed	0	0	0
⏱️ Duration	7.19s	11.23s	6.85s
📦 Coverage	68.8%	68.7%	68.7%

💡 Full report: Download artifacts from this workflow run.

[github-actions]

📊 Test Report (Multi-OS)

Metric	🐧 Linux	🪟 Windows	🍎 macOS
Total Tests	805	805	805
✅ Passed	802 (99.6%)	802 (99.6%)	802 (99.6%)
❌ Failed	0	0	0
⏱️ Duration	7.15s	10.06s	6.93s
📦 Coverage	68.8%	68.7%	68.7%

💡 Full report: Download artifacts from this workflow run.