Architecture Reference (Map)
This document is the canonical index into the Stella Ops architecture. It is intentionally a map — a curated set of pointers into the authoritative views, module dossiers, flows, and schemas — not a full re-statement of every dossier.
Audience: engineers and operators who already know what Stella Ops is and need to find the authoritative source for a specific subsystem, contract, or flow.
If you want a short walkthrough instead, start with ARCHITECTURE_OVERVIEW.md(a 10-minute tour).
How the docs are organized
Stella Ops documentation is two-level:
- High-level, canonical docs live in
docs/*.md. - Detailed references live under
docs/**(module dossiers, API contracts, runbooks, schemas).
Entry points:
- Full technical index:
docs/technical/README.md - Platform architecture index:
docs/technical/architecture/README.md
Guiding principles (stable)
- Deterministic outputs: stable ordering, stable identifiers, UTC ISO-8601 timestamps, canonical hashing where applicable.
- Offline-first posture: the workflow must run connected or air-gapped using Offline Kit bundles and locally verifiable signatures.
- Evidence-linked decisions: every decision should link back to concrete evidence (SBOMs, observations, reachability, attestations).
- Aggregation-not-merge for upstream evidence: preserve provenance and conflicts rather than silently collapsing them.
Architecture views (authoritative)
These documents are the authoritative detailed views used by module dossiers and runbooks:
- Platform topology:
docs/technical/architecture/platform-topology.md - Infrastructure dependencies:
docs/technical/architecture/infrastructure-dependencies.md - Request and data flows:
docs/technical/architecture/request-flows.md - Data isolation model:
docs/technical/architecture/data-isolation.md - Security boundaries:
docs/technical/architecture/security-boundaries.md
User-centric architecture views
These documents provide end-to-end views from the user’s perspective:
- User flows (UML diagrams):
docs/technical/architecture/user-flows.md - Complete module matrix:
docs/technical/architecture/module-matrix.md - Data flows (SBOM/Policy/VEX lifecycles):
docs/technical/architecture/data-flows.md - Schema mapping (PostgreSQL/Valkey/RustFS):
docs/technical/architecture/schema-mapping.md
End-to-end workflow flows
Comprehensive flow documentation covering 16 major workflows: docs/flows/
| Category | Flows |
|---|---|
| Core Platform | Dashboard, Scan Submission, SBOM Generation, Policy Evaluation, Notification, Export |
| CI/CD & Automation | CI/CD Gate, Advisory Drift Re-scan, VEX Auto-Generation |
| Evidence & Compliance | Evidence Bundle Export, Binary Delta Attestation |
| Enterprise | Multi-Environment Policy Rollout, Exception Approval, Risk Score Dashboard |
| Offline & Specialized | Offline Sync, Reachability Drift Alert |
Note: “Multi-Environment” means multiple environments or logical scopes under one operator trust boundary. It does not mean multi-tenant SaaS hosting for unrelated tenants; see ADR-005.
Policy engine data pipeline
Comprehensive documentation of how evidence feeds policy decisions:
| Document | Description |
|---|---|
| Policy Engine Data Pipeline | Master data flow diagram: docs/technical/architecture/policy-engine-data-pipeline.md |
| SBOM Analyzer Inventory | analyzer families (language / OS / surface / capability) — see docs/technical/architecture/sbom-analyzer-inventory.md for the authoritative count (a hardcoded total here rots; §modules README warns these counts are illustrative) |
| Runtime Agents Architecture | eBPF, Zastava, signal processing: docs/technical/architecture/runtime-agents-architecture.md |
| Call Graph Analysis | ReachGraph, BFS, 8-state reachability: docs/technical/architecture/call-graph-analysis.md |
| Confidence Scoring | 5-factor weighted scoring (archived — superseded by 6-dimension EWS): docs-archive/technical/architecture/confidence-scoring.md |
| K4 Lattice Logic | Four-valued logic for uncertainty: docs/technical/architecture/k4-lattice-logic.md |
Modules (authoritative dossiers)
The per-module dossiers (architecture + implementation plan + operations) are indexed here:
- Module documentation index:
docs/modules/README.md - Technical architecture index:
docs/technical/architecture/README.md - Platform Service (Console aggregation):
docs/modules/platform/platform-service.md
Use module dossiers as the source of truth for:
- APIs and storage schemas owned by the module
- lifecycle, trust boundaries, and failure modes
- determinism rules and offline expectations
Identity, tenancy, and headers
Tenancy and identity context are part of the platform contract:
- Gateway tenant auth and ABAC contract:
docs/api/gateway/tenant-auth.md - Gateway identity header policy (spoofing prevention + migration rules):
docs-archive/modules/gateway/identity-header-policy.md - Authority service dossier:
docs/modules/authority/architecture.md - Claims and headers index:
docs/product/claims-index.md
APIs and CLI reference
Canonical entry points:
- API and CLI reference hub:
docs/API_CLI_REFERENCE.md - API conventions (headers, errors, pagination, determinism):
docs/api/overview.md - API contracts and samples:
docs/api/ - CLI command guides:
docs/modules/cli/guides/commands/
Offline, verification, and operations
Canonical entry points:
- Offline Kit:
docs/OFFLINE_KIT.md - Security hardening:
docs/SECURITY_HARDENING_GUIDE.md - Installation guide:
docs/INSTALL_GUIDE.md - Ops and runbooks:
docs/operations/,docs/modules/*/operations/
Hybrid Logical Clock (HLC) Ordering
StellaOps uses Hybrid Logical Clocks for audit-safe job queue ordering:
| Component | Description | Documentation |
|---|---|---|
| HLC Library | Core HLC timestamp and clock implementation | src/__Libraries/StellaOps.HybridLogicalClock/ |
| JobEngine Queue Chain | HLC-based enqueue with cryptographic linking | docs/modules/jobengine/architecture.md (Scheduler subsystem) |
| Air-Gap Sync | Offline job merge using HLC total ordering | docs/operations/airgap-operations-runbook.md |
| Status & Timeline CLI | Query HLC chain state and ordering from the CLI | docs/features/checked/cli/hlc-status-and-timeline-query-cli-commands.md |
| Troubleshooting | HLC-specific issue resolution | docs/operations/runbooks/hlc-troubleshooting.md |
Key concepts:
- HLC Timestamp: Tuple of
(PhysicalTime, LogicalCounter, NodeId)for total ordering - Chain Linking: Each job links to its predecessor via cryptographic hash
- Batch Snapshots: Periodic DSSE-signed proofs of chain state
- Deterministic Merge: Offline nodes can merge jobs in correct HLC order
Metrics and observability:
- No Grafana dashboard and no Prometheus alert rules ship for HLC. (
devops/observability/contains onlygrafana/canary.json+grafana/provisioning/; there is noalerting/directory anywhere underdevops/, and nohlc-*asset. Two files previously listed here —hlc-queue-metrics.jsonandhlc-alerts.yaml— never existed.) - The HLC/scheduler metric instruments are declared on the
StellaOps.Scheduler.HlcQueuemeter (src/JobEngine/StellaOps.Scheduler.__Libraries/StellaOps.Scheduler.Queue/Metrics/HlcSchedulerMetrics.cs:20) but are declared-but-unrecorded — no code path calls their recorders today, so the counters and histograms emit nothing at runtime. Alert names referenced in the runbook are condition labels, not wired alerts. - Canonical, verified breakdown of declared-vs-emitted metrics and the manual investigation steps that replace them:
docs/operations/runbooks/hlc-troubleshooting.md(“Metrics reference”).
Data and schemas
Use these as the canonical map for schemas and contracts:
- Data schemas (high-level index):
docs/technical/DATA_SCHEMAS.md - Database specifications:
docs/db/ - Events (schemas + samples):
docs/modules/signals/events/
Related high-level docs
- Architecture overview (10-minute tour):
ARCHITECTURE_OVERVIEW.md - Product overview:
overview.md - Key features:
key-features.md - Feature matrix (tier-by-tier):
FEATURE_MATRIX.md - API and CLI reference:
API_CLI_REFERENCE.md - Glossary:
GLOSSARY.md