StellaOps Architecture Overview

Verified against commit 942a18727c (2026-09-26, DOC-2 of SPRINT_20260926_001). Re-verify by reading the evidence paths listed in the Evidence section.

Audience: service owners, platform engineers and contributors who need the cross-cutting rules every Stella Ops service follows. The system-wide service map, flows and failure behaviour live in ARCHITECTURE_OVERVIEW.mdand the module index in ARCHITECTURE_REFERENCE.md. The Platform WebService runtime is described in architecture.md.

This page replaced a pre-consolidation overview on 2026-09-26. The earlier text described Concelier and Excititor WebServices, Scheduler services and advisory_raw/vex_raw raw stores that are no longer part of the estate; it is kept as a frozen record under docs-archive/modules/platform/architecture-overview.md.

1 · System landscape

The release bundle (devops/release/bundle/docker-compose.yml) is the authoritative list of deployables. Clients (Console SPA, stella CLI, CI/API clients) reach every service through router-gateway; services attach to the gateway as router microservices over the Valkey messaging transport and authenticate Authority-issued bearer tokens. Backing infrastructure is one PostgreSQL server, Valkey and RustFS object storage.

SmRemote and Tester are not in the bundle and run only from their own overlays (devops/compose/docker-compose.sm-remote.yml, devops/compose/docker-compose.tester.yml). Workflow (src/Workflow) has no service in the bundle or in the compose files under devops/compose/. The central doctor-web host was retired on 2026-08-17; diagnostics are hosted by each service (see Doctor).

2 · Cross-cutting rules

• One service, one database. Each microservice owns one physical PostgreSQL database and role on the shared server and resolves only its own STELLAOPS_POSTGRES_<SERVICE>_CONNECTION. Cross-service access goes through the owner’s API, events or a registered read contract. The ownership tiebreaker is the database ownership matrix.
• Startup convergence. Services apply their own embedded SQL migrations at startup (AddStartupMigrations). There is no central migration service or migration HTTP face; each service reports its own state through its doctor.standard.db.migration-status check.
• Envelope-bound tenant identity. Tenant identity is resolved from the envelope-attached stellaops:tenant claim through IStellaOpsTenantAccessor (src/Authority/StellaOps.Authority/StellaOps.Auth.ServerIntegration/Tenancy/). Raw tenant headers are not a tenancy source; TenantHeaderCallSiteConformanceTests enforces this.
• Tenancy model. Tenants are environments, business units or logical scopes under one operator trust boundary (ADR-005).
• Tenant directory. shared.tenants lives in the Platform database and is written by Platform only: platform-web drains Authority’s tenants catalog (catalog:replicate) and projects the owner fields (SharedTenantsCatalogProjection.cs). Platform-owned columns (is_default, default_region, settings, metadata) are never overwritten by the projection. See the catalog-replication contract and the Authority tenant model.
• Empty topology is tenant truth. The Platform topology synchronizer records zero-row watermarks for tenants without environments; /api/v2/topology/* then returns a typed empty result instead of falling back to a global catalog.
• Router weighted canary. The gateway can split traffic by advertised (Router__Microservice__Weight) or overridden routing weight; overrides are managed through GET/POST /api/v1/router/routing/weights (src/Router/StellaOps.Gateway.WebService/Endpoints/RoutingWeightEndpoints.cs). Operations: weighted canary deployment runbook.
• Runtime plugins are signed and fail closed. Executable extensions are delivered as signed bundles mounted at runtime. Admission binds the manifest, verifies per-assembly SHA-256 and a detached signature before any code loads (shared chokepoint src/__Libraries/StellaOps.Plugin/Security/SignedRuntimePluginAdmission.cs). The module set is the -Module list of devops/build/package-runtime-plugins.ps1; per-module status is in the plugin development guide.
• Cryptography and compliance defaults. First-run setup captures installation-scoped regional crypto, FIPS mode and compliance defaults in platform.environment_settings; see cryptography and compliance.
• Determinism and offline posture. Stable ordering, UTC timestamps and content-addressed artifacts; no cloud-managed defaults. Release artifacts are deployed by digest.
• OCI reference admission. The neutral parser validates explicit distribution names pinned by digest; content kind and authorization remain consumer responsibilities. See the OCI reference contract for port, tag, IPv6 and rejection behavior.

3 · Platform service in the estate

StellaOps.Platform.WebService is the Console backend. It serves the frontend configuration (/platform/envsettings.json), owns installation settings, the tenant directory and rebuildable read projections, hosts federated and NIS2 telemetry surfaces, the crypto provider and KEK control plane, the connector credential store, and the Doctor capability registry and aggregate view. It hosts no ReleaseOrchestrator operations and no migration authority. Detail: architecture.mdand platform-service.md.

4 · Offline & disaster readiness

• Migrations are forward-only (ADR-004). Rollback is a PostgreSQL snapshot restore, not a reverse migration; see the migration recovery runbook.
• Offline operation is served by the Offline Kit services (offlinekit-web, offlinekit-worker, offlinekit-exportcenter-init); see ../../OFFLINE_KIT.md.
• Deterministic replay is owned by the Replay module; see ../replay/architecture.md.

Evidence