49 lines
2.7 KiB
Markdown
49 lines
2.7 KiB
Markdown
# 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.
|