MILTON.Platform

MILTON.Platform provides the fundamental, domain-agnostic technical infrastructure for the MILTON distributed application. It is one of only two shared libraries in the solution (alongside MILTON.ServiceDefaults), carefully designed to avoid coupling microservices through shared business contracts.

Architectural Intent

The primary architectural guardrail for this library is strict domain ignorance. MILTON.Platform contains no domain entities, no Data Transfer Objects (DTOs), and no message contracts. Any concept that intrinsically understands documents, clustering, projects, or inter-service wire formats belongs in a specific service’s boundaries.

By enforcing this boundary, we ensure that adding a dependency on MILTON.Platform never inadvertently couples two services together. MILTON.DocumentGenerator, MILTON.API, and MILTON.GitOperations all reference this library to share technical plumbing without sharing domain knowledge.

Core Infrastructure Components

1. The AI Client Abstraction (MILTON.Platform.AI)

The AI infrastructure is modeled around the IAIService, offering a unified interface for OpenAI-compatible interactions (chat, JSON-enforced grammar, embeddings, clustering, and preset-based generation). Crucially, it consumes a purely technical AiPresetConfig. It knows nothing about the MILTON Project or domain-specific LLM presets; caller services must decrypt and map their domain-specific configurations onto this technical boundary before invocation.

2. S3 Claim-Check Store (MILTON.Platform.Storage)

To prevent RabbitMQ from being overwhelmed by large payloads (such as generated document text or source code), MILTON.Platform implements the Claim-Check Pattern. When a service needs to pass a large payload to another, it stores the payload in the milton-claimcheck S3 bucket via IClaimCheckStore, and passes only the returned lightweight reference key over the message bus.

sequenceDiagram
    participant API as MILTON.API (Producer)
    participant S3 as S3 (milton-claimcheck)
    participant Bus as RabbitMQ / Wolverine
    participant Worker as MILTON.DocumentGenerator (Consumer)

    API->>S3: PutAsync(LargePayload)
    S3-->>API: Returns claim-check Key (e.g., claimcheck/123.json)
    API->>Bus: Publish Message { ClaimCheckKey: "claimcheck/123.json" }
    Bus->>Worker: Deliver Message
    Worker->>S3: GetAsync("claimcheck/123.json")
    S3-->>Worker: Returns LargePayload
    Worker->>S3: DeleteAsync("claimcheck/123.json")

3. S3 Repository File Store (MILTON.Platform.Storage)

Instead of relying on a fragile shared filesystem, MILTON distributes cloned Git repositories via S3. The IRepoFileStore handles uploading and retrieving raw file contents from the milton-repos bucket. MILTON.GitOperations clones the repositories and uploads the files, while consumers like the Python clustering service or MILTON.DocumentGenerator can fetch files contextually using the RepoScope identifier.

graph TD
    Git[MILTON.GitOperations] -->|UploadRepositoryAsync| S3[(milton-repos Bucket)]
    S3 -->|ReadFileAsync| API[MILTON.API]
    S3 -->|ReadFileAsync| DocGen[MILTON.DocumentGenerator]

4. HashiCorp Vault Secret Provider (MILTON.Platform.Security)

The Vault integration (IVaultSecretProvider / VaultSecretClient) fetches and caches secrets from a HashiCorp Vault KV v2 backend, with a background VaultSecretRefresherService that renews dynamic leases or re-fetches static secrets near expiry. Security hardening:

• Resilience via IHttpClientFactory: AddVaultSecretProvider registers a named "VaultClient" HttpClient (30s timeout) with AddStandardResilienceHandler — retry on 429/5xx + transient exceptions with exponential backoff + jitter, a circuit breaker, and a 30s total request timeout. VaultSecretClient never constructs a raw HttpClient; it requires a non-null instance (normally from IHttpClientFactory.CreateClient("VaultClient")) in real mode.
• Explicit mock/offline fallback (no silent fallback): real mode is the default (VaultMode.Real). Mock/offline mode is only used when explicitly requested via Vault:Mode=Mock or APP_MODE=Offline. If real mode is active but Vault:Address/Vault:Token are missing, construction throws an InvalidOperationException (fail fast) instead of silently switching to the in-memory MockVaultSecretProvider. A failed Vault request with no cached value is logged at error level and the exception is rethrown — it never silently returns an empty dictionary.
• TLS enforcement: Vault:AllowInsecureHttp (default false). An http:// Vault:Address throws InvalidOperationException unless the flag is explicitly set for local development; https:// is always allowed.
• Static secrets are not faked as dynamic leases: KV v2 static responses (lease_duration: 0, renewable: false, no lease_id) produce an IsStatic: true, IsRenewable: false, LeaseId: null lease with a configurable TTL instead of a fabricated 1-hour renewable lease. VaultSecretRefresherOptions.StaticRefreshInterval (default 5 minutes) drives re-fetch cadence; the refresher only calls /v1/sys/leases/renew for genuinely renewable dynamic leases and always re-fetches static secrets.

Summary

MILTON.Platform is the engine room of the application. It provides the heavy lifting for AI interactions and distributed storage, adhering strictly to the philosophy that shared libraries should provide capabilities, not contracts.