[Forge] Neo4j graph database service setup done

[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

- Connection pooling and health check
- CRUD helpers: add_node(), add_edge(), query_neighbors(), shortest_path(), subgraph()
- Proper error handling and logging

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