# Team Memory Graph — Redesign Brief (fresh-session handoff)

> **You are a fresh Claude Code session with no prior context. Read this whole file first.**
> Your job: rebuild the **live "Team memory" graph view** so the **light/real-data** version is as
> polished and functional as the original **dark Bauhaus mock**, and make the graph **dynamic**
> (force-directed + animated), not the current dead static-column layout.
> **Do not rewrite the backend materializer — it is good.** The problem is 100% the frontend rendering.

---

## 0. Mission (one paragraph)

PodMan's "Team memory" is a per-pod graph of who owns/edits which files, where work collides, and what
PodMan learned from accepted interventions — the continual-learning loop made legible in 10 seconds.
A **dark Bauhaus mock** of this view looks great (clean 3-panel layout, a learning-loop rail, an activity
stream, a readable graph). The **shipped light version on real data looks terrible** (a hairball of red
edges, overlapping labels, a static lifeless layout, and it's missing the learning-loop rail + activity
stream entirely). Make the light version match the mock's structure/polish/functionality, in the app's
**light shadcn theme**, and make the **graph dynamic** (organic force-directed layout, draggable,
animated transitions). Keep using **real data** from the existing materializer.

---

## 1. The two reference points

### A. The dark Bauhaus mock = what "good" looks like (target structure)

A single dark card titled **"PODMAN — CONTINUAL-LEARNING OBSERVATORY"** with a `LIVE · POD demo-pod`
status. Layout:

- **Left rail — WORKFLOW METRICS**: a vertical stack of bordered cards, each a big numeral + an
  UPPERCASE tracked label + a one-line detail, with a colored left-accent bar:
  `03 PODS WATCHED`, `05 ENGINEERS LIVE`, `02 COLLISIONS OPEN (▲ auth.ts critical)`,
  `01 INTERVENTION SENT`, `86% ACCEPT RATE (▲ +14% this session)`, `124 MEMORY VECTORS`.
- **Center — the GRAPH**: sparse, geometric, readable. Node shapes encode kind
  (engineer = filled square, file = outlined square, feature = circle, collision = triangle,
  intervention = diamond). One **risk path is lit** (Karti+Yahya → auth.ts → collision → sync PR →
  `learned_from`), everything else dimmed. Edges color-coded (`collides` red, `warns` amber/orange,
  `learned_from` dashed violet, `owns` blue, `editing` paper, `touches` grey).
- **Right rail — LEARNING LOOP**: a vertical 5-step stepper with the active step highlighted/pulsing:
  `01 OBSERVE (vision → 5 contexts/s)` → `02 STORE (124 vectors · Atlas)` →
  `03 PREDICT (2 collisions flagged)` [active] → `04 OUTCOME (1 accepted · 0 dismissed)` →
  `05 ADAPT (Karti→auth ownership +)`. Arrows between steps.
- **Bottom-left — ACTIVITY STREAM**: a time-stamped feed with colored kind-tags:
  `15:48 EDITING Yahya opened auth.ts — unpushed changes detected`,
  `15:48 COLLISION Critical overlap on auth.ts · Karti + Yahya`,
  `15:49 WARNS PodMan spoke: "open a sync PR?" → card sent`,
  `15:49 OUTCOME Sync PR accepted by the pod`,
  `15:49 LEARNED_FROM Memory updated: Karti owns auth (confidence ↑)`.
- **Bottom-right — SELECTED NODE**: click a node → kind / name / relationships count / severity / a
  one-line "why" (`Two engineers editing the same file before push — the signal git can't see.`).
- **Legend**: engineer / file / feature / collision / intervention · collides / warns / learned_from.

It reads in 10 seconds because it is **sparse, color-coded, and tells the loop story** with the rails +
stream, not just a node blob. (The full mock HTML/CSS is reproduced in **Appendix A** — port its
structure to light shadcn.)

### B. The shipped light version = what's wrong (the thing to fix)

Same data, but: a **hairball** — every engineer fans red `collides` edges to ~6 collision triangles
(all labeled `sync PR`); **file labels overlap** in a dim middle column; the graph uses a **static
deterministic column layout** (`x` by kind, `y` evenly spread) so it looks dead/lifeless; and it is
**missing the LEARNING LOOP rail and the ACTIVITY STREAM** entirely — it's just a metrics rail + the bare
graph + a selected-node panel. (Two already-fixed-on-branch items: garbage collision labels
`infra/README.md### Running the git watcher` and full-path bleed — see PR #7 / commit `a21a289`,
`shortLabel` in `live.ts`. Build on top of that, don't redo it.)

---

## 2. The gap to close (light vs mock)

| Mock has                                 | Light version                   | Action                             |
| ---------------------------------------- | ------------------------------- | ---------------------------------- |
| Workflow metrics rail                    | ✅ has it (3 metrics)           | keep; restyle to match             |
| **Learning loop rail (observe→…→adapt)** | ❌ missing                      | **build it** (needs live counts)   |
| **Activity stream feed**                 | ❌ missing                      | **build it** (needs an event feed) |
| Selected-node panel                      | ✅ has it                       | keep                               |
| **Dynamic / animated graph**             | ❌ static columns               | **replace the layout**             |
| Sparse, lit "risk path"                  | partial (Risk-path mode exists) | improve emphasis + spacing         |
| Legend                                   | ✅                              | keep                               |

---

## 3. Current architecture (build on this — do NOT rewrite the materializer)

**Backend (good, keep):**

- `backend/src/graph/live.ts` — `materializePodGraph(podId)`: builds the graph from the real Mongo
  collections (`pods`, `engineer_states`, `observations`, `collisions`, `interventions`, `outcomes`).
  It already de-noises hard: collapses collisions by `memorySignature`, caps to 8, collapses
  interventions to one per collision, filters junk files (`isFilePath`), prunes test-artifact engineers
  (`ENGINEER_NOISE`), caps files to 9, short labels (`shortLabel`). Output is ~20 clean nodes for
  `demo-pod`. **This is solid — extend it, don't replace it.**
- `backend/src/graph/store.ts` — `loadPodGraph(podId)`: live materializer → seeded `team_model.graph`
  → demo fallback (`createDemoPodGraph`). Plus `reachFrom` (`$graphLookup`).
- Route: `GET /api/pods/:id/graph` returns `PodGraph` (also `/graph/reach/:node`).
- `backend/src/memory/db.ts` — `collections()`, `getGitStates(podId)`, `getDb()`.
- WS bus: `backend/src/server.ts` hosts `ws /api/events` (the agent + `/api/outcome` broadcast here).

**Frontend (this is where the work is):**

- `frontend/src/components/GraphView.tsx` — **the thing you redesign** (~90% of the work). Currently:
  fetches `/api/pods/:id/graph`, renders a bespoke SVG with the static column layout, Risk/Learning/Whole
  toggles, a metrics rail, a selected-node panel, a legend. Composed from shadcn primitives (`Button`,
  `Badge`) + Tailwind utilities. Theme-aware via shadcn tokens.
- `frontend/src/lib/graph.ts` — `fetchPodGraph(podId)`.
- Opened from each `PodCard`'s `⋯` menu → "Team memory" (`onOpenGraph(pod.id)` in
  `frontend/src/App.tsx`). It is a conditional render (no route).

**Data contract** (`shared/src/graph.ts`):

```ts
PodGraph = { podId, generatedAt, nodes: PodGraphNode[], edges: PodGraphEdge[], metrics: PodGraphMetric[] }
PodGraphNode = { id, kind, label, summary, weight 0..1, status: 'stable'|'active'|'risk'|'learned', x, y }
//   kind: 'engineer'|'feature'|'file'|'collision'|'intervention'
PodGraphEdge = { id, source, target, kind, label, strength 0..1 }
//   kind: 'owns'|'editing'|'touches'|'collides'|'warns'|'learned_from'
PodGraphMetric = { label, value, detail }
```

**Theme / components (HARD RULE):** the app is **light shadcn**, built from the **ruixen registry** —
add primitives with `npx shadcn@latest add "https://ruixen.com/r/[component]"` and compose from
`@/components/ui/*` (`Button`, `Badge`, `Card`, `Tabs`, `ToggleGroup`, etc.) using the design tokens
(`var(--card)` / `--foreground` / `--muted-foreground` / `--border`, `--chart-1..5`). Only the SVG/canvas
graph is bespoke. Match `frontend/src/App.tsx`'s `StatPill`/`BriefLine` utility patterns.

---

## 4. Target design (build this)

A light shadcn page with the **mock's structure**:

```
┌───────────────────────────────────────────────────────────────────────┐
│ Header: "Team memory · What PodMan learned · <pod>"        [← Pods]      │
├───────────────────────────────────────────────────────────────────────┤
│ Toggles: Risk path | Learning edges | Whole graph   (keep)              │
├──────────────┬──────────────────────────────────┬─────────────────────┤
│ WORKFLOW     │                                  │  LEARNING LOOP        │
│ METRICS      │        DYNAMIC GRAPH CANVAS        │  observe→store→       │
│ (cards)      │   (force-directed + animated)     │  predict→outcome→     │
│              │                                  │  adapt (active pulses)│
├──────────────┴──────────────────────────────────┴─────────────────────┤
│ ACTIVITY STREAM (time-tagged feed)        │ SELECTED NODE (detail)      │
└───────────────────────────────────────────────────────────────────────┘
```

- **Light shadcn** throughout (theme-aware; follows dark mode if the app ever toggles). Keep the
  geometric **node-shape + color encoding** (it's the legible part) but on light surfaces with the
  app's hues (engineer blue `#2563eb`, file slate outline `#475569`, feature amber `#d97706`,
  collision red `#dc2626`, intervention violet `#7c3aed`; edges: collides red, warns amber,
  learned_from dashed violet, owns blue, editing slate, touches faint slate).
- **Default to "Risk path"**: light the collision→intervention→`learned_from` chain; dim the rest.

---

## 5. Make the graph DYNAMIC (the headline new requirement)

The static column layout (`live.ts` `layout()` sets `x`/`y` by kind) looks dead. Replace the frontend
rendering with a **dynamic** graph. Pick one (recommended order):

1. **`d3-force` force-directed (recommended).** Add `d3-force` (small). Run a force simulation on the
   `PodGraph` nodes/edges: link force (by `edge.strength`), charge/repulsion, center, collision radius
   (by `node.weight`). Render nodes/edges as SVG, update positions per tick. Make nodes **draggable**
   (pin on drag). Animate new nodes/edges fading in on data refresh, and the `learned_from` dashed
   stroke animating. Ignore the server's `x`/`y` (or use them as initial positions). Keep node shapes.
2. `react-force-graph` / `force-graph` (canvas) — heavier, faster for big graphs; overkill at ~20 nodes
   but fine.
3. A custom animated **layered** layout (engineers → files → collisions → interventions columns, but
   with curved edges, eased position transitions on refresh, and gentle idle motion). Lighter-weight
   than d3-force; still feels alive if you animate transitions.

**Realtime/dynamic data:** poll `GET /api/pods/:id/graph` every ~5s and **animate the diff** between
snapshots (don't hard-replace). Optionally subscribe to `ws /api/events` for instant nudges. New
collisions/interventions should visibly animate in; the `learned_from` edge + gold node should pop on a
new accepted outcome.

**De-hairball:** even force-directed, ~6 collisions × 3 engineers = many `collides` edges. Mitigate:
bundle/curve edges, lower non-risk edge opacity, default to Risk-path emphasis, size nodes by `weight`,
and keep label collision-avoidance (offset labels, hide on overlap, show on hover/select).

---

## 6. Data for the new panels (extend the materializer or add endpoints)

The mock's **Learning Loop** and **Activity Stream** need data the current `PodGraph` doesn't carry. Two
options: (a) extend `materializePodGraph` to also return `loop` + `activity`, or (b) add small endpoints.
Recommended: extend the return type (additive to `shared/src/graph.ts`).

- **Learning loop counts** (`observe→store→predict→outcome→adapt`):
  - observe = recent `observations` count (e.g. last 60s) / rate
  - store = `memory_vectors` or `collisions.embedding` count (Voyage vectors)
  - predict = open `collisions` (distinct signatures) count
  - outcome = `outcomes` accepted vs dismissed counts
  - adapt = `team_model.ownership` entries / learned owners count
  - mark the "active" stage = the most recent activity.
- **Activity stream**: merge + time-sort recent events from `collisions.detectedAt`,
  `interventions.createdAt`, `outcomes.recordedAt`, `engineer_states.gitUpdatedAt` → a typed feed
  `{ at, kind: 'editing'|'collision'|'warns'|'outcome'|'learned_from', text }`. Cap to ~8 most recent.

(`backend/src/memory/db.ts` `collections()` gives you `observations/collisions/interventions/outcomes`;
`getGitStates` gives engineer_states; `team_model` is `db.collection('team_model')`.)

---

## 7. Files to touch

- **`frontend/src/components/GraphView.tsx`** — the redesign (force-directed graph + 3-panel layout +
  learning-loop rail + activity stream). May split into `GraphCanvas.tsx`, `LearningLoop.tsx`,
  `ActivityStream.tsx`, `MetricsRail.tsx`.
- **`frontend/src/lib/graph.ts`** — add fetches for loop/activity if you add endpoints.
- **`backend/src/graph/live.ts`** (extend, don't rewrite) — emit `loop` + `activity` in the result;
  keep all the de-noise.
- **`shared/src/graph.ts`** — add `loop`/`activity` types to `PodGraph` (additive).
- **deps** — `d3-force` (+ `@types/d3-force`) via pnpm in `frontend`.
- Possibly add a ruixen primitive (e.g. `timeline`, `stepper`) via the shadcn CLI if one fits.

---

## 8. Constraints & gotchas (READ — these will bite you)

- **The materializer is good — do not rewrite it.** It already de-noises (caps, collapse-by-signature,
  engineer/file filters, short labels). The bad UI is the **frontend layout/render**, not the data.
- **PWA service worker caches aggressively** — after any deploy, hard-refresh (Cmd-Shift-R) or test in a
  private window, or you'll think nothing changed.
- **Deploy = merge to `main`** (DO `deploy_on_push: true`). `main` is shared by ~4 engineers and moves
  fast. Work on a branch, open a PR, merge. Don't push to `main` directly.
- **`learned_from` "money" edge won't render on `demo-pod`** right now — its one accepted outcome is
  orphaned (points at a collision deleted by test churn). It needs **one intact accept flow** (real
  collision → intervention → someone clicks Accept) to draw. To demo, seed a clean chain or clear test
  docs (writes to shared Atlas — confirm scope first).
- **Atlas creds rotate frequently** — `podman/.env`'s `MONGODB_URI` may be stale; the **deployed env**
  has the working one. If local Mongo auth fails, that's why.
- **Build verification**: some sandboxes can't run `pnpm`/`vite`/shadcn deps (`lucide-react`,
  `@radix-ui`). Verify the frontend with `pnpm build` in a real env or CI before merging. Backend
  typecheck excludes uninstalled `ws`/`sharp`/`@livekit/rtc-node` noise.
- **Compose from ruixen/shadcn primitives** (`npx shadcn add ruixen.com/r/[component]`,
  `@/components/ui/*`); only the SVG/canvas graph is bespoke. Match `StatPill`/`BriefLine` in `App.tsx`.
- **Light theme + tokens** — never hardcode dark colors for chrome; use `var(--card)/--foreground/…`.
  Keep fixed semantic hues only for the node/edge kind encoding.

---

## 9. Acceptance criteria

- Light Team-memory page matches the mock's structure: **metrics rail + dynamic graph + learning-loop
  rail + activity stream + selected-node panel + legend**.
- **Graph is dynamic**: force-directed (or animated layered), **draggable**, **animates** new
  nodes/edges and refresh transitions; **no overlapping labels, no hairball**.
- Reads in 10s; the **risk/money path is obvious** by default.
- **Light shadcn** theme, theme-aware; composed from ruixen primitives.
- Uses **real data** from `materializePodGraph`; graceful demo fallback when empty.
- `pnpm build` + typechecks pass; deploys; verified after a hard-refresh.

---

## 10. Suggested first moves for the new session

1. Read this file + `docs/graph.md` + `docs/live-ui-spec.md` (R1/R2 sections) + `CLAUDE.md`.
2. `git fetch`; branch off `main` (or `feat/live-graph-glue`, which has the latest graph work).
3. Hit the live data once: `curl https://165-22-129-249.sslip.io/api/pods/demo-pod/graph` — that's the
   real `PodGraph` you'll render.
4. Build a `d3-force` `GraphCanvas` first (replace the static layout), get it draggable + animated.
5. Add `LearningLoop` + `ActivityStream` (extend the materializer to feed them).
6. Polish to the mock; `pnpm build`; PR → main → redeploy → hard-refresh.

---

## Appendix A — the dark mock (reference structure to port to light)

The mock is a single dark card. Structure + the exact content to reproduce (in light shadcn):

- Header: brand glyph (blue square + amber circle + red triangle + outlined square) + `PODMAN /
CONTINUAL-LEARNING OBSERVATORY` + `● LIVE · POD demo-pod`.
- Grid `180px 1fr 196px`: **metrics rail** | **graph** | **learning-loop rail**.
- Metrics cards: big `Archivo`-weight numeral, uppercase tracked label, muted detail, colored
  left-accent (blue/red/yellow/violet/green).
- Graph: SVG, geometric node shapes by kind, color-coded edges, one lit risk path, dim others; click a
  node → highlight its incident edges + neighbors, fill the selected-node panel.
- Learning-loop rail: 5 bordered steps with number + UPPERCASE title + muted sub; the active step has a
  pulsing left bar; `↓` arrows between.
- Legend row (node kinds + edge kinds).
- Activity stream (time + colored tag + text) and selected-node panel below.

Palette used (port to shadcn tokens for chrome; keep these as node/edge hues):
`bg #0c0c0e`, `panel #141417`, `line #2a2a31`, `paper/text #ECE7DA`, `muted #8d897e`,
`blue #3B5BFF`, `red #E2403A`, `amber #F6C445`, `violet #8b6cff`, `green #46c07a`.
For light: chrome → `var(--card)/--foreground/--border/--muted-foreground`; node/edge hues →
blue `#2563eb`, slate `#475569`, amber `#d97706`, red `#dc2626`, violet `#7c3aed` (light-readable).

> The dark mock was a `show_widget` demo (not a saved file). If you want the literal HTML/CSS, ask the
> user to paste it, or reconstruct from this appendix — the **structure + content above is the spec**.
> Goal: same structure, same legibility, **light theme + dynamic graph**.