Architecture Overview (High-Level)

This document is the current architecture of Stella Ops Suite: where it sits, what runs, what talks to what, where the trust boundaries are, and how it behaves when something fails.

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 your CI and your runtime targets, governs promotion across environments, enforces security and policy gates, and produces verifiable evidence for every release decision.

CI Build → Registry → Stella (Scan + Release + Promote + Gate + Deploy) → Targets → Evidence

Build → Scan → Create Release → Request Promotion → Gate Evaluation → Deploy → Evidence
        ↑                              ↓
        └── Re-evaluate on CVE Updates ┘

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: every release decision links to concrete evidence artifacts (scan verdicts, approvals, policy evaluations), packaged so the decision can be replayed later.
• Pluggable everything: integrations are plugins; the core orchestration engine is stable. Extensibility does not require core code changes.
• Offline-first: all core operations work in air-gapped environments.
• Agentless execution toward targets: deployment reaches Docker, Compose, SSH and WinRM targets from the Stella side. Nothing is installed on the target hosts. “Agent” in this codebase means the executor service that runs inside your own Stella installation (StellaOps.Agent.Host, which registers the SSH and WinRM capabilities) — not software placed on the machines being deployed to.
• 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.
• No feature gating: all plans include all features; limits are environments + new digests/day.

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 PASS/FAIL decision semantics; Concelier remains ingestion and linkset only.
• 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 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

Data plane and required infrastructure

Required

• PostgreSQL — canonical persistent store. Each service owns a schema, which is what makes the ownership boundary and the tenant-isolation strategy enforceable rather than conventional.
• 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. Evidence stores are append-only, which is what keeps a verdict replayable.

Optional, and deliberately never load-bearing for core flows

• NATS JetStream — alternative messaging transport in some deployments; Valkey is the default.
• Transparency log services — a Rekor mirror, and CA services, when transparency is enabled.

Detail: Infrastructure dependencies · Schema mapping · Data schemas

End-to-end flows

Vulnerability scanning

1. Evidence enters via Concelier and Excititor connectors (Aggregation-Only Contract).
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. Signer + Attestor wrap outputs into DSSE bundles and, optionally, anchor them in a Rekor mirror.
6. Console / CLI / Export surface findings and package verifiable evidence; Notify emits digests and incidents.

Release orchestration

1. CI pushes an image to the registry by digest; a webhook triggers Stella.
2. Stella scans the new digest and stores the verdict.
3. Release created, bundling component digests with a semantic version.
4. Promotion requested to move the release from Dev → Stage → Prod. The promote and deploy paths fail closed when release truth, approvals, or gate results are missing.
5. Gate evaluation checks the security verdict, approval count, freeze windows, and custom policies.
6. Decision record produced with evidence references, and signed.
7. Deployment executed via an agent to the target (Docker, Compose, SSH/WinRM; ECS and Nomad as built-in agent capabilities).
8. Version sticker written to the target for drift detection.
9. Evidence packet sealed and stored.

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 produces DSSE signatures; Attestor assembles evidence bundles and can anchor them in a Rekor transparency log. Under air-gap the mirror is local, and Attestor can cache transparency proofs so verification still works.
• 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 — evidence packets are exportable for external audit, and every release decision can be replayed with frozen inputs.

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 own schema and its own queues, so a stalled worker or an unavailable connector degrades one capability rather than the control plane. Symptom-to-action procedures per service live under docs/operations/runbooks/.
• Backup and restore cover the PostgreSQL state volume, the object store, and Valkey, using shipped tooling: Backup and restore operations. The restore path is exercised as a drill — wipe the state, restore the backup, confirm no loss — in the PostgreSQL backup + restore drill.
• 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. 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 the Offline Kit carries vulnerability feeds, container images, signatures, and verification material, so the workflow is identical to the connected one. 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