git.stella-ops.org/docs/modules/graph/architecture-index.md

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.