MongoDB Agent Guide — Quick Reference for GoGrab Platform

Purpose: Get any agent up to speed on querying the GoGrab MongoDB setup in seconds, not minutes. Read this BEFORE opening Atlas or writing any query.

TL;DR — The Cheat Sheet

Connection Points

The 5 Collections You'll Actually Query

Critical ID Mappings — MEMORIZE THESE

The #1 time-waster is querying with the wrong ID format. The frontend uses slugs, the database uses internal IDs.

┌──────────────────────────────────────────────────────────┐
│  Route: /space/chrome-space-1/universe/paks-uni-1/vibe   │
│                                                          │
│  chrome-space-1  →  spaceId: "69250a03857479fe44376823"  │
│  paks-uni-1      →  universeId: "universe_176859..."     │
│                                                          │
│  ⚠️ NEVER query with "paks-uni-1" — zero results         │
│  ✅ ALWAYS use the internal long-form ID                  │
└──────────────────────────────────────────────────────────┘

Known ID Translations

Finding the Internal ID

If you don't know the internal ID, query space_modules or generated-modules without a universe filter and look at any document's universeId field:

// In Atlas: go to space_modules, find any doc, check universeId
{ spaceId: "69250a03857479fe44376823" }

Or check generation_checkpoints — every checkpoint has the universeId.

Common Queries — Copy-Paste Ready

"Were the latest modules saved?"

Step 1: Check generation_checkpoints (Vitto > vitto-mind):

{ sessionId: "modgen-9e2521fb" }

Look for status: "completed" and completedPhases containing all 7 phases.

Step 2: Check generated-modules (GoGrabSpace > ai-agents):

{ universeId: "universe_1768598939515_vfjz6wten", slug: { $regex: "fitness" } }

Check updatedAt — does it match the checkpoint's completedAt?

Step 3: Check space_modules (GoGrabSpace > space_chrome-space-1_*):

{ universeId: "universe_1768598939515_vfjz6wten", slug: { $regex: "fitness" } }

"What went wrong with a generation?"

// In generation_checkpoints:
{ sessionId: "modgen-XXXXXXXX" }

Check: status, error, currentPhase, completedPhases

"Show me everything created today"

{ createdAt: { $gte: ISODate("2026-02-23T00:00:00Z") } }

"Show me all modules for a specific generation run"

// In generated-modules — use the workflowId:
{ workflowId: "workflow-1771862265114-wfw9kes" }

"How many modules exist for this universe?"

// In generated-modules:
{ universeId: "universe_1768598939515_vfjz6wten" }
// Result count = total unique module definitions

// In space_modules:
{ universeId: "universe_1768598939515_vfjz6wten" }
// Result count = total space module entries (can have duplicates across runs)

"What's the full schema of a module?"

Go to generated-modules collection and expand any document. The actions[], embeddables[], and entities[] arrays contain the full module schema. Switch to JSON view ({} icon) and click the expand arrow on the first document.

Navigation Shortcuts in Atlas UI

Getting to the Right Collection Fast

1. Atlas URL pattern: https://cloud.mongodb.com/v2/{orgId}#/explorer/{clusterId}/{dbName}/{collection}/find
2. Tabs persist — once you open a collection, it stays as a tab at the top. Use tabs to switch quickly between collections.
3. JSON view ({} icon, top-right of results) is better for seeing nested arrays.
4. List view (default) is better for scanning many documents quickly.

Cluster Navigation

In the left sidebar:

▼ GoGrabSpace
  ▼ ai-agents           ← generated-modules lives here
  ▼ space_chrome-space-1_79fe44376823  ← space_modules lives here

▼ Vitto
  ▼ vitto-mind          ← generation_checkpoints lives here

Filtering Tips

• Atlas query bar uses MongoDB Extended JSON (similar to shell syntax)
• ISODate("...") works for date comparisons
• $regex works for pattern matching: { slug: { $regex: "fitness" } }
• Combine filters with comma: { universeId: "...", slug: { $regex: "..." } }
• Use $gte/$lte for date ranges
• Click "Explain" to see query performance
• Click "Reset" to clear the filter

Data Relationships

generation_checkpoints.sessionId  ──►  Frontend processId (URL param)
                                       e.g. modgen-9e2521fb

generated-modules.workflowId     ──►  Links to specific generation session
                                       e.g. workflow-1771862265114-wfw9kes

generated-modules.moduleId       ═══  space_modules.moduleId
                                       e.g. fitness-studio-class-management

generated-modules.spaceId        ═══  space_modules.spaceId
                                       e.g. 69250a03857479fe44376823

space_modules._id                      Unique per deploy (includes timestamp)
                                       e.g. mod-page-module-fitness-studio-class-management-1768941199145

Important: generated-modules Uses Upsert

The unique index is { moduleId: 1, spaceId: 1 }. Re-running generation for the same template updates existing docs, not creates new ones. So you'll only ever see ONE document per module per space — the latest version.

space_modules does NOT upsert — each deploy creates new entries with unique timestamp-based _ids. You may see duplicates across multiple generation runs.

Debugging Flowchart

Generation seems broken?
│
├─ Check generation_checkpoints
│  ├─ status: "failed" → Read the `error` field, done
│  ├─ status: "completed" → Pipeline worked, check downstream
│  └─ No document found → Backend-vitto-api never started, check server logs
│
├─ Checkpoint says "completed" but no modules?
│  ├─ Check generated-modules (ai-agents DB)
│  │  ├─ Docs found with recent updatedAt → Backend DEPLOY worked
│  │  └─ No recent docs → Bug 12: DEPLOY phase didn't persist
│  │
│  └─ Check space_modules (space DB)
│     ├─ Docs found → Frontend deploy worked
│     └─ No docs → Frontend crashed (Bug 10) before deployToUniverse()
│
└─ Modules in DB but not showing in UI?
   ├─ Check universeId matches between documents and the route
   ├─ Check isActive: true
   └─ Try hard refresh of frontend

Collection Size Reference (as of 2026-02-23)

Environment-Specific Notes

Local Development

• All backends run locally on ports 3000-3003
• MongoDB connections configured in .env.local
• Use tools/scripts/database/env-loader.js to load connection strings
• Connection strings: getMongoDBConnectionString() from env-loader

Atlas Access

• Organization: GoGrab Space
• Project: GoGrab Space
• Atlas URL: https://cloud.mongodb.com/v2/688796fab8924748e5c599d2#/explorer
• 4 clusters visible: GoGrab-Docs, GoGrabSpace, test-modules, Vitto

Backend API URL Tokens (Critical for API Calls)

Using the wrong token causes silent 404s — see CLAUDE.md rule #9.

Quick Index