README

MILTON

MILTON is an AI-assisted documentation platform. It ingests source code repositories, analyses them, and generates structured technical documents (requirements, test cases, traceability, etc.) that can be edited in a web UI and exported to PDF.

Architecture at a glance

MILTON is orchestrated with .NET Aspire (MILTON.AppHost). The main moving parts:

Project / Resource	Role
MILTON	Main backend API (FastEndpoints) + Wolverine; owns the relational domain, EF persistence/migrations, and supporting infrastructure
MILTON.Platform	Shared technical-infra library: AI client, S3 repo-file + claim-check stores. No domain/DTOs
MILTON.DocumentGenerator	Worker: AI document/block generation + the saga. Message-only, owns its own docgen-db
MILTON.GitOperations	Worker: clones repositories and uploads them to S3
MILTON.NotificationService	SignalR hub + live-update consumer
MILTON.ApiMigrationService	Applies the API’s EF Core migrations to milton-db on startup
MILTON.DocumentGeneratorMigrationService	Applies DocGenDbContext EF Core migrations to docgen-db on startup
MILTON.ReverseProxy	YARP gateway (TLS termination, unified routing)
MILTON.Clustering	Python service for repository clustering/analysis
MILTON.ReactClient	The frontend — React 19 + Vite (see its own README)
MILTON.ServiceDefaults	Shared OpenTelemetry / health / resilience config

Service isolation: there is no shared domain/contracts library — MILTON.BackendCore and MILTON.Shared have both been folded into the API. Services interoperate over RabbitMQ via per-producer records bound by Wolverine [MessageIdentity], with large payloads passed through an S3 claim-check. The only shared libraries are MILTON.Platform and MILTON.ServiceDefaults.

Backing services (run as containers via Aspire): PostgreSQL, RabbitMQ, Keycloak, RustFS (S3-compatible storage), and Gotenberg (HTML→PDF).

The frontend is React only. The previous Blazor client (MILTON.Client) has been removed.

Running locally

The whole system is started through the Aspire AppHost:

aspire run

This builds and launches every .NET service, the React client, and all backing containers, and exposes the Aspire dashboard. See CLAUDE.md for more detail on working with the Aspire orchestration.

Repository docs

• CLAUDE.md / AGENTS.md — the authoritative architecture reference and agent instructions (services, CQRS pipeline, key patterns, Aspire workflow, commands). These two are intentional duplicates so that every AI tool used on this project finds the filename it looks for — CLAUDE.md for Claude Code, AGENTS.md for opencode, Codex, Antigravity, and others. Edit both together; do not let them drift.
• index.md — per-service and per-feature documentation index