KAVACHKAVACH
v2.0.3

Operate Neo4j Synchronization

Use Studio to understand the state of a graph projection and safely recover a failed synchronization event.

What You Will Do

You will start the local stack, seed governance data into Neo4j, inspect its synchronization events in Studio, and follow the safe retry workflow for a dead-letter event. The graph stays a projection throughout: it never replaces the authoritative control-plane data.

Start and Seed

bash
./scripts/keycloak/start-keycloak.sh
./kavach.sh

curl -X POST http://localhost:8000/api/v1/ontology/demo/seed

The local scripts initialize the Neo4j schema automatically. Re-running the seed is intentional: synchronization uses idempotent upserts, so existing graph entities and relationships are reconciled rather than duplicated.

Use the normal local workflow

Run the seed through Studio or the authenticated API when your local setup requires a bearer token. The endpoint above is a concise local example.

Inspect the Projection

  1. Open Kavach Studio and go to Home.
  2. Confirm the Neo4j Graph Store reports healthy connectivity and live counts.
  3. Open Sync Events.
  4. Select an event to see its entity, event type, retry count, timestamps, failure context, payload, and reconciliation metadata.

A completed event means its expected semantic projection has converged. It does not imply the graph is a source of truth; it is still derived from the domain repositories.

Recover an Event

If an event reaches DEAD_LETTER, first read the failure context. Typical causes include malformed source data or a relationship that is not permitted by the ontology contract. Correct that cause before retrying.

  1. Select the dead-letter event in Sync Events.
  2. Expand technical details only when the summary is not enough.
  3. Fix the underlying data or contract issue.
  4. Choose Retry event.
  5. Refresh and confirm the status becomes COMPLETED.

The retry is explicit and auditable. The worker re-runs diff-based reconciliation, which upserts the projection and repairs only drift rather than duplicating graph records.

Verify the Result

Run the smoke test when you need an end-to-end confirmation outside Studio:

bash
uv run python smoke_tests/smoke_neo4j_evaluation_result_sync.py

For deeper operational guidance, including schema initialization, direct read-only Cypher checks, soft deletes, and integration tests, continue to Neo4j Operations.