docs: finalize PodMan architecture and write full integration specs

Replaces v1 plan with locked architecture: - Hermes orchestrator: POST /ingest → Gemini Vision → MongoDB → event detection → Gemini Live 2.5 voice via LiveKit Agents - Four MongoDB collections: engineer_states, ownership_map, events, nudges - Continual learning via ownership_map persisting across sessions New files: docs/idea.md, docs/gemini.md, docs/livekit.md, docs/mongodb.md, docs/digitalocean.md, docs/demo-setup.md Updated: README.md, docs/PLAN.md (12-hour build plan), database/README.md, infra/README.md, .env.example Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FFbfi4Cmb7BY75Wtne7bZn
2026-06-27 15:23:36 -07:00
parent e26961d526
commit 923ab1cf58
13 changed files with 1313 additions and 210 deletions
@@ -0,0 +1,128 @@
+# MongoDB Atlas Integration Spec
+
+MongoDB Atlas is PodMan's shared memory. It stores live engineer state, the ownership map that enables continual learning, coordination events, and nudge history.
+
+---
+
+## Collections
+
+### `engineer_states`
+
+Latest context per engineer. Upserted on every successful `/ingest` call.
+
+```ts
+{
+  _id: string,                    // engineerId (stable across sessions)
+  podId: string,
+  name: string,                   // display name
+  currentFile: string | null,     // from Gemini Vision
+  inferredTask: string | null,    // from Gemini Vision
+  terminalVisible: boolean,
+  recentTerminalOutput: string | null,
+  confidence: number,             // last frame confidence (0–1)
+  updatedAt: Date
+}
+```
+
+**Index:** `{ podId: 1, updatedAt: -1 }`
+
+**Usage:** Hermes reads all documents for a given `podId` after each update to run event detection across the full team.
+
+---
+
+### `ownership_map`
+
+Tracks who works on which files. Built up over the session. **Persists across sessions** — this is the continual learning artifact.
+
+```ts
+{
+  _id: string,                    // `${podId}:${file}`
+  podId: string,
+  file: string,
+  primaryOwner: string,           // engineerId with most recent activity on this file
+  contributors: string[],         // all engineerIds observed on this file
+  observationCount: number,       // total frames where this file was seen
+  lastSeenAt: Date
+}
+```
+
+**Index:** `{ podId: 1, file: 1 }` (unique)
+
+**Upsert logic:**
+- On each context update where `currentFile` is non-null:
+  - Increment `observationCount`
+  - Update `primaryOwner` to the engineer with the most recent `lastSeenAt` on this file
+  - Add engineerId to `contributors` if not present
+  - Update `lastSeenAt`
+
+**Continual learning:** Hermes loads this collection on startup for the pod. If history exists, it pre-populates the in-memory ownership cache before the first frame arrives.
+
+---
+
+### `events`
+
+Every coordination event detected by Hermes.
+
+```ts
+{
+  _id: ObjectId,
+  podId: string,
+  type: 'DEPENDENCY_READY' | 'BLOCKER_DETECTED' | 'DUPLICATE_WORK',
+  involvedEngineers: string[],
+  file: string | null,
+  reason: string,                 // 1-sentence explanation from Gemini
+  nudgeSent: boolean,             // false if suppressed by cooldown
+  detectedAt: Date
+}
+```
+
+**Index:** `{ podId: 1, detectedAt: -1 }`
+
+---
+
+### `nudges`
+
+Every voice nudge sent to the room.
+
+```ts
+{
+  _id: ObjectId,
+  podId: string,
+  eventId: ObjectId,             // ref to events collection
+  targetEngineers: string[],
+  message: string,               // the spoken text
+  sentAt: Date
+}
+```
+
+**Index:** `{ podId: 1, sentAt: -1 }`
+
+**Cooldown check:** before sending a nudge, Hermes queries this collection for any nudge in the last 3 minutes for the same `podId`. If found, suppresses the new nudge and marks the event as `nudgeSent: false`.
+
+---
+
+## Hermes startup sequence
+
+```
+1. Connect to Atlas using MONGODB_URI
+2. Load ownership_map for this podId
+3. Build in-memory cache: Map<file, { primaryOwner, contributors }>
+4. Begin accepting /ingest requests
+```
+
+---
+
+## Atlas configuration
+
+- **Cluster tier:** M0 (free) is sufficient for hackathon scale
+- **Region:** same as DigitalOcean deployment (e.g. NYC1)
+- **Auth:** connection string in `MONGODB_URI` env var
+- **Collections created automatically** on first write (no schema migration needed)
+
+---
+
+## What MongoDB does NOT store
+
+- Raw screenshot frames (too large — frames are processed in-memory by Hermes and discarded)
+- Full Gemini response objects (only extracted fields are stored)
+- Session recordings