Waze reroutes when the road changes. LifeGraph reroutes when your life changes.
LifeGraph models your life — goals, commitments, resources, constraints, preferences — as a
Neo4j graph. It starts from your connected profile (email, WhatsApp, bank, card,
health, monthly expenses — seeded as graph nodes with CONNECTED state), so there is already
a life in the graph before you type a word. When reality changes (a flight gets cancelled, a
bill lands, a meeting moves), it traverses that graph to find everything the change touches,
generates competing plans, scores them against what you actually care about, explains why
the winner won in graph terms, and — only with your approval — writes the new plan back
into the graph.
This is not a chatbot with a graph attached. Every number, chain and recommendation on screen is produced by a real traversal over real nodes and edges.
| # | Stage | What happens | Where it comes from |
|---|---|---|---|
| 01 | MODEL | The seeded connected profile plus natural-language context become goals, commitments, constraints, preferences | POST /api/context → graph seed |
| 02 | EVENT | Something unexpected happens | POST /api/events |
| 03 | IMPACT | The change propagates: affected nodes, chain of consequences, threatened goals | GET /api/events/:id/impact — real Cypher traversal |
| 04 | OPTIONS | Three competing response plans, each grounded in the graph | POST /api/events/:id/options |
| 05 | DECISION | Six-dimension weighted scoring ranks the plans | POST /api/decisions |
| 06 | WHY | Explanation paths traversed in the graph; supporting nodes glow on the canvas | recommendation.explanation + supportingNodeIds |
| 07 | EXECUTE | Nothing happens without you — approval gate, then step-by-step write-back | POST /api/decisions/:id/execute |
| 08 | RECOVERED | The graph is the new plan: resolved / created / cancelled state | final graph payload |
┌───────────────────────────┐ ┌──────────────────────────────┐
│ client/ Vite + React 19 │ /api │ server/ Express (ESM) │
│ plain JSX · Tailwind v4 │───────▶│ routes → decision engine │
│ Cytoscape.js live graph │◀───────│ graph repositories │
└───────────────────────────┘ graph │ │
payloads │ cypherRepository ──▶ Neo4j Aura (bolt + APOC)
│ memoryRepository ──▶ in-memory fallback
└──────────────────────────────┘
- Graph-first. One
:EntityMERGE key with physical domain labels (Goal,Flight,Meeting,Budget,Option, …); display metadata and props travel with each node so the client can paint the graph without re-deriving anything. - Batched writes. On Aura with APOC, seeds / resets / plan applications land in single
UNWINDstatements inside one managed transaction (session.executeWrite), with a per-row fallback when APOC is absent. - Deterministic demo. The scripted flight-cancelled path never calls an LLM — impact analysis, option generation and scoring are graph-driven and reproducible. The LLM is an optional enhancer for unknown / custom events only.
- Dual driver.
GRAPH_DRIVER=auto|neo4j|memory— the same contract runs against Aura or the in-memory graph, and both produce identical demo outcomes. - Connected-profile seed. A structured persona fixture (person, email, WhatsApp, bank, card, income, monthly expenses, health, contacts) is written into the graph at reset, so stage 01 starts from ~40 nodes / ~66 edges of real life instead of an empty canvas.
0.30 goal preservation + 0.20 deadline safety + 0.15 cost + 0.15 risk + 0.10 preference fit + 0.10 convenience
Every dimension is computed from graph state (threatened goals, arrival margins, budget headroom, violated constraints), never from prose.
# 1. install (root + server + client)
npm run install:all
# 2. configure
cp .env.example .env # then fill in NEO4J_URI / NEO4J_USERNAME / NEO4J_PASSWORD
# GEMINI_API_KEY is optional — leave empty for the deterministic demo
# 3. run both halves
npm run dev # server :8787 · client :5173 (proxies /api)Open http://localhost:5173 — the home stage greets you with the live profile card (connected accounts, income, expenses, health) already on the graph. Press Model my life →, then Simulate: Flight cancelled and ride the loop to PLAN RECOVERED.
Without Aura credentials the server falls back to the in-memory graph automatically, so the demo runs anywhere.
| Command | Does |
|---|---|
npm run dev |
server (node --watch) + client (Vite) side by side |
npm run build |
production client build (client/dist) |
npm start |
server only, production mode |
npm test |
engine + graph-repository tests (node --test) |
| Key | Purpose |
|---|---|
GRAPH_DRIVER |
auto (default) · neo4j · memory |
NEO4J_URI / NEO4J_USERNAME / NEO4J_PASSWORD / NEO4J_DATABASE |
Aura connection |
PORT |
API port (default 8787) |
GEMINI_API_KEY |
optional — enables LLM enhancement for unknown events |
GEMINI_MODEL |
model id, read from env only (falls back to LLM_MODEL / DEFAULT_MODEL) |
Full request/response contracts live in docs/CONTRACTS.md.
GET /api/health driver + LLM status
GET /api/scenarios the scripted event scenarios
POST /api/context natural language → graph seed
GET /api/graph current graph payload
POST /api/reset reseed the demo graph
POST /api/events inject a scenario or custom event
GET /api/events/:id/impact traversal: affected nodes, chain, threatened goals, Cypher proof
POST /api/events/:id/options three graph-grounded plans
POST /api/decisions body { eventId } — weighted scoring, recommendation, explanation paths
POST /api/decisions/:id/execute approval-gated write-back, step log, outcome
client/ Vite React SPA — sidebar app shell, connected-profile panel, stage panels,
Cytoscape live graph, light lavender design system
server/ Express API — routes, decision engine (analyze → generate → score → explain → execute),
Neo4j + in-memory repositories, persona + scenario fixtures, tests
docs/ CONTRACTS.md — the client/server payload contract
spec.md the original product spec this build implements
assets/ repository banner
A soft lavender "connected life OS": light canvas (#f4f1fb) with white rounded cards,
Plus Jakarta Sans for display and body, IBM Plex Mono for telemetry, and a violet → mint
accent system (violet #7c6df2 for goals and selection, mint #2ec4a6 for resolved,
coral #ef5d72 for impact, cyan #3db8d4 for info). A persistent sidebar frames the product
— profile chip, primary nav (Home, LifeGraph AI, Commitments, Inbox, Calendar, Impact
Reports), "My Life Areas" and an invite card — with the eight-stage loop rail inside the
working column and the live Cytoscape canvas beside it.
On the graph, node shape encodes entity family (star = goal, vee = flight, hexagon = budget …) and colour encodes state. Impacted nodes pulse; supporting nodes in the "why" stage glow; everything outside a pinned node's neighbourhood dims.
Built for the Qodar × Neo4j hackathon · 2026-09-12
