git.stella-ops.org/docs/modules/platform/architecture.md

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: rustfs, seed-fs.
  • 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.
• TaskRunner: Postgres run state/log/approval + seed-fs artifact payload channel.
• RiskEngine: Postgres-backed result store (riskengine.risk_score_results) with explicit in-memory test fallback.
• Replay: Postgres snapshot index + seed-fs snapshot blob store.
• OpsMemory: connection precedence aligned to ConnectionStrings:OpsMemory -> ConnectionStrings:Default, with non-development fail-fast.

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.