neo4j

Catalog date: 2026-06-24.

The canonical graph store. Holds the ownership graph (Workstream F), the bipartite lineage DAG (Workstream A + B), and the entity-graph service (instruments, companies, datasets, pipeline assets, service metadata). Postgres carries the snapshot rows; Neo4j carries the traversable relationships.

Identity

Field	Value
Service id	neo4j
Role	graph
Image	neo4j:5-community
Port	7474 (HTTP) + 7687 (Bolt)
Storage	2 Gi PVC (volume_claim_template in the Terraform-provisioned StatefulSet, terraform/modules/alphaswarm_workloads/main.tf); managed Neo4j Aura recommended for prod cells

Deployment surfaces

Surface	Where
Compose	service neo4j in alphaswarm_platform/compose/docker-compose.yml
Terraform	terraform/modules/alphaswarm_workloads/main.tf — kubernetes_stateful_set.neo4j, gated to local/RPi installs (local.is_local), neo4j:5-community image, 2Gi ReadWriteOnce PVC. No deployments/kubernetes/base-services/neo4j/ Kustomize manifest was found — correcting the earlier "rolled into base-services/" and "not provisioned by a managed module today" claims, which are both contradicted by this module. alphaswarm-graph's deployment.yaml connects to it at bolt://neo4j:7687, describing it as "the platform's Neo4j 5 Community StatefulSet".

Dependencies

Upstream: none.

Downstream:

• alphaswarm-core — ownership graph reads via data.ownership.* MCP tool; lineage relay writes through OpenLineage adapter.
• alphaswarm-worker — sync tasks that mirror Postgres rows into Neo4j edges.

Sync semantics

• Postgres remains the canonical source of truth for entity attributes; Neo4j holds the relationships.
• Sync is event-driven via alphaswarm/tasks/openlineage_relay_tasks.py's drain_openlineage_outbox task, which drains an OpenLineageOutbox table. No lineage Celery queue family or data.lineage.replay task was found in alphaswarm/tasks/celery_app.py — correcting the earlier claim.
• Read paths go through the data.ownership.* and data.lineage.* DataMCP tools — the agentic plane MUST NOT speak Bolt directly.

Operations

• Auth: username/password via ExternalSecret; Bolt TLS through Linkerd mTLS.
• Backups: no neo4j-admin database backup cron or job was found in alphaswarm_platform — flagging as unverified rather than restating a specific backup mechanism.
• Cypher style: no alphaswarm/data/sources/graph/queries/ directory exists. Graph query logic actually lives in alphaswarm/data/entities/neo4j_store.py, alphaswarm/data/entities/graph_store.py, and alphaswarm/data/semantics/graph_source.py.

See also

• ownership-graph (private alphaswarm_internal repo) — ownership graph contract (Workstream F).
• lineage-graph (private alphaswarm_internal repo) — bipartite lineage DAG + OpenLineage relay (Workstream A + B). (As of 2026-07-19, alphaswarm/.cursor/rules/ only carries a pointer to this SSoT repo.)
• entity-graph-services.md — entity registry + service control via Neo4j.