docs re-org, audit fixes, build fixes

docs/ARCHITECTURE_REFERENCE.md

@@ -0,0 +1,118 @@
+# 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/`
+
+## 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/events/`
+
+## Related high-level docs
+
+- Product overview: `docs/overview.md`
+- Key features: `docs/key-features.md`
+- Roadmap (internal): `docs/ROADMAP.md`
+- Glossary: `docs/GLOSSARY.md`