stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
378b52a5cb2106791c2958802b96be26268d2df3
git.stella-ops.org/docs/modules/platform/architecture.md

6.4 KiB
Raw Blame History

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.