Architecture Overview (High-Level)

This document is the 10-minute tour of Stella Ops Suite: what the components are, how they fit together, and what “release control plane + security gates + evidence-linked decisions” means in practice.

Audience: anyone forming a first mental model of the platform — operators, integrators, and engineers. For the full reference map (services, boundaries, detailed flows), see ARCHITECTURE_REFERENCE.md.

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

Guiding Principles

• Digest-first releases: a release is an immutable set of OCI digests, never mutable tags.
• 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).
• Pluggable everything: integrations are plugins; the core orchestration engine is stable.
• Offline-first: all core operations work in air-gapped environments.
• No feature gating: all plans include all features; limits are environments + new digests/day.

Tenancy Model

Stella Ops supports multiple logical tenants inside one operator’s trust boundary. Tenants are 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 SaaS deployment. See ADR-005; token-selection mechanics inside this posture are covered by ADR-002.

System Map

Release-Centric Flow

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

Platform Themes

Stella Ops Suite organizes capabilities into themes (functional areas):

Analysis & Evidence Themes (Operational)

Release Orchestration Themes (Operational — residual gaps noted per theme)

Theme names and “Key Modules” are capability labels, not src/ project names (verified against src/ 2026-07-28). The release-control capability shipped in src/ReleaseOrchestrator/— the release-orchestrator and agent-core services in the default compose stack (devops/compose/docker-compose.stella-services.yml) — with the connector hub in src/Integrations/(integrations-web service) and plugin infrastructure in src/Plugin/. The code lives in StellaOps.ReleaseOrchestrator.* libraries and StellaOps.Agent.* agent projects, not under the label names below. docs/modules/README.md is the authoritative module inventory; residual runtime gaps are tracked in docs/modules/release-orchestrator/promotion-runtime-gap-closure-plan.md.

Service Tiers

Ownership Clarifications

• Ingress/routing: Router owns both the HTTP ingress gateway (StellaOps.Gateway.WebService) and the internal binary protocol transport. The standalone src/Gateway/ was deleted (Sprint 200).
• Promotion policy gates: Policy Engine owns PASS/FAIL decision semantics; Concelier remains ingestion/linkset only.
• Environment topology and promotion lanes: owned by Release Orchestrator ENVMGR/PROMOT tracks (not Cartographer).

See:

• docs/modules/router/architecture.md
• docs/modules/router/README.md
• docs/modules/policy/promotion-gate-ownership-contract.md
• docs/modules/release-orchestrator/promotion-runtime-gap-closure-plan.md

Infrastructure (What Is Required)

Required

• PostgreSQL: canonical persistent store for module schemas.
• Valkey: Redis-compatible cache/streams and DPoP nonce store.
• RustFS (or equivalent S3-compatible store): object storage for artifacts, bundles, and evidence.

Optional (deployment-dependent)

• NATS JetStream: optional messaging transport in some deployments.
• Transparency log services: Rekor mirror (and CA services) when transparency is enabled.

End-to-End Flows

Current: Vulnerability Scanning Flow

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/incidents.

Current: Release Orchestration Flow

1. CI pushes image to registry by digest; triggers webhook to Stella.
2. Stella scans the new digest and stores the verdict.
3. Release created bundling component digests with semantic version.
4. Promotion requested to move 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: security verdict, approval count, freeze windows, custom policies.
6. Decision record produced with evidence refs and signed.
7. Deployment executed via agent to target (Docker, Compose, SSH/WinRM; ECS and Nomad as built-in agent capabilities).
8. Version sticker written to target for drift detection.
9. Evidence packet sealed and stored.

Extension Points

Current Extension Points

• 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 and waivers/justifications.
• AI code guard evidence for AI-assisted code changes (Scanner evidence + Policy overrides).
• Export profiles for output formats and offline bundle shapes.

Three-Surface Plugin Model (Shipped)

Plugins contribute through three surfaces (all implemented in src/Plugin/ and consumed by the modules above):

1. Manifest (static declaration): what the plugin provides (integrations, steps, agents, gates), signed and signature-verified before load (StellaOps.Plugin.Abstractions)
2. Sandboxed runtime (dynamic execution): plugins run in a process sandbox with a gRPC plugin bridge (StellaOps.Plugin.Sandbox)
3. Execution plugin (execution contract): IExecutionPlugin capabilities registered through the agent’s ExecutionPluginCatalog for workflow/deployment steps

Plugin types:

• Integration connectors: SCM (Gitea, GitHub App, GitLab), CI (Jenkins), Registry (Harbor, Nexus, Docker Registry), secrets (Vault, Consul) — shipped as signed plugins
• Step providers: custom execution plugins for build/scan/deploy/verify steps
• Agent types: new deployment target types
• Gate providers: custom gate evaluations (e.g. the reachability promotion gate)
• Traffic/router plugins: interface defined for progressive delivery; a real load-balancer data-plane integration is not yet claimed

Offline & Sovereign Notes

• Offline Kit carries vulnerability feeds, container images, signatures, and verification material so the workflow stays identical when air-gapped.
• Authority + token verification remain local; quota enforcement is verifiable offline.
• Attestor can cache transparency proofs for offline verification.
• Evidence packets are exportable for external audit in air-gapped environments.
• All release decisions can be replayed with frozen inputs.

Key Architectural Decisions

References

• ARCHITECTURE_REFERENCE.md— Full reference map
• modules/release-orchestrator/architecture.md— Release orchestrator dossier (implemented; residual gaps in modules/release-orchestrator/promotion-runtime-gap-closure-plan.md)
• OFFLINE_KIT.md— Air-gap operations
• API_CLI_REFERENCE.md— API and CLI contracts
• modules/platform/architecture-overview.md— Platform service design
• modules/scanner/operations/ai-code-guard.md— AI code guard operations
• docs-archive/product/advisories/09-Jan-2026 - Stella Ops Orchestrator Architecture.md — Full orchestrator specification (archived)
• docs-archive/product/advisories/13-Jan-2026 - Controlled Conversational Interface.md — Controlled conversational interface guardrails and audit log (archived)