StellaOps Architecture Overview

Ownership: Architecture Guild • Docs Guild Audience: Service owners, platform engineers, solution architects Related: High-Level Architecture, Concelier Architecture, Policy Engine Architecture, Aggregation-Only Contract

This dossier summarises the end-to-end runtime topology of the Stella Ops release control plane after the Aggregation-Only Contract (AOC) rollout. It highlights where raw facts live, how ingest services enforce guardrails, and how downstream components consume those facts to derive policy decisions and user-facing experiences. Read it as the starting map before diving into the module-specific dossiers linked from §6.

Orientation & further reading

1 · System landscape

graph TD
    subgraph Edge["Clients & Automation"]
        CLI[stella CLI]
        UI[Console SPA]
        APIClients[CI / API Clients]
    end
    Gateway[API Gateway
(JWT + DPoP scopes)]
    subgraph Scanner["Fact Collection"]
        ScannerWeb[Scanner.WebService]
        ScannerWorkers[Scanner.Workers]
        Agent[Agent Runtime]
    end
    subgraph Ingestion["Aggregation-Only Ingestion (AOC)"]
        Concelier[Concelier.WebService]
        Excititor[Excititor.WebService]
        RawStore[(PostgreSQL
advisory_raw / vex_raw)]
    end
    subgraph Derivation["Policy & Overlay"]
        Policy[Policy Engine]
        Scheduler[Scheduler Services]
        Notify[Notifier]
    end
    subgraph Experience["UX & Export"]
        PlatformSvc[Platform Service
(Console Backend)]
        Exporters[Export / Offline Kit]
    end
    Observability[Telemetry Stack]

    CLI --> Gateway
    UI --> Gateway
    APIClients --> Gateway
    Gateway --> ScannerWeb
    ScannerWeb --> ScannerWorkers
    ScannerWorkers --> Concelier
    ScannerWorkers --> Excititor
    Concelier --> RawStore
    Excititor --> RawStore
    RawStore --> Policy
    Policy --> Scheduler
    Policy --> Notify
    Policy --> PlatformSvc
    Scheduler --> PlatformSvc
    PlatformSvc --> Exporters
    Exporters --> CLI
    Exporters --> Offline[Offline Kit]
    Observability -.-> ScannerWeb
    Observability -.-> Concelier
    Observability -.-> Excititor
    Observability -.-> Policy
    Observability -.-> Scheduler
    Observability -.-> Notify

Platform Service (StellaOps.Platform.WebService) aggregates cross-service status for the Console UI (health, quotas, onboarding, preferences, global search) and does not mutate raw evidence. Pack22 environment posture surfaces also consume Platform v2 read-model adapters, including /api/v2/evidence/packs, with comma-delimited region and environment scope sets preserved end to end so multi-select Console context is not collapsed by the backend.

Key boundaries:

2 · Aggregation-Only Contract focus

2.1 Responsibilities at the boundary

AreaServicesResponsibilities under AOCForbidden under AOC
Ingestion (Concelier / Excititor)StellaOps.Concelier.WebService, StellaOps.Excititor.WebServiceFetch upstream advisories/VEX, verify signatures, compute linksets, append immutable documents to advisory_raw / vex_raw, emit observability signals, expose raw read APIs.Computing severity, consensus, suppressions, or policy hints; merging upstream sources into a single derived record; mutating existing documents.
Policy & OverlayStellaOps.Policy.Engine, SchedulerJoin SBOM inventory with raw advisories/VEX, evaluate policies, issue effective_finding_* overlays, drive remediation workflows.Writing to raw collections; bypassing guard scopes; running without recorded provenance.
Experience layersConsole, CLI, ExportersSurface raw facts + policy overlays; run stella aoc verify; render AOC dashboards and reports.Accepting ingestion payloads that lack provenance or violate guard results.

2.2 Raw stores

CollectionPurposeKey fieldsNotes
advisory_rawImmutable vendor/ecosystem advisory documents._id, tenant, source.*, upstream.*, content.raw, linkset, supersedes.Idempotent by (source.vendor, upstream.upstream_id, upstream.content_hash).
vex_rawImmutable vendor VEX statements.Mirrors advisory_raw; identifiers.statements summarises affected components.Maintains supersedes chain identical to advisory flow.
Logical replication (advisory_raw_stream, vex_raw_stream)Feed Policy Engine and Scheduler.operationType, documentKey, fullDocument, tenant, traceId.Scope filtered per tenant before delivery.

2.3 Guarded ingestion sequence

sequenceDiagram
    participant Upstream as Upstream Source
    participant Connector as Concelier/Excititor Connector
    participant Guard as AOCWriteGuard
    participant PG as PostgreSQL (advisory_raw / vex_raw)
    participant Stream as Logical Replication
    participant Policy as Policy Engine

    Upstream-->>Connector: CSAF / OSV / VEX document
    Connector->>Connector: Normalize transport, compute content_hash
    Connector->>Guard: Candidate raw doc (source + upstream + content + linkset)
    Guard-->>Connector: ERR_AOC_00x on violation
    Guard->>PG: Append immutable row (with tenant & supersedes)
    PG-->>Stream: Replication event (tenant scoped)
    Stream->>Policy: Raw delta payload
    Policy->>Policy: Evaluate policies, compute effective findings

2.4 Authority scopes & tenancy

ScopeHolderPurposeNotes
advisory:ingest / vex:ingestConcelier / Excititor collectorsAppend raw documents through ingestion endpoints.Paired with tenant claims; requests without tenant are rejected.
advisory:read / vex:readDevOps verify identity, CLIRun stella aoc verify or call /aoc/verify.Read-only; cannot mutate raw docs.
effective:writePolicy EngineMaterialise effective_finding_* overlays.Only Policy Engine identity may hold; ingestion contexts receive ERR_AOC_006 if they attempt.
findings:readConsole, CLI, exportsConsume derived findings.Enforced by Gateway and downstream services.

3 · Data & control flow highlights

  1. Ingestion: Concelier / Excititor connectors fetch upstream documents, compute linksets, and hand payloads to AOCWriteGuard. Guards validate schema, provenance, forbidden fields, supersedes pointers, and append-only rules before writing to PostgreSQL.
  2. Verification: stella aoc verify (CLI/CI) and /aoc/verify endpoints replay guard checks against stored documents, mapping ERR_AOC_00x codes to exit codes for automation.
  3. Policy evaluation: PostgreSQL logical replication delivers tenant-scoped raw deltas. Policy Engine joins SBOM inventory (via BOM Index), executes deterministic policies, writes overlays, and emits events to Scheduler/Notify.
  4. Experience surfaces: Console renders an AOC dashboard showing ingestion latency, guard violations, and supersedes depth. CLI exposes raw-document fetch helpers for auditing. Offline Kit bundles raw collections alongside guard configs to keep air-gapped installs verifiable.
  5. Observability: All services emit ingestion_write_total, aoc_violation_total{code}, ingestion_latency_seconds, and trace spans ingest.fetch, ingest.transform, ingest.write, aoc.guard. Logs correlate via traceId, tenant, source.vendor, and content_hash.

3.1 Scanner events lane (Sprint 20260530.022)

Decision: Option (ii). SCANNER__EVENTS__ENABLED is the optional scanner-to-Platform analytics lane, not the writer path for the dossier tables (scanner.scans, scanner.scan_findings, concelier.sbom_documents, findings.findings_projection_default, or release_orchestrator.releases). Those tables are populated by their synchronous owning services.

When enabled, Scanner WebService publishes report-ready / scan-completed envelopes to orchestrator:events, the stream consumed by Platform AnalyticsIngestionService. The scanner default, compose fallback, and shipped env samples use orchestrator:events so enabling the flag does not write to an unread stella.events stream. Operators may still override SCANNER_EVENTS_STREAM, but doing so must be paired with a matching Platform analytics Streams.ScannerStream override.

4 · Offline & disaster readiness

5 · Replay CAS & deterministic bundles

6 · References

7 · Compliance checklist

Last updated: 2026-01-05.