Graph Architecture

Verified against commit 942a18727c on 2026-09-26 (UTC). Re-verify: git grep -n "AddHostedService\|AddReachGraphApplication\|SnapshotGraphChangeSource" -- src/Graph and ls src/Graph/__Libraries/StellaOps.Graph.Persistence/Migrations.

Graph owns the tenant-scoped dependency and service graph, the asset registry and the reachability store. src/ is the source of truth; where this document and the code disagree, the code wins.

1. Components

src/Graph/
  StellaOps.Graph.Api/                  # the one host (graph-api): Program.cs, Endpoints/, Hosting/, Security/, Services/
  StellaOps.Graph.Indexer/              # library composed by graph-api: Ingestion/, Analytics/, Incremental/, Assets/, Retention/
  __Libraries/
    StellaOps.Graph.Contracts/          # wire contracts (asset-registry event feed)
    StellaOps.Graph.Indexer.Persistence/# Postgres repositories for the Indexer (no migrations registered by graph-api)
    StellaOps.Graph.Persistence/        # the consolidated migration authority (graph + reachgraph schemas)
    StellaOps.Graph.Operations/         # schema topology and Doctor checks
    StellaOps.ReachGraph.Application/   # reachability controllers and services lifted from reachgraph-web
  __Tests/
src/__Libraries/StellaOps.ReachGraph*/  # shared reachability model, hashing, serialization, cache, persistence

graph-api composes everything in src/Graph/StellaOps.Graph.Api/Program.cs. There is no separate Indexer or ReachGraph process.

2. Request path, identity and scopes

• Requests arrive through the Router (AddRouterMicroservice, consumer group graph in the bundle) or directly on the service aliases.
• Security/GraphHeaderAuthenticationHandler.cs authenticates only from an already-authenticated principal (the Router dispatch path) or a gateway-signed identity envelope verified with the shared signing key. Raw tenant or scope headers are never an identity source; a request with neither source receives 401 GRAPH_UNAUTHORIZED.
• Tenant resolution is GraphRequestContextResolver; a missing tenant claim is rejected.
• Scope policies (Security/GraphPolicies.cs, registered in Program.cs):

• Reachability deletion (DELETE /v1/reachgraphs/{digest}) additionally requires graph:admin (ReachGraphDestructiveActionAuthorizer).
• Rate limits: the graph query routes use RateLimiterService (120 requests per window, per tenant partition); the reachability controllers use the reachgraph-read (100 per minute) and reachgraph-write (20 per minute) fixed-window policies (Hosting/ReachGraphApplicationHostingExtensions.cs).

3. API surface

Endpoints/GraphConsolidatedRouteAliases.cs publishes every family above a second time under the consolidated root /api/graph/v1 (for example /graph becomes /api/graph/v1/graph, /v1/reachgraphs becomes /api/graph/v1/reachgraphs) as real route endpoints, so the Router discovers them.

Behaviour notes verified in source:

• Graph builds (SPRINT_20261018_017 CCP-093): a build reads one SBOM version from SbomService’s tenant-scoped exact-document route for the authenticated principal’s tenant, verifies SbomService’s ledger digest (SHA-256 of the document’s compact JSON re-serialization, as SbomService derives ledger_versions.digest; the route returns the stored first-writer bytes, whose plain hash is a different identity), maps the CycloneDX JSON (CycloneDxSbomSnapshotReader) and runs the SBOM ingest (SbomIngestProcessor), which writes artifact, sbom and component nodes to graph.graph_nodes. The body carries sbomId (the SbomService subject reference), sbomVersionId (the ledger version id) and sbomDigest (the ledger digest, which the upload response returns as digest); a body that names tenantId or tenant is refused with 400. The route requires graph:write, runs inside the request and answers with the terminal status: completed only after the write, otherwise failed with a stable error code listed in the API reference. Another tenant’s SBOM is not visible to the owner read and fails sbom_not_found. SPDX documents fail sbom_format_unsupported. Build records are process-local and bounded to the 1,024 most recent builds; after a restart the status read answers 404 and the caller submits the build again (the ingest upserts the same node and edge ids). Without Graph:SbomOwner a build answers 501 GRAPH_FEATURE_UNAVAILABLE.
• The direct build paths stay excluded from Router publication and are reached on the cartographer.stella-ops.local alias with a gateway-signed identity envelope. Their canonical aliases under /api/graph/v1/builds are published, so an operator reaches a build through the gateway with a bearer token. The JobEngine scheduler worker still calls the direct path without an identity and with a body tenant, so its builds are refused until it authenticates (open follow-up in SPRINT_20261018_017).
• The overlay endpoints are unchanged: they record a process-local job as completed without running an overlay and take the tenant from the request body (open defect in SPRINT_20261018_017).
• Outside the Testing environment, overlay, export and edge-metadata services without a Postgres-backed implementation are replaced by Unsupported* services that answer with explicit unavailability instead of fabricated data (Program.cs, GraphFeatureUnavailableResults.cs). A tile read with includeOverlays=true therefore answers 501 GRAPH_FEATURE_UNAVAILABLE (details.feature = "overlays") on those hosts, while the same tile without overlays answers.
• Console consumer (Graph Explorer, /security/sbom/graph; SPRINT_20261007_031 CCP-024): the explorer reads GET /graphs, then the first listed graph’s tile with overlays. On the 501 overlay answer above it reads the tile again without overlays and states the owner’s overlay message; the graph itself is not reported as unavailable. A 401/403 or a session without graph:read renders as denied (no retry); no response or a 5xx renders as unavailable with retry; an empty graph list, a graph whose status is not ready, and a tile with no nodes each render their own stated empty state, never a blank canvas. The tile’s hasException attribute is shown as a flag only; the tile carries no exception record. The SBOM entry /security/sbom is the artifact-digest subject selection that opens SbomService’s lineage viewer (/security/lineage/<digest>); it no longer states that graph visualization is coming soon.
• Console exception controls (CCP-077): Graph Explorer applies policy:author, the scope of the Policy Engine exception create route, to both the Create Exception control and direct handler (corrected 2026-10-19 from exceptions:write, which no create route enforces). The shared Full Wizard action and both Explorer placeholder handlers are removed; inline context and Cancel remain. See Explorer exception draft controls for the actual served-route boundary, verification source and explicitly retained limitations.
• The committed OpenAPI document openapi/v1.json and the generated api-reference.mdare captured from the host in process. They cover the minimal-API routes, the reachability controllers and the /api/graph/v1 aliases of the minimal-API routes; the /api/graph/v1 aliases of the reachability controllers are not in them. The retired reachgraph-web spec is archived at docs-archive/modules/reach-graph/openapi/v1.json.

4. Indexer pipeline (in-process)

5. Change source (CIC-2)

The change and backfill source is SnapshotGraphChangeSource, which reads the persisted snapshot queue graph.pending_snapshots in Graph’s own database. Program.cs registers it for both IGraphChangeEventSource and IGraphBackfillSource whenever the Graph connection resolves. The consolidated baseline creates the queue empty, so the same source serves a fresh install. Without the connection the processor falls back to a no-op source, which the runtime guard refuses outside Development and Testing. The Doctor check doctor.graph.indexer.change-source (Services/GraphChangeSourceDoctorCheck.cs) reports the composed source, whether the queue exists and its depth, and is Critical when the no-op source is composed.

6. Persistence

• Database stellaops_graph; schemas graph and reachgraph; connection STELLAOPS_POSTGRES_GRAPH_CONNECTION or Postgres:Graph:ConnectionString (StellaOps.Graph.Operations/GraphSchemaTopology.cs). ConnectionStrings:Default is not a source. Outside Testing a missing connection fails the host.
• Migration authority: StellaOps.Graph.Persistence only (AddConsolidatedGraphPersistence, startup migrations). graph-api registers the Indexer repositories with registerMigrations: false, and the ReachGraph composition registers no migrator.

Migrations (src/Graph/__Libraries/StellaOps.Graph.Persistence/Migrations/):

The reachability hot-path cache is Valkey through ConnectionStrings:Redis (ReachGraphValkeyCache, options section ReachGraphCache); outside Development and Testing a missing Redis connection string fails startup.

7. Retention

GraphEphemeralRetentionService (StellaOps.Graph.Indexer/Retention/), options section Graph:EphemeralRetention:

It is registered only when the Graph connection resolves. The Doctor check doctor.graph.retention.ephemeral-backlog reports rows past these bounds.

8. Integrations

• Signals: the reachability query API reads runtime facts over HTTP (SignalsHttpAdapter), base address Signals:BaseUrl or STELLAOPS_SIGNALS_URL, default http://signals.stella-ops.local.
• Findings: reads the asset-registry catch-up feed with the graph:asset-registry:read-all scope (HttpGraphAssetRegistryEventSource in src/Findings).
• Timeline: audit emission through AddAuditEmission (bundle AuditEmission__TimelineBaseUrl).
• Scheduler: calls the build and overlay contract on the cartographer.stella-ops.local alias. Its build calls carry no identity and are refused (section 3).
• SbomService: graph builds read the exact-document route /api/v1/sbom/subject/{subjectRef}/document (query version) with a client-credentials token of the confidential client stellaops-graph-sbom-reader (scope sbom:read), requested per build for the caller’s tenant. Settings Graph:SbomOwner: Enabled (default false), BaseAddress, Authority, TokenEndpoint, ClientId, MaximumDocumentBytes (default 32 MiB), RequestTimeoutSeconds (default 60). The client secret comes only from GRAPH_SBOM_READER_CLIENT_SECRET; an enabled host without it fails at startup.
• Doctor registration with Platform is opt-in (Doctor:Registration:Enabled); when enabled, Authority, ClientId and ClientSecret are required and must not be blank.

9. Doctor checks

The standard service checks come from AddServiceDoctorChecks("graph-api"). The Doctor endpoints require ops.health.

10. Observability

Meter StellaOps.Graph.Api (Services/GraphMetrics.cs): graph_tile_latency_seconds, graph_export_latency_seconds, graph_query_budget_denied_total, graph_overlay_cache_hits_total, graph_overlay_cache_misses_total. The Indexer stages define their own meters (GraphAnalyticsMetrics, GraphBackfillMetrics, SbomIngestMetrics, PolicyOverlayMetrics, AdvisoryLinksetMetrics).

11. Retired surfaces

• reachgraph-web: merged into graph-api (SPRINT_20260722_023 GRA-4, GRA-9, GRA-10). Host-era dossier archived at docs-archive/modules/reach-graph/.
• cartographer: merged into graph-api; the alias remains on the container.
• src/__Obsoleted/Graph/: predecessor saved-view migration authority (EST-9) and the orphaned StellaOps.Graph.Core prototype with its tests (GRA-10).