[Forge] Neo4j Graph Database Service Setup
Task ID: ed95ce27-ae67-4da3-b94b-bdb92407cd93
Layer: Forge
Priority: 90
Goal
Set up Neo4j Community Edition as a systemd service to provide SciDEX with a native graph database backend. This will enable efficient graph queries for the Atlas layer (knowledge graph navigation, shortest paths, subgraphs) and support the evolution from SQLite-stored edges to a proper graph database. The implementation includes service configuration, Python driver integration, and a clean API wrapper with connection pooling.
Acceptance Criteria
☑ Neo4j Community Edition installed and running as scidex-neo4j systemd service
☑ Neo4j configured with bolt protocol on port 7687 and HTTP on port 7474 (localhost only)
☑ Python neo4j driver added to requirements
☑ graph_db.py module created with:
- Connection pooling and health check
- CRUD helpers:
add_node(),
add_edge(),
query_neighbors(),
shortest_path(),
subgraph() - Proper error handling and logging
☑ Unit tests for graph_db.py pass
☑ scidex services list shows neo4j healthy
☑ Documentation in graph_db.py docstrings
Approach
Install Neo4j Community Edition:
- Download and install Neo4j Community Edition (version 5.x)
- Configure for localhost-only access
- Set up authentication (store credentials in .env)
Configure systemd service:
- Create
/etc/systemd/system/scidex-neo4j.service - Enable service to start on boot
- Configure ports: bolt:7687, HTTP:7474
Python integration:
- Add
neo4j driver to requirements.txt
- Install with pip
Build graph_db.py:
- Connection manager with pooling
- Health check endpoint
- Core operations: add_node, add_edge, query_neighbors, shortest_path, subgraph
- Follow SciDEX error handling patterns
Update CLI:
- Add neo4j to
scidex services list monitoring
Test:
- Write unit tests for each operation
- Verify service health via CLI
- Test connection pooling under load
Work Log
2026-04-01 20:10 PT — Slot 1
- Created spec file
- Starting implementation...
2026-04-01 20:20 PT — Slot 1
- Installed Neo4j Community Edition 2026.03.1 via apt package
- Configured Neo4j for localhost-only access (bolt:7687, HTTP:7474)
- Set initial password and stored credentials in .env
- Created systemd service wrapper at /etc/systemd/system/scidex-neo4j.service
- Installed neo4j Python driver (6.1.0) and python-dotenv (1.2.2)
- Created graph_db.py module with:
- Connection manager with pooling (max 50 connections, 3600s lifetime)
- health_check() function
- add_node() with unique key support for MERGE operations
- add_edge() for creating relationships
- query_neighbors() with direction and relationship filters
- shortest_path() using Cypher shortestPath algorithm
- subgraph() for extracting neighborhoods around center nodes
- execute_cypher() for custom queries
- Created test_graph_db.py with 10 unit tests covering all operations
- All tests pass (10/10 successful)
- Updated cli.py to include neo4j in SERVICES dict
- Verified:
scidex services list shows neo4j active ✓
- Updated requirements.txt with neo4j==6.1.0 and python-dotenv==1.2.2
- Result: Done — Neo4j graph database fully operational and integrated into SciDEX