# High-Level Architecture (Reference Map)

This document is the canonical index for StellaOps architecture.
It is intentionally a map, not a full re-statement of every module dossier.

If you want a short walkthrough, start with `docs/ARCHITECTURE_OVERVIEW.md`.

## How the docs are organized

StellaOps 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 (46 modules): `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-Tenant Policy Rollout, Exception Approval, Risk Score Dashboard |
| Offline & Specialized | Offline Sync, Reachability Drift Alert |

### 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 | 25 analyzers (11 language, 9 OS, 4 surface, 1 capability): `docs/technical/architecture/sbom-analyzer-inventory.md` |
| 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: `docs/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/modules/gateway/identity-header-policy.md`
- Authority service dossier: `docs/modules/authority/architecture.md`
- Claims and headers index: `docs/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/` |
| Scheduler Queue Chain | HLC-based enqueue with cryptographic linking | `docs/modules/scheduler/architecture.md` |
| Air-Gap Sync | Offline job merge using HLC total ordering | `docs/operations/airgap-operations-runbook.md` |
| Migration Guide | Enabling HLC ordering in existing deployments | `docs/modules/scheduler/hlc-migration-guide.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:
- Grafana dashboard: `devops/observability/grafana/hlc-queue-metrics.json`
- Alerting rules: `devops/observability/alerting/hlc-alerts.yaml`

## Data and schemas

Use these as the canonical map for schemas and contracts:
- Data schemas (high-level index): `docs/DATA_SCHEMAS.md`
- Database specifications: `docs/db/`
- Events (schemas + samples): `docs/modules/signals/events/`

## Related high-level docs

- Product overview: `docs/overview.md`
- Key features: `docs/key-features.md`
- Glossary: `docs/GLOSSARY.md`