Templates Feature

The Templates Feature handles the creation, management, and instantiation of DocumentTemplate definitions. A template defines the skeletal structure (a StructureJson hierarchy of Sections and ContentBlocks) and formatting options (DocumentStyleJson) used to dynamically generate complex output documents like SVDs or SRSs.

Business Logic Intent

Before an AI can generate a document, it needs a blueprint. The Template system provides this blueprint. Users can manage project-specific or tenant-global templates defining exactly which logical blocks (Text, Mermaid, Requirements, Trace Matrix, etc.) should be instantiated when a Document is created.

The most critical operation in this feature is Instantiation (InstantiateDocumentEndpoint). When a template is instantiated:

1. The structured JSON blueprint is materialized into physical Document, Section, and ContentBlock rows in the AppDbContext.
2. A CreateDocumentFromTemplateCommand is dispatched to generate these entities.
3. Critically, as a side-effect, Wolverine cascades a DocumentCreatedEvent, which acts as the trigger for the DocumentProcessingSaga in the DocumentGenerator worker, initiating the massive AI pipeline processing phase entirely asynchronously.

Architecture & Integration

• FastEndpoints: Standard CRUD endpoints map to /documents/templates/*.
• Wolverine CQRS: The InstantiateDocumentEndpoint heavily relies on IMessageBus to bridge the gap between the synchronous API creation of the document structure and the asynchronous offloading of AI generation to the worker node.
• Data Persistence: Uses AppDbContext to store the raw JSON template definitions.

Mermaid Sequence Diagram

The following diagram illustrates the lifecycle of Instantiating a document from a Template.

sequenceDiagram
    autonumber
    actor User
    participant API as InstantiateDocument Endpoint
    participant Bus as Wolverine IMessageBus
    participant Handler as CreateDocumentFromTemplateHandler
    participant DB as AppDbContext
    participant Saga as DocumentProcessingSaga (Worker)

    User->>API: POST /documents/templates/instantiate
    API->>Bus: InvokeAsync(CreateDocumentFromTemplateCommand)
    Bus->>Handler: Route Command
    
    Handler->>DB: Load Template
    Handler->>Handler: Parse StructureJson
    Handler->>DB: Materialize Document, Sections, Blocks
    Handler->>DB: SaveChangesAsync()
    
    Handler-->>Bus: Return InstantiateDocumentResponse
    Note over Handler, Bus: Handler Cascades DocumentCreatedEvent
    
    Bus->>Saga: Publish(DocumentCreatedEvent)
    Note right of Saga: Saga activates and begins dispatching Block requests
    
    Bus-->>API: Response
    API-->>User: 200 OK { DocumentId: UUID }

Modules and Components

Endpoints

Located in the Core/ subdirectory:

• ListTemplates, ListProjectTemplates: Query endpoints to discover available blueprints.
• GetTemplate, PreviewTemplate: Fetching singular blueprints and rendering preview states.
• CreateTemplate, UpdateTemplate: Management of the StructureJson definitions.
• InstantiateDocumentEndpoint: The primary integration bridge between standard CRUD and the AI processing pipeline, publishing commands that cascade into saga events.