Graph Module · Architecture Index

Status: Draft (2025-11-26) — PARTIALLY SUPERSEDED. This was a planning-era index. Where it disagrees with architecture.md, architecture.md wins — it is the reconciled deep dive and the only Graph doc kept current against src/. Known corrections applied 2026-07-12 are marked inline; the roadmap/event names below were not re-verified and may name surfaces that were never built.

Data model (canonical)

• Nodes/edges follow docs/modules/graph/schema.md.
• Tenancy: every node/edge/snapshot/event carries tenant.
• Snapshots: immutable bundles of nodes + edges. Overlays are not persisted: there is no graph_overlays_cache table (corrected 2026-07-12 — it never existed in src/; only the in-memory counters graph_overlay_cache_hits_total / _misses_total do). Overlays are computed inline in a Testing host and return 501 GRAPH_FEATURE_UNAVAILABLE otherwise, pending a durable overlay backend — see architecture.md §1/§3.1.

Ingestion pipeline

1. SBOM snapshots from SBOM Service → Graph Indexer (graph_snapshots, graph_nodes, graph_edges).
2. Advisory/VEX from Concelier/Excititor → edges and overlay seeds.
3. Policy overlays from Policy Engine (POLICY-ENGINE-30-001…003) → computed per node (no overlay cache table ships today; see the correction above).
4. Runtime/signals (future) → additional edges/attributes; stored alongside snapshot edges with tenant guard.

Overlays & caches

• Overlay types: policy (policy.overlay.v1), vex (openvex.v1), analytics (clusters/centrality).
• Cache TTL: 5–10 minutes recommended; deterministic IDs (SHA256 over tenant|node|kind).
• Analytics overlays emitted as NDJSON (overlays/clusters.ndjson, overlays/centrality.ndjson) with stable ordering.

Events & change streams

Draft-era names, not re-verified against src/(e.g. advisory.observation.updated@1 predates the consolidation). Trust architecture.md and the emitting code over this list.

• Inputs: sbom.snapshot.created, advisory.observation.updated@1, sbom.version.created, sbom.asset.updated.
• Outputs: Graph Indexer change-stream/backfill emits node/edge upserts and overlay refresh notifications for Graph API caches.
• Downstream consumers: Scheduler (recompute jobs), Graph API (query caches), Export Center (offline bundles).

APIs (reader surfaces)

• Graph API (Sprint 0207): /graph/search, /graph/query, /graph/paths, /graph/diff, /graph/export. Note: /graph/query, /graph/paths and /graph/export return 501 outside a Testing host today — see architecture.md §3.1 for the shipped-vs-501 map.
• Saved queries and snapshots exposed through Graph API; RBAC scopes enforced (graph:read/query/export).
• Health check: /healthz (200 when service ready). Full endpoint parameters and error envelopes live in architecture.md§3 — there is no docs/api/graph.md (the draft-era pointer to one was never built; corrected 2026-07-12).

Observability (current metrics)

• graph_tile_latency_seconds{route}
• graph_query_budget_denied_total{reason}
• graph_overlay_cache_hits_total, graph_overlay_cache_misses_total
• graph_export_latency_seconds{format}
• Ingest/backfill metrics live in Indexer (Sprint 0141).

Offline / bundles

• Exports: deterministic NDJSON (nodes.jsonl, edges.jsonl, overlays) with SHA256 manifest and optional DSSE.
• Air-gap friendly: no external calls; rely on cached schemas and local snapshots.

References

• architecture.md — deep dive.
• implementation_plan.md — roadmap and risks.
• schema.md — canonical node/edge shapes.
• docs/implplan/SPRINT_0141_0001_0001_graph_indexer.md — Indexer sprint.
• docs/implplan/SPRINT_0207_0001_0001_graph.md — Graph API sprint.