AGENTS.md

1# apps/ui — Agent Instructions
2 
3React 19 web app for visualizing and interacting with the knowledge graph.
4 
5## Entry Point
6 
7`src/main.tsx` → React root. Port **5173** (Vite dev server).
8 
9## Key Directories
10 
11| Directory | Purpose |
12|-----------|---------|
13| `src/components/` | React components |
14| `src/store/` | Zustand stores — client-only state (see below) |
15| `src/hooks/` | Custom React hooks (`use-graph.ts`, `use-websocket.ts`, `use-debounce.ts`) |
16| `src/lib/` | Utilities — `api.ts` (REST client), `ws.ts` (WebSocket), `query-client.ts` / `query-keys.ts` (TanStack Query), `ws-cache.ts` (live-update cache reducers) |
17 
18## State management
19 
20Server state lives in **TanStack Query** (`@tanstack/react-query`). Each page
21calls `useQuery` / `useMutation` keyed via the `src/lib/query-keys.ts` factory;
22the `queryClient` singleton in `src/lib/query-client.ts` lets non-component code
23(WebSocket handlers) patch caches with `setQueryData`. The accumulated graph
24cache + entity mutations are wrapped in `src/hooks/use-graph.ts`.
25 
26Zustand is used **only for true client state**:
27 
28| Store | Purpose |
29|-------|---------|
30| `auth-store.ts` | Session: csrfToken / user / mode / relayUrl |
31 
32UI-local state (search query, timeline/ownership filters, graph selection) is
33plain component `useState`.
34 
35## Conventions
36 
37- React 19 functional components only
38- Server state via TanStack Query (never hand-rolled caches or Zustand for server data)
39- WebSocket live updates patch query caches via pure reducers in `lib/ws-cache.ts`
40- Cytoscape.js with diff-based rendering (not full re-render)
41- Tailwind CSS dark theme (`zinc-950` background)
42- HashRouter (React Router 7)
43- REST client in `src/lib/api.ts` — all API calls go through this
44- WebSocket in `src/lib/ws.ts` — auto-reconnect, Zod-validated event union
45