# Platform topology (detailed)

This document provides a comprehensive view of StellaOps platform topology. For module-specific details (APIs, schemas, operations), see `docs/modules/`.

## 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
├─ Policy.Gateway                → OPA/Rego policy evaluation
├─ Scheduler.WebService          → Re-scan orchestration
├─ Notify.WebService             → Notification orchestration
├─ Notify.Worker                 → Slack/Teams/Email delivery
└─ Orchestrator.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, Excititor, Policy, Scheduler, Notify, Orchestrator | 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.Gateway, Policy Engine | OPA/Rego evaluation |
| **Orchestration** | Scheduler, Orchestrator | Job coordination |
| **Notifications** | Notify.Web, Notify.Worker | Delivery to Slack/Teams/Email |

## Layered architecture diagram

```
┌─────────────────────────────────────────────────────────────────────┐
│                      USER EXPERIENCE                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │   Gateway    │  │  Web (UI)    │  │     CLI      │              │
│  │ (API Router) │  │ (Angular v17)│  │(Multi-plat)  │              │
│  └──────────────┘  └──────────────┘  └──────────────┘              │
└─────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│                   DATA & EXPORT                                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │ExportCenter  │  │EvidenceLocker│  │FindingsLedger│              │
│  │(SARIF/SBOM)  │  │(Artifacts)   │  │(Audit Trail) │              │
│  └──────────────┘  └──────────────┘  └──────────────┘              │
└─────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│                  EVENTS & NOTIFICATIONS                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │   Notify     │  │   Notifier   │  │TimelineIndex │              │
│  │(Slack/Teams) │  │  (Advanced)  │  │  (Events)    │              │
│  └──────────────┘  └──────────────┘  └──────────────┘              │
└─────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│                   ORCHESTRATION & WORKFLOW                           │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │ Scheduler    │  │ Orchestrator │  │ TaskRunner   │              │
│  │(Job Sched)   │  │(Coordinator) │  │(Executor)    │              │
│  └──────────────┘  └──────────────┘  └──────────────┘              │
└─────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      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 `deploy/` (`deploy/compose/`, `deploy/helm/`, `deploy/releases/`).