Model & Compute Platform — aggregate roots

Generated from the architecture model

This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.

Aggregate	Service	Root entity	Events	Tables
ComputePool	ComputePoolService	ComputePool	ComputePoolRegistered, ComputePoolStateChanged, ModelWarmed, ModelEvicted	ComputePools, PoolModelCache
PlacementDecision	ComputePoolService	PlacementDecision	PlacementDecided	PlacementDecisions
ModelProfile	ModelRouterService	ModelProfile	ModelProfileActivated, ModelProfileRetired	ModelProfiles
ModelDeployment	ModelRouterService	ModelDeployment	DeploymentStateChanged, CapabilityEvidenceRecorded	ModelDeployments, CapabilityScores
RoutePlan	ModelRouterService	RoutePlan	RoutePlanResolved	RoutePlans
InvocationReceipt	ModelRouterService	InvocationReceipt	ModelInvoked, ModelFallbackUsed	InvocationReceipts

ComputePool (ComputePoolService)

One pool of accelerators with its metadata (GPU type, VRAM, CPU, RAM, region, tenant, price, availability), live utilization and queue depth, model cache and cold-start estimate.

Field	Type	Required	Description
poolId	string	yes
tenantId	string	yes	Platform tenant for ConnectSoft pools; the owning tenant for hybrid-compute pools.
kind	enum:PoolKind	yes
state	enum:PoolState	yes
region	string	yes
securityBoundary	enum:SecurityBoundary	yes
gpuType	string	yes
gpuCount	int	yes
vramGb	int	yes
cpuCores	int	yes
ramGb	int	yes
pricePerHourUsd	decimal	yes
utilization	decimal	yes	0 to 1, from the collector.
queueDepth	int	yes
coldStartSeconds	int	yes	Estimated time to load a model that is not cached.
endpointRef	string	yes	Serving endpoint reference; credentials from the Secret Broker.
version	long	yes

Invariants

• A pool is placeable only in state Active and with reported utilization younger than the staleness window.
• A pool's security boundary and region are facts set at registration; placement reads them and never relaxes a requirement to fit a cheaper pool.
• The model cache lists what is loaded now; a placement onto a pool without the model adds the cold-start estimate to the decision.

States (PoolState)

stateDiagram-v2
    Draft --> Active : Activate
    Active --> Draining : Drain
    Draining --> Active : Resume
    Draining --> Retired : Retire

Hold "Alt" / "Option" to enable pan & zoom

Entities: CachedModel · Value objects: —

PlacementDecision (ComputePoolService)

The record of one placement request — requirements, candidates considered with the reason each was kept or excluded, and the chosen pool.

Field	Type	Required	Description
placementId	guid	yes
tenantId	string	yes
deploymentId	string	yes	The self-hosted model deployment to place (BC-07).
runId	guid	no
requirements	json	yes	Accelerator memory, privacy and security boundary, region, latency class, max price.
candidates	json	yes	Pools considered with keep or exclude reasons.
chosenPoolId	string	no
outcome	enum:PlacementOutcome	yes
decidedAt	datetime	yes

Invariants

• Every candidate exclusion names its reason (boundary, region, memory, price, capacity, state) so that an operator can see why a cheaper pool was not chosen.
• PolicyDenied is returned, not worked around, when no pool satisfies the privacy or region requirement.

ModelProfile (ModelRouterService)

Runtime read model of a Published model-profile asset (BC-04, D32) — the logical capability, privacy, limit and fallback requirement that agents and workflows reference instead of model names.

Field	Type	Required	Description
profileId	string	yes	Logical name such as code-agent, reasoning-high, embedding, pii-local.
version	string	yes
releaseId	string	yes	Published asset release of the profile.
tenantId	string	yes	Platform tenant for ConnectSoft profiles; a tenant may publish its own.
modality	enum:Modality	yes
requiredCapabilities	json	yes	Capability thresholds (tool calling, structured output, JSON schema, reliable context, patch success, multi-turn…) from the quality gates.
privacyClass	enum:PrivacyClass	yes
latencyClass	enum:LatencyClass	yes
maxContextTokens	int	yes
maxOutputTokens	int	yes
allowedRegions	list:string	yes
allowedDeployments	list:string	yes	Deployment ids the router may choose, in preference order.
fallbackChain	list:string	yes	Explicit profile ids to fall back to; each must satisfy the same privacy and output guarantees.
fallbackEnabled	bool	yes	Runtime fallback is off unless an equivalent-constraint alternative exists and passed its tests.
embeddingCompatibility	string	no	Embedding space identifier for embedding profiles.
priceBasis	string	yes	Pricing revision reference used for estimates.

Invariants

• A profile is usable only when its release is Published and Platform-admin approved (D32); runs pin the profile version at acceptance.
• Every entry of fallbackChain has the same or a stricter privacy class and the same tool and structured-output guarantees.
• Clients reference profiles, never provider model names; a provider model appears only on receipts.

ModelDeployment (ModelRouterService)

One concrete provider, model revision and endpoint in a region with its capability evidence, license metadata, health and ModelOps state.

Field	Type	Required	Description
deploymentId	string	yes
tenantId	string	yes
provider	string	yes	openai
model	string	yes	Provider model identifier and revision.
region	string	yes
privacyClass	enum:PrivacyClass	yes
endpointRef	string	yes	Connection or pool reference; credentials come from the Secret Broker.
computePoolId	string	no	For self-hosted deployments the pool that serves it (BC-41).
capabilityEvidenceRef	string	no	Evaluation record reference (BC-22) with scores per capability.
licenseMetadata	json	yes	Commercial use, redistribution, fine-tuning, customer deployment.
state	enum:DeploymentState	yes
healthy	bool	yes
version	long	yes

Invariants

• A deployment is routable only in state Approved and healthy; Degraded deployments are skipped by the router without changing the route plan's constraints.
• Approval requires capability evidence that meets the thresholds of every profile that lists the deployment (quality gates).
• License metadata is recorded before approval; a deployment whose license forbids the intended use is never Approved.

States (DeploymentState)

stateDiagram-v2
    Candidate --> Evaluated : CapabilityEvidenceRecorded
    Evaluated --> Approved : PlatformAdminApproval
    Approved --> Degraded : HealthProbeFailed
    Degraded --> Approved : HealthProbeRecovered
    Approved --> Retired : Retire
    Degraded --> Retired : Retire

Hold "Alt" / "Option" to enable pan & zoom

Entities: CapabilityScore · Value objects: —

RoutePlan (ModelRouterService)

The ordered candidates resolved for one run and profile under the policy revision in force; immutable for the run so that every attempt routes the same way.

Field	Type	Required	Description
routePlanId	guid	yes
runId	guid	yes
tenantId	string	yes
profileId	string	yes
profileVersion	string	yes
policyRevision	string	yes
candidates	list:string	yes	Deployment ids in order after policy filters, capability scores, cost and latency.
constraints	json	yes	Privacy class, region, tool and output guarantees that every candidate satisfies.
resolvedAt	datetime	yes

Invariants

• A route plan is resolved once per run and profile and reused by every attempt; a changed policy affects future runs only.
• Every candidate satisfies the plan's constraints; the router never adds a candidate at invocation time.

InvocationReceipt (ModelRouterService)

The record of one model call — what was asked by hash, which deployment actually answered, how much was used and with what certainty, which policy decision allowed it and whether a fallback was taken.

Field	Type	Required	Description
invocationId	guid	yes
tenantId	string	yes
projectId	string	yes
runId	guid	no
attemptId	guid	no
profileId	string	yes
deploymentId	string	yes	The deployment that produced the output.
routePlanId	guid	no
fallbackUsed	bool	yes
requestHash	hash	yes
idempotencyKey	string	yes
policyDecisionId	guid	yes
outcome	enum:InvocationOutcome	yes
usageStatus	enum:UsageStatus	yes
inputTokens	int	no
outputTokens	int	no
estimatedCostUsd	decimal	no
pricingRevision	string	yes
latencyMs	int	no
outputArtifactRef	string	no	Artifact reference of the output (content never stored here).
startedAt	datetime	yes
endedAt	datetime	no

Invariants

• A receipt exists for every invocation that reached an adapter, including failed, denied, cancelled and partial ones.
• The same idempotency key within scope returns the existing receipt instead of a second call.
• Usage Unknown is recorded as such and reconciled by statement; it is never written as zero.