140 lines
6.6 KiB
Markdown
Executable File
140 lines
6.6 KiB
Markdown
Executable File
# 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`
|