# Architecture Overview (High-Level)

This document is a high-level orientation to StellaOps: what components exist, how they fit together, and what "offline-first + deterministic + evidence-linked decisions" means in practice.

For the full reference map (services, boundaries, detailed flows), see `docs/07_HIGH_LEVEL_ARCHITECTURE.md`.

## Guiding Principles

- **SBOM-first:** scan and reason over SBOMs; fall back to unpacking only when needed.
- **Deterministic replay:** the same inputs yield the same outputs (stable ordering, canonical hashing, UTC timestamps).
- **Evidence-linked decisions:** policy decisions link back to specific evidence artifacts (SBOM slices, advisory/VEX observations, reachability proofs, attestations).
- **Aggregation-not-merge:** upstream advisories and VEX are stored and exposed with provenance; conflicts are visible, not silently collapsed.
- **Offline-first:** the same workflow runs connected or air-gapped via Offline Kit snapshots and signed bundles.

## System Map (What Runs)

At a high level, StellaOps is a set of services grouped by responsibility:

- **Identity and authorization:** Authority (OIDC/OAuth2, scopes/tenancy)
- **Scanning and SBOM:** Scanner WebService + Worker (facts generation)
- **Advisories:** Concelier (ingest/normalize/export vulnerability sources)
- **VEX:** Excititor + VEX Lens (VEX observations/linksets and exploration)
- **Decisioning:** Policy Engine surfaces (lattice-style explainable policy)
- **Signing and transparency:** Signer + Attestor (DSSE/in-toto and optional transparency)
- **Orchestration and delivery:** Scheduler, Notify, Export Center
- **Console:** Web UI for operators and auditors

## 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 Flow (Typical)

1. **Ingest evidence sources:** Concelier and Excititor ingest upstream advisories/VEX into immutable observations with provenance.
2. **Scan:** Scanner accepts an SBOM or image reference, produces scan facts and evidence artifacts.
3. **Decide:** Policy evaluation merges scan facts with advisory/VEX evidence to produce an explainable verdict.
4. **Seal:** Signer/Attestor wrap outputs into signed bundles (DSSE/in-toto) and optionally anchor in transparency logs.
5. **Export and notify:** Export Center produces portable evidence bundles and Offline Kit material; Notify delivers digests/incidents.
6. **Operate:** Console exposes triage, explainability, verification, and governance workflows.

## Extension Points (Where You Customize)

- **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.
- **Export profiles** for output formats and offline bundle shapes.

## References

- `docs/07_HIGH_LEVEL_ARCHITECTURE.md`
- `docs/24_OFFLINE_KIT.md`
- `docs/09_API_CLI_REFERENCE.md`
- `docs/modules/platform/architecture-overview.md`