Sections

Info

Architectural truth for Sections in the Documents feature. This leaf module contains the domain logic and endpoints for managing the structural hierarchy of a document.

Overview

In MILTON, documents are strictly structured into hierarchical Sections. A Section is a container that belongs to a Document and can contain either child Sections or polymorphic ContentBlocks.

The Documents/Sections module is purely synchronous and handles structural CRUD operations for Sections via FastEndpoints.

Business Logic Intent

The main intent of this module is to allow clients to manipulate the document tree dynamically. While initial document structure is often instantiated from a Template, users can manually add sections, reorder them, or attach specific source code files to a section to constrain the context for downstream block generation.

Context Constraining

A key feature of a Section is its SourceFilesJson property. By attaching source files to a Section (via UpdateSectionSourceFilesEndpoint), all ContentBlock elements inside that section will inherit those files as their context during LLM generation. This allows users to say “Generate documentation for these specific files in this section.”

Endpoints

• AddSectionEndpoint: Creates a new Section. Supports nesting via the optional ParentSectionId.
• ReorderSectionsEndpoint: Receives an ordered list of Section IDs and updates their SortOrder in the database within a specific Document.
• UpdateSectionSourceFilesEndpoint: Attaches an array of source file paths to a section. Serializes the array to SourceFilesJson.

Sequence: Attaching Source Files

sequenceDiagram
    participant Client
    participant Endpoint as UpdateSectionSourceFilesEndpoint
    participant DB as AppDbContext
    
    Client->>Endpoint: PUT /documents/sections/sourcefiles
    Note right of Client: { SectionId, SourceFiles: ["/src/main.cs"] }
    
    Endpoint->>DB: FindAsync(SectionId)
    DB-->>Endpoint: Section Entity
    
    Endpoint->>Endpoint: Serialize SourceFiles to JSON
    Endpoint->>DB: SaveChangesAsync()
    Endpoint-->>Client: 200 OK

Domain Models

• Section: The EF Core entity representing a node in the document tree. Key fields: DocumentId, ParentSectionId, Title, SortOrder, SourceFilesJson.
• Request Models: AddSectionRequest, ReorderSectionsRequest, UpdateSectionSourceFilesRequest
• Response DTOs: SectionDto