TraceLinks

Info

Architectural truth for TraceLinks in the Documents feature. This leaf module contains the domain logic and endpoints for establishing many-to-many traceability between ContentBlocks.

Overview

Traceability is a fundamental requirement in systems engineering and software documentation (e.g., ensuring every Requirement has at least one TestCase, and every TestCase traces back to a Requirement).

In MILTON, this is achieved via the TraceLink entity, which acts as a directed edge between two ContentBlock vertices.

Business Logic Intent

The Documents/TraceLinks module provides synchronous CRUD operations for creating and querying these relationships. When a worker (like the TestCase generator) generates new blocks, it will often also emit commands to create trace links automatically. However, users can also manually define trace links between any two blocks in the system, even across different documents within the same project.

Endpoints

• CreateTraceLinkEndpoint: Creates a directed link (SourceBlockId → TargetBlockId) with a specific LinkType (e.g., Verifies, Implements, DependsOn).
• GetTraceLinksEndpoint: Given a BlockId, returns all trace links where the block is either the source OR the target.

Entity Graph

erDiagram
    CONTENT_BLOCK {
        Guid Id
        string Type
    }
    TRACE_LINK {
        Guid Id
        Guid SourceBlockId
        Guid TargetBlockId
        string LinkType
        string Notes
    }
    
    CONTENT_BLOCK ||--o{ TRACE_LINK : "is Source"
    CONTENT_BLOCK ||--o{ TRACE_LINK : "is Target"

Domain Models

• TraceLink: The EF Core entity representing the many-to-many relationship.
• Request Models: CreateTraceLinkRequest, GetTraceLinksRequest
• Response DTOs: TraceLinkDto