# Graph Module · Architecture Index

Status: Draft (2025-11-26) — aligns with Sprint 0141 (Graph Indexer) and Sprint 0207 (Graph API).

## 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 stored separately (`graph_overlays_cache`) to avoid mutating historical snapshots.

## 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) → cached per node in `graph_overlays_cache`.
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
- 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`.
- Saved queries and snapshots exposed through Graph API; RBAC scopes enforced (`graph:read/query/export`).
- Health check: `/healthz` (200 when service ready).
See also `docs/api/graph.md` (pending) for full endpoint parameters and error envelopes.

## 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.