Platform topology (detailed)

Audience: operators and architects who need the layer-by-layer map of how Stella Ops services, clients, and infrastructure fit together. For module-specific detail (APIs, schemas, operations), see the dossiers under docs/modules/; for the full module inventory see the Module Matrix; for ports and hostnames see the Port Registry.

This document gives a comprehensive view of Stella Ops platform topology — the client layer, the gateway, the core engines, and the data plane they share. The ASCII diagrams below are deliberately retained as a fast visual reference; treat the prose tables as the authoritative companion.

Note on consolidated services. Several names in the diagrams below are historical sub-components that now run inside a parent service: the API gateway is hosted by Router (StellaOps.Gateway.WebService); Signer and Provenance run inside Attestor; Excititor and Feedser run inside Concelier; Scheduler and PacksRegistry run inside JobEngine. The diagrams keep the familiar names for orientation; the Module Matrix is the consolidated source of truth.

Component topology (quick reference)

CLIENT LAYER
├─ stella CLI                    → Gateway (JWT + DPoP auth)
├─ Web UI (Angular)              → Gateway (JWT + DPoP auth)
├─ CI/CD Pipelines               → Gateway (JWT + DPoP auth)
└─ Zastava Observer              → Scanner (runtime scans)

INFRASTRUCTURE (REQUIRED)
├─ PostgreSQL v16+               → Primary database (ALL services)
├─ Valkey v8.0                   → Cache, DPoP, queues, events
└─ RustFS                        → Object storage (S3 API)

INFRASTRUCTURE (OPTIONAL)
└─ NATS JetStream                → Alternative messaging (Valkey is default)

GATEWAY LAYER
└─ Gateway.WebService            → Auth, routing, rate limiting

AUTH & CRYPTO
├─ Authority                     → OAuth2/OIDC, OpTok issuance
├─ Signer                        → DSSE signing (FIPS/GOST/SM)
└─ Attestor                      → Rekor v2 transparency log

CORE ENGINES
├─ Scanner.WebService            → Scan orchestration
├─ Scanner.Worker                → Image analysis, SBOM generation
├─ Concelier.WebService          → Advisory ingestion (NVD, Red Hat, etc.)
├─ Excititor.WebService          → VEX ingestion + consensus (within Concelier)
├─ Policy.Engine                 → K4 lattice + ordered-gate evaluation
├─ Scheduler.WebService          → Re-scan orchestration (within JobEngine)
├─ Notify.WebService             → Notification orchestration
├─ Notify.Worker                 → Slack/Teams/Email delivery
└─ JobEngine.WebService          → DAG workflows, pack runs

SUPPORTING
└─ IssuerDirectory               → VEX issuer trust registry

Layers (tabular reference)

Layer	Primary components	Responsibility
Client	CLI, Web UI, CI/CD pipelines, runtime observers	Submit scan requests, query results, manage policy/tenancy.
Gateway	Gateway.WebService	Auth enforcement, tenant routing, rate limiting, request correlation, API routing.
Auth & crypto	Authority, Signer, Attestor, IssuerDirectory	Token issuance, signing, transparency/attestation workflows, issuer trust registry.
Core engines	Scanner, Concelier (incl. Excititor), Policy, JobEngine (incl. Scheduler), Notify	Scanning, ingestion, verdicts, orchestration, notifications, exports.
Data plane	PostgreSQL, Valkey, RustFS (S3), optional NATS	Persistent state, queues/streams, artifact storage, optional alternative messaging.

Service categories (detailed)

Category	Services	Purpose
Gateway	Gateway.WebService	API routing, auth enforcement
Auth & Security	Authority, Signer, Attestor	OAuth2, signing, transparency
Scanning	Scanner.Web, Scanner.Worker	Container analysis, SBOM
Advisory	Concelier.Web, Concelier.Worker	Vulnerability ingestion
VEX	Excititor.Web, Excititor.Worker	Exploitability statements
Policy	Policy.Engine	K4 lattice + ordered-gate evaluation (see Policy Engine Data Pipeline)
Orchestration	JobEngine (Scheduler, pack runs)	Job coordination
Notifications	Notify.Web, Notify.Worker	Delivery to Slack/Teams/Email

Layered architecture diagram

┌─────────────────────────────────────────────────────────────────────┐
│                      USER EXPERIENCE                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │   Gateway    │  │  Web (UI)    │  │     CLI      │              │
│  │ (API Router) │  │ (Angular 21) │  │(Multi-plat)  │              │
│  └──────────────┘  └──────────────┘  └──────────────┘              │
└─────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│                   DATA & EXPORT                                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │ExportCenter  │  │EvidenceLocker│  │FindingsLedger│              │
│  │(SARIF/SBOM)  │  │(Artifacts)   │  │(Audit Trail) │              │
│  └──────────────┘  └──────────────┘  └──────────────┘              │
└─────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│                  EVENTS & NOTIFICATIONS                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │   Notify     │  │   Notifier   │  │TimelineIndex │              │
│  │(Orchestrate) │  │  (Delivery)  │  │  (Events)    │              │
│  └──────────────┘  └──────────────┘  └──────────────┘              │
└─────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│                   ORCHESTRATION & WORKFLOW                           │
│  ┌──────────────┐  ┌──────────────┐                                │
│  │ Scheduler    │  │ Orchestrator │                                │
│  │(Job Sched)   │  │(Coordinator) │                                │
│  └──────────────┘  └──────────────┘                                │
└─────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      SCANNING & ANALYSIS                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │Scanner.Web   │  │Scanner.Worker│  │ AdvisoryAI   │              │
│  │(API/Control) │  │(Analyzers)   │  │(ML Analysis) │              │
│  └──────────────┘  └──────────────┘  └──────────────┘              │
│  ┌──────────────┐  ┌──────────────┐                                 │
│  │ RiskEngine   │  │    Policy    │                                 │
│  │  (Scoring)   │  │   (Engine)   │                                 │
│  └──────────────┘  └──────────────┘                                 │
└─────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    INGESTION & AGGREGATION                           │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │  Concelier   │  │   Excititor  │  │IssuerDirectry│              │
│  │(Advisories)  │  │    (VEX)     │  │(CSAF Pubshrs)│              │
│  └──────────────┘  └──────────────┘  └──────────────┘              │
└─────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│                     AUTHENTICATION & SIGNING                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │  Authority   │─▶│    Signer    │─▶│   Attestor   │              │
│  │ (OAuth2/OIDC)│  │(DSSE/PKIX)   │  │(in-toto/DSSE)│              │
│  └──────────────┘  └──────────────┘  └──────────────┘              │
└─────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│                        INFRASTRUCTURE LAYER                          │
│  ┌──────────────────┐  ┌──────────────────┐  ┌─────────────────┐   │
│  │   PostgreSQL     │  │     Valkey       │  │     RustFS      │   │
│  │   (v16+ ONLY)    │  │  (Redis-compat)  │  │  (S3-like API)  │   │
│  │                  │  │   - Caching      │  │  - Artifacts    │   │
│  │ All services use │  │   - DPoP nonces  │  │  - SBOMs        │   │
│  │ PostgreSQL for   │  │   - Event queues │  │  - Signatures   │   │
│  │ persistent data  │  │   - Rate limiting│  │                 │   │
│  └──────────────────┘  └──────────────────┘  └─────────────────┘   │
│                                                                      │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │ Optional: NATS JetStream (alternative transport for queues)  │   │
│  │           Only used if explicitly configured in appsettings  │   │
│  └──────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘

Notes

Module dossiers live under docs/modules/<module>/architecture.md.
Deployment defaults (ports, profile overlays, pinned digests) live under devops/compose/, devops/helm/, and deploy/releases/.
PostgreSQL is the single primary datastore for all services; Valkey is the default transport, cache, and DPoP store; RustFS (S3 API) holds artifacts. NATS JetStream is an optional alternative messaging transport, used only when explicitly configured.