Skip to content
ayushozhaPublic

About

LifeGraph — a graph-based planning prototype that traces changing constraints and compares next steps. React, Express, and Neo4j.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

4 Commits

Folders and files

Repository files navigation

LifeGraph — reroutes when your life changes

LifeGraph

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.


The loop

# 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

Architecture

┌───────────────────────────┐        ┌──────────────────────────────┐
│  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 :Entity MERGE 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 UNWIND statements 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.

Scoring

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.

Quickstart

# 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.

Scripts

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)

Configuration (.env)

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)

API surface

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

Repository layout

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

Design

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

About

LifeGraph — a graph-based planning prototype that traces changing constraints and compares next steps. React, Express, and Neo4j.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages