SDS-036: Documentation Orchestrator Service

sds_id: SDS-036 title: Documentation Orchestrator Service bounded_context: shared satisfies_prds:

Addresses Requirements

MVP Status

✅ MVP

Component Description

The Documentation Orchestrator Service coordinates the automated generation of comprehensive project documentation. It receives requests to generate documentation for specific projects, orchestrates the extraction of context from the Universal Context Service (SDS-051), and leverages the Artifact Engine to generate documentation artifacts using CADSL. The service manages documentation templates, formatting rules, and quality validation to ensure production-ready output.

Domain Model

Aggregates

Aggregate Identity Description
DocumentationJob jobId Tracks documentation generation request lifecycle
DocumentationArtifact artifactId Generated documentation output

Value Objects

Value Object Description
DocumentationType Enum: README, API_REFERENCE, ARCHITECTURE, CHANGELOG
OutputFormat Enum: MARKDOWN, HTML, PDF
GenerationOptions Configuration for generation (theme, sections, etc.)
TemplateSpec Template configuration and variable bindings

Invariants (Policies)

Policy ID Name Rule
POL-DOC-001 FreshnessGuarantee Generated docs must be ≤ 24h old or regenerated on request
POL-DOC-002 TemplateConformance All output must conform to registered template schema
POL-DOC-003 TraceabilityRequired Generated docs must include ADR/PRD/SDS references
POL-DOC-004 IdempotentGeneration Same input + context must produce identical output

CQRS Operations

Commands

Command ID Name Description Emits Event
CMD-DOC-001 GenerateDocumentation Request documentation generation for project EVT-DOC-001
CMD-DOC-002 ValidateDocumentation Validate generated documentation quality EVT-DOC-002
CMD-DOC-003 RefreshDocumentation Force regeneration of stale documentation EVT-DOC-001
CMD-DOC-004 RegisterTemplate Register or update a documentation template EVT-DOC-003

Queries

Query ID Name Description Consistency
QRY-DOC-001 GetDocumentation Retrieve generated documentation eventual
QRY-DOC-002 GetJobStatus Check documentation generation job status strong
QRY-DOC-003 ListTemplates List available documentation templates eventual

Events

Event ID Name Payload
EVT-DOC-001 DocumentationGenerated {jobId, projectId, types[], artifactIds[], generatedAt}
EVT-DOC-002 DocumentationValidated {artifactId, validationResult, issues[]}
EVT-DOC-003 TemplateRegistered {templateId, templateType, version, registeredAt}

Technical Details

Interfaces

Direction Description Format
Input Project identifier String
Input Documentation type Enum (README, API, architecture)
Input Configuration parameters JSON
Output Documentation artifacts CADSL, Markdown, HTML

Protocols

API Specification

Endpoints

Endpoint Method Description
/documentation/generate POST Generate documentation
/documentation/{projectId}/{type} GET Retrieve generated docs
/documentation/validate POST Validate documentation

Request/Response

Generate Documentation

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

POST /documentation/generate
{
  "projectId": "order-service",
  "types": ["readme", "api-reference", "architecture"],
  "options": {
    "includeExamples": true,
    "includeDiagrams": true,
    "format": "markdown",
    "theme": "default"
  }
}

// Response
{
  "jobId": "job-uuid",
  "status": "processing",
  "estimatedCompletion": "2024-01-15T10:30:00Z"
}

Get Documentation

1
2
3
4
5
6
7
8
9
10
11
12

GET /documentation/order-service/readme

// Response
{
  "artifact": {
    "type": "readme",
    "format": "markdown",
    "content": "# Order Service\n\n## Overview\n...",
    "sections": ["overview", "quick-start", "api", "architecture"],
    "generatedAt": "2024-01-15T10:25:00Z"
  }
}

Error Codes

Code Description
400 Bad Request Invalid request parameters
404 Not Found Project not found
500 Internal Server Error Generation failure

Dependencies

Error Handling

Performance Considerations

Security Considerations

Testing Strategy