Contracts

Architectural Context

The Contracts Layer defines the formal messaging schema used to orchestrate work across the inter-service boundaries between MILTON.DocumentGenerator and the main MILTON.Api.

To maintain strict service isolation, MILTON avoids using a shared contracts assembly. Instead, each service declares its own structurally-identical copy of a message record. Wolverine seamlessly routes these messages across RabbitMQ by matching the shared [MessageIdentity("...")] aliases.

Intent and Architecture

The Document Generator orchestrates highly asynchronous, long-running processes (e.g., recursive document block generation). It relies heavily on CQRS and Sagas. The contracts defined here dictate how the DocumentProcessingSaga requests data from the API, and how the generation Cores return results.

Because generated text and source code context can be exceptionally large, messages themselves are kept lightweight. Large payloads travel entirely via an S3 Claim-Check pattern. The messages flowing through RabbitMQ carry only the metadata and the claim-check keys necessary to resolve the payload from object storage.

sequenceDiagram
    participant API as MILTON.Api
    participant Rabbit as RabbitMQ
    participant Saga as DocumentProcessingSaga
    participant Core as AI Generation Core
    participant S3 as S3 Claim-Check Store

    API->>Rabbit: [document-created] DocumentCreatedEvent
    Rabbit->>Saga: Starts Saga Process
    
    Saga->>Rabbit: [prepare-requirement-generation]
    Rabbit->>API: Gathers DB + Context
    
    API->>S3: Writes Generation Payload
    API->>Rabbit: [requirement-generation-requested] (Claim-Check Key)
    Rabbit->>Core: Invokes AI logic
    
    Core->>S3: Reads Payload
    Core->>S3: Writes Result Payload
    Core->>Rabbit: [requirement-generation-completed] (Result Key)
    Rabbit->>API: Applies updates to DB
    
    API->>Rabbit: [block-processed]
    Rabbit->>Saga: Advances Saga State

Contract Categories

Document Orchestration (DocumentOrchestrationMessages)

The core driver of the DocumentProcessingSaga. Includes entry point events like DocumentCreatedEvent, progression commands like ProcessNextBlockCommand and BlockProcessedEvent, and termination commands like GeneratePdfCommand and DocumentGenerationCompletedEvent.

Requirement Generation (RequirementGenerationMessages)

Defines the transport boundaries for the Requirement vertical slice. Includes commands such as PrepareRequirementGenerationCommand to trigger API data gathering, and RequirementGenerationRequested carrying the S3 claim-check key for the pure generation core.

Scanner Generation (ScannerGenerationMessages)

Handles the “Exploder” slice. Provides the schema for routing instructions from the API (which claim-checks file lists and cached clusters) to the clustering worker (ScannerGenerationRequested) and back.

Test Case Generation (TestCaseGenerationMessages)

Orchestrates the generation of test cases derived from existing requirements. Similar to the other slices, this defines the lightweight claim-check transport records like PrepareTestCaseGenerationCommand and TestCaseGenerationRequested.