Files

master 044cf0923c docs consolidation

2026-01-07 10:23:21 +02:00

5.4 KiB

Executable File

Raw Blame History

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