Architecture Overview (High-Level)

This document describes Stella Ops Suite’s ownership boundaries and governed release workflow. The implementation limits below distinguish serving contracts from the remaining acceptance work.

Ownership and flow references verified against 60913a04352cb4899ab6443e596811b11cc3f01a on 2026-09-30. This was a source review, not a deployment or acceptance run. Recheck the service map with python tools/scripts/generate/service-inventory.py --check and the serving contracts linked below before applying this description to an installation.

Audience: operators, architects, and integrators evaluating or deploying the platform. For the index into per-subsystem detail — module dossiers, API contracts, schemas — see ARCHITECTURE_REFERENCE.md. For a one-line-per-component map of the codebase, see Platform component map.

What Stella Ops Suite is

Stella Ops Suite is a centralized, auditable release control plane for non-Kubernetes container estates.

It sits between CI and runtime targets. The product outcome is a governed release whose artifact, policy decision, approval, execution observations, recovery and evidence remain attributable. A later risk assessment must retain the original decision, and a separate reader must be able to verify the selected evidence offline with its declared trust material.

CI artifact → Scan and policy → Scoped approval → Target execution and observation → Exact evidence
                                                       ↓                              ↓
                                                Owned recovery                 Offline verification

New advisory / VEX / runtime evidence → Current risk assessment → Accountable action
                                      (historical decision and proof remain unchanged)

The Console confidence decisions define this scope. Its acceptance contract requires real restricted roles, target observations, interrupted-operation recovery and independent proof. Those scenarios are not claimed passed by this document.

Implementation status and remaining proof

• Release Orchestrator owns persisted releases, approvals, gate decisions and deployment dispatch. Dispatch acceptance is not target completion; an observer’s report is identified separately from independent corroboration. See the deployment runtime contract.
• Policy owns evaluation; Release Orchestrator owns promotion, approval and execution authorization. A permitted policy result alone does not authorize deployment. See the promotion ownership contract.
• Evidence owns the consolidated proof service; Signer remains a separate key-custody service. Release Orchestrator writes each committed decision revision with a durable seal intent and reconciles it into Evidence under a tenant-bound idempotency key, so saturation, restart, an Evidence outage or a lost response does not lose or duplicate the decision proof (CCP-050, source; estate activation needs an authorized redeploy). See the promotion evidence contract.
• A subject-bound producer attestation establishes received CI evidence. A scan, a manually entered commit, an accepted job or a new user’s onboarding checklist does not establish completed delivery. Receipt, cryptographic verification, trust acceptance and decision replay have separate outcomes.

Design principles

• Digest-first releases: a release is an immutable set of OCI digests, never mutable tags. Tags are mutable; digests give a release an identity that survives audit.
• Deterministic replay: the same inputs yield the same outputs — stable ordering, canonical hashing, UTC timestamps.
• Evidence-linked decisions: each release decision must identify its recorded scan, approval and policy inputs. Missing material stays explicit; replay requires those historical inputs.
• Pluggable everything: integrations are plugins; the core orchestration engine is stable. Extensibility does not require core code changes.
• Offline-first: core workflows use local owners and packaged inputs. A disconnected profile must state unavailable inputs and prove the selected offline workflow; connectivity posture is not evidence that every operation is available.
• Explicit executor placement: agent capabilities support local and remote target operations. Executor placement, credentials and target prerequisites follow the selected Docker, Compose, SSH or WinRM profile; the word “agent” alone does not establish where a process runs.
• Compiled C# steps plus shell hooks: C# for complex orchestration; shell hooks for the simple cases, executed by the deployment agent under a timeout. The hook runner starts sh -c (or cmd.exe /c on Windows) as a child process with the agent’s own privileges — treat hook content as trusted input and keep it under the same review as deployment code.
• Commercial terms: the offer guide states the free-use limit and the subscription. No component enforces a licence term.

Deployment model and trust boundary

Stella Ops is self-hosted. Every service, the data plane it writes to, and the signing material it uses run inside the operator’s own boundary; there is no vendor-hosted control plane.

Inside that boundary Stella Ops supports multiple logical tenants — environments, business units, or logical scopes that share the same operator, security team, and incident-response authority. The current architecture does not support unrelated, mutually adversarial tenants on one shared deployment. See ADR-005; token-selection mechanics inside this posture are covered by ADR-002.

Trust zones, outside in:

Externally reachable services enforce token validation (short-lived, tenant-scoped), sender constraints where configured (DPoP / mTLS), scope-based authorization, and tenant filtering on data access. The deployment bundles under devops/ are the authoritative source for the concrete network layout of a given profile.

Detail: Security boundaries · Platform topology · Data isolation model · Port registry · Scopes and roles

System map

Service tiers

Ownership that is easy to get wrong:

• Ingress and routing — Router owns both the HTTP ingress gateway (StellaOps.Gateway.WebService) and the internal binary protocol transport.
• Promotion policy gates — Policy Engine owns policy evaluation; Release Orchestrator enforces approval, target readiness and dispatch rules. Vulnerabilities owns advisory/VEX ingestion; the carried Concelier and Excititor libraries are not independent decision authorities.
• Evidence custody — src/Evidence/ owns the current web/worker family and database. Residual Attestor/EvidenceLocker libraries and tests do not imply separate runtime owners. Signer remains outside this family.
• Environment topology and promotion lanes — owned by the Release Orchestrator, not Cartographer.

The full inventory, including which historical component names now run inside a parent service, is the generated service inventory, Module matrix and docs/modules/.

Capability areas

Capabilities are grouped into themes — functional labels used for orientation. The project layout under src/ is mapped separately, in the Platform component map.

Analysis and evidence

Release orchestration

The following is a dated capability inventory, not current end-to-end acceptance. Validate the selected installation through the core acceptance contract above; source, published images and deployed behavior can differ.

Data plane and required infrastructure

Required

• PostgreSQL — each service family owns one physical database and one role on the shared server. Web and worker roles of that family share it; sibling databases deny that role CONNECT. Services migrate their own schemas at startup and use owner APIs/events across the boundary. See ADR-039 and the database ownership matrix.
• Valkey — Redis-compatible cache and coordination substrate: DPoP nonces, streams and events, worker queues, tenant-prefixed caching, rate-limit counters.
• RustFS (or an equivalent S3-compatible store) — object storage for artifacts, bundles, and evidence. Append-only custody preserves recorded material; replay also requires the original inputs.

Profile-dependent infrastructure

• NATS JetStream — alternative messaging transport in some deployments; Valkey is the default.
• Transparency log services — a Rekor mirror and CA services where configured. A selected trust policy may require their proof material; missing required proof is not an implicit allow.

Detail: Infrastructure dependencies · Schema mapping · Data schemas

End-to-end flows

Vulnerability scanning

1. Advisory and VEX evidence enters through the Vulnerabilities hub’s carried connectors.
2. SBOM arrives from CLI/CI; Scanner deduplicates layers and enqueues work.
3. Analyzer bundle runs inside the Worker and stores evidence in content-addressed caches.
4. Policy Engine merges advisories, VEX, and inventory/usage facts; emits explain traces and stable dispositions.
5. Evidence and the configured signing provider produce the applicable attestation/proof material; Signer remains a separate key owner. Missing or failed proof stays visible.
6. Console / CLI / Export surface findings and package verifiable evidence; Notify emits digests and incidents.

Release orchestration

This is the required workflow; its complete positive and negative cases remain acceptance work.

1. CI publishes an immutable artifact and attributable build evidence through supported producers.
2. Scanner records scan attempts/results. Policy evaluates the exact subject using complete required inputs; absent or stale knowledge retains its configured non-success outcome.
3. Release Orchestrator binds component digests, source identity, target environment and policy version. Contributor ownership and approval authority are checked independently.
4. Promotion records its gate basis and approval result. Dispatch rechecks the owner’s current authorization, evidence and target prerequisites.
5. The executor reports target execution and health. The UI identifies the observer and keeps requested, accepted, running, partially failed and completed outcomes distinct.
6. Retry or rollback follows the existing authorized recovery path, retaining both the original failure and the recovery result with the target digest/configuration observations.
7. Evidence binds the exact finalized decision revision. Sealing failure remains a proof gap; recovery must not repeat deployment or introduce automatic rollback because proof is missing.
8. A separate reader exports and verifies the identified packet offline using its declared trust material. Decision replay requires its recorded inputs, pack and version.
9. Later advisory, VEX or runtime changes produce a current assessment and accountable action without rewriting the original release decision or proof.

Detail, including the per-hop sequence and where each hop persists state: Request and data flows · Data flows · End-to-end workflow flows

Signing, credentials, and anchored trust

• Identity — Authority issues short-lived, tenant-scoped tokens and rotates JWKS. Sender constraints (DPoP nonces, mTLS) are enforced where configured.
• Signing — Signer owns key custody/signing; the consolidated Evidence family assembles evidence bundles and can anchor them in a Rekor transparency log. A local mirror and retained proof material support verification in a disconnected profile; missing required material remains explicit.
• Key location — signing and verification keys are not baked into images and are not carried in the repository. A service reads its key at runtime from an environment variable or a mounted file, and fails closed when one is absent.
• Trust roots — issuer and KMS bindings are held in the Issuer Directory and distributed with the Offline Kit for air-gapped installs.
• Verification by the reader — supported evidence packets can be exported for external audit. Replay requires the recorded subject, policy version and inputs; a record without those inputs remains explicitly non-replayable. A successful root-hash comparison is not signature or trust verification.

Detail: Security hardening guide · Key rotation runbook · Verification key rotation · Attestor architecture · Signer architecture

Failure behaviour and recovery

• Gates fail closed. Promotion and deployment stop when release truth, approvals, or gate results are missing, rather than proceeding on an assumption.
• Failure domains follow the service boundary. Each service owns its physical database and work state. Required downstream failures can still block a release; availability of one service does not prove the complete journey. Symptom-to-action procedures per service live under docs/runbooks/general/.
• Backup and restore must cover the PostgreSQL cluster, the file-backed stores (including the Evidence object store and the timestamp authority’s state) and the installation files together: Backup and restore operations. The DevOps script backup.sh archives only the PostgreSQL, RustFS and Valkey volumes, and the release bundle ships no backup or restore tool; the other stores need the manual steps of the backup and restore drill. Run the drill on an authorized isolated installation. The program requires fresh restoration evidence before claiming the selected profile preserves its release, access and proof state.
• Upgrade and rollback run through Docker Compose or the Offline Kit, with signed release manifests, image-digest verification, service health checks, and a release evidence pack: Deployment upgrade and rollback runbook. A release-bundle installation upgrades in place with the newer bundle’s installer, which keeps .env values, adds the newer settings and provisions the databases a newer bundle adds (same runbook, “Release-bundle installations”); no upgrade of a real installation has been run yet. Database migrations are forward-only (ADR-004), so a rollback is a deployment operation, not a schema reversal.
• Trust-infrastructure disaster recovery — Rekor outage, key compromise, or a TUF repository failure: Disaster recovery guide.

Connected and air-gapped operation

The same deployment runs in three connectivity postures, and policy must stay compatible across all three:

In sealed mode OfflineKit carries the supported feeds, images, signatures and verification material. The release identity and authorization rules remain the same; input availability and recovery procedures depend on the packaged material. Authority and token verification remain local. Capabilities that genuinely differ between modes are enumerated rather than glossed over: see the degradation matrix.

Detail: Offline Kit · Air-gap overview · Air-gap operations runbook

Extension points

Integrations are plugins, and the evidence chain does not change when you add one.

• Scanner analyzers (restart-time plug-ins) for ecosystem-specific parsing and facts extraction.
• Concelier connectors for new advisory sources, preserving aggregation-only guardrails.
• Policy packs for organization-specific gating, waivers, and justifications.
• AI code guard evidence for AI-assisted code changes (Scanner evidence + Policy overrides).
• Export profiles for output formats and offline bundle shapes.

Plugins contribute through three surfaces:

1. Manifest — a static declaration of what the plugin provides (integrations, steps, agents, gates), signed and signature-verified before load.
2. Sandboxed runtime — plugins execute in a process sandbox behind a gRPC plugin bridge.
3. Execution contract — IExecutionPlugin capabilities registered through the agent’s execution plugin catalog for workflow and deployment steps.

Plugin types: integration connectors (SCM — Gitea, GitHub App, GitLab; CI — Jenkins; registry — Harbor, Nexus, Docker Registry; secrets — Vault, Consul), step providers, agent types for new deployment targets, and gate providers such as the reachability promotion gate. A traffic/router plugin interface is defined for progressive delivery; a real load-balancer data-plane integration is not claimed.

Detail: Plugin SDK guide

Where the detailed architecture lives