# Platform architecture (summary)

This module aggregates cross-cutting contracts and guardrails that every StellaOps service must follow.

## Anchors
- High-level system view: `../../ARCHITECTURE_REFERENCE.md`
- Architecture overview: `../../ARCHITECTURE_OVERVIEW.md`
- Platform overview: `architecture-overview.md`
- Platform service definition: `platform-service.md`
- Aggregation-Only Contract: `../../aoc/aggregation-only-contract.md` (referenced across ingestion/observability docs)

## Scope
- **Identity & tenancy**: Authority-issued OpToks, tenant scoping, RBAC, short TTLs; see Authority module docs.
- **AOC & provenance**: services ingest evidence without mutating/merging; provenance preserved; determinism required.
- **Offline posture**: Offline Kit parity, sealed-mode defaults, deterministic bundles.
- **Platform Service**: aggregation endpoints for health, quotas, onboarding, preferences, and global search.
- **Observability baseline**: metrics/logging/tracing patterns reused across modules; collectors documented under Telemetry module.
- **Determinism**: stable ordering, UTC timestamps, content-addressed artifacts, reproducible exports.

## Coordination
Platform docs are the starting point for new contributors; keep this summary in sync with module-specific dossiers and sprint references.

## Shared Storage Driver Contract (Sprint 312)

This contract is the default for all stateful StellaOps webservices unless a module ADR explicitly overrides it.

- `Storage:Driver`
  - Accepted values: `postgres`, `inmemory`, `filesystem`.
  - Production default: `postgres`.
  - `inmemory` and `filesystem` are non-production/testing-only and must be explicitly configured.
- `Storage:ObjectStore:Driver`
  - Accepted values at platform key level: `rustfs`, `seed-fs`.
  - Module runtime contracts may narrow this set and must fail fast for unsupported values.
  - Use only for blob/object payload channels (artifacts, snapshots, package blobs).
- `ConnectionStrings:Default`
  - Required when `Storage:Driver=postgres` unless a service-specific connection key is provided.
  - Service-specific key, when present, takes precedence over `ConnectionStrings:Default`.

Fail-fast policy:
- Non-development runtime must fail startup when required storage configuration is missing (no silent localhost/file fallback).
- Development runtime may use localhost/file defaults only when explicitly intended for local workflows.

Current implementation status (2026-03-05):
- `PacksRegistry`: Postgres metadata/state + seed-fs payload channel for pack/provenance/attestation blobs; startup rejects `rustfs` and unknown object-store drivers.
- `TaskRunner`: Postgres run state/log/approval + seed-fs artifact payload channel; startup rejects `rustfs` and unknown object-store drivers in both WebService and Worker.
- `RiskEngine`: Postgres-backed result store (`riskengine.risk_score_results`) with explicit in-memory test fallback.
- `Replay`: Postgres snapshot index + seed-fs snapshot blob store; startup rejects `rustfs` and unknown object-store drivers.
- `OpsMemory`: connection precedence aligned to `ConnectionStrings:OpsMemory -> ConnectionStrings:Default`, with non-development fail-fast.

## Platform Runtime Read-Model Boundary Policy (Point 4 / Sprint 20260305-005)

Platform runtime read-model APIs are aggregation-only and must stay behind explicit query contracts. Runtime read handlers must not take direct dependencies on foreign module persistence internals.

Approved runtime query contracts:
- `IReleaseControlBundleStore` (release/topology/security/integration projections over release-control bundles + runs).
- `IPlatformContextQuery` (read-only access to region/environment context inventory).

Prohibited in runtime read-model services:
- Direct constructor dependencies on foreign `StellaOps.*.Persistence*` namespaces.
- Direct `DbContext`, `NpgsqlDataSource`, or module-specific migration runner dependencies from non-admin read endpoints.

Migration/admin allowlist (explicit boundary exceptions):
- `src/Platform/StellaOps.Platform.WebService/Endpoints/SeedEndpoints.cs`
- `src/Platform/__Libraries/StellaOps.Platform.Database/MigrationModulePlugins.cs`

Enforcement:
- Guard tests in `src/Platform/__Tests/StellaOps.Platform.WebService.Tests/PlatformRuntimeBoundaryGuardTests.cs` fail when constructor contracts drift or foreign persistence references appear outside the allowlist above.

### Runtime Dependency Inventory (2026-03-05)

| Component | Dependency category | Classification | Notes |
| --- | --- | --- | --- |
| `ReleaseReadModelService` | `IReleaseControlBundleStore` | Allowed runtime read-model dependency | Release projection reads only via Platform-owned bundle-store contract. |
| `TopologyReadModelService` | `IReleaseControlBundleStore`, `IPlatformContextQuery` | Allowed runtime read-model dependency | Topology projection composes release bundles with context inventory through explicit query contracts. |
| `SecurityReadModelService` | `IReleaseControlBundleStore`, `IPlatformContextQuery` | Allowed runtime read-model dependency | Security projection remains synthetic/read-only and does not call VEX/exception write stores directly. |
| `IntegrationsReadModelService` | `IReleaseControlBundleStore`, `IPlatformContextQuery` | Allowed runtime read-model dependency | Integration freshness projection uses release run metadata and context inventory only. |
| `PlatformContextService` | `IPlatformContextStore` (`InMemory`/`Postgres`) | Allowed runtime dependency (module-local persistence) | Exposes read-only `IPlatformContextQuery` plus preference write APIs; no foreign module coupling. |
| `SeedEndpoints` | Foreign `StellaOps.*.Persistence*` migration assemblies | Migration/admin-only dependency | Allowed exception for demo seed execution only (`platform.setup.admin`). |
| `MigrationModulePlugins` | Foreign module migration assemblies | Migration-only dependency | Allowed exception for schema migration orchestration, not part of runtime read endpoint execution path. |

## Advisory Commitments (2026-02-26 Batch)

- `SPRINT_20260226_223_Platform_score_explain_contract_and_replay_alignment` defines deterministic score/explain/replay contract behavior for CLI and Web consumers.
- `SPRINT_20260226_230_Platform_locale_label_translation_corrections` completes locale label correction baseline for cross-language operator UI consistency.
- Cross-module advisory translation tracking is maintained in `docs/product/advisory-translation-20260226.md`.