Ramis
923ab1cf58
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
129 lines
3.5 KiB
Markdown
129 lines
3.5 KiB
Markdown
# 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
|