Database Architecture
Complete map of all MongoDB databases, their purpose, collections, and data ownership rules
Database Architecture
Overview
GoGrab Space uses 4 MongoDB clusters serving 4 backend APIs with clearly separated concerns.
| Cluster | Env Variable | Databases | Purpose |
|---|---|---|---|
| Main Atlas | MONGODB_CONNECTION_STRING |
gograb-api, ai-agents, ai-context, ai-memory, ai-mcp-dev, ai-archive, space_* |
Platform + AI |
| Docs | MONGODB_CONNECTION_STRING_DOCS |
docs-database |
Documentation system |
| Vitto | VITTO_MONGODB_URI |
vitto-mind |
Vitto autonomous intelligence |
| Test Modules | (separate) | test |
Module system testing |
Data Classification
All data falls into one of these categories:
| Category | Where It Lives | Examples | Ownership |
|---|---|---|---|
| User Data | gograb-api |
Profiles, preferences, memories, billing | Belongs to the user. GDPR-deletable. |
| Platform Data | gograb-api |
Spaces, modules, templates, themes | Belongs to the platform. |
| AI System Data | ai-agents, ai-memory, ai-mcp-dev |
Agent tasks, embeddings, learning patterns | Belongs to the AI system. |
| Vitto Brain | vitto-mind |
Strategies, skills, execution traces | Belongs to Vitto's intelligence. |
| Tenant Data | space_* |
Per-space user content | Belongs to the space tenant. |
| Documentation | docs-database |
Doc files, analytics | Belongs to the docs system. |
| Cold Storage | ai-archive |
Old decisions, embeddings | Archived system data. |
Database Detail
gograb-api — Platform Core (Default Connection)
Purpose: All user-owned and platform-owned data. The single database a GDPR deletion request needs to hit for user data.
Backend: backend-api (default connection), backend-ai-api (platform connection)
| Collection | Purpose | Category |
|---|---|---|
users |
User accounts, credentials, roles | User Data |
user_agent_memories |
What AI agents know about each user (facts, preferences, skills) | User Data |
user_preferences |
User privacy/agent settings | User Data |
user_hierarchy |
Organization hierarchy | User Data |
platform_users |
Platform-level user profiles | User Data |
spaces |
User-created spaces | Platform Data |
modules |
Module definitions | Platform Data |
templates |
Space templates | Platform Data |
themes |
Theme definitions | Platform Data |
universes |
Universe groupings | Platform Data |
widgets |
Widget definitions | Platform Data |
hives |
Hive structures | Platform Data |
products |
E-commerce products | Platform Data |
orders |
E-commerce orders | Platform Data |
drafts |
Draft entities | Platform Data |
billing_accounts |
Billing accounts | User Data |
usage_records |
API usage tracking | User Data |
invoices |
Billing invoices | User Data |
deployments |
Deployment records | Platform Data |
mock_definitions |
API mock definitions | Platform Data |
sessions |
Auth sessions | User Data |
ai_chat_history |
Legacy chat history (pre-Session 98) | User Data |
temp_files |
Temporary file storage | Transient |
Why user_agent_memories is here: It's USER data — what agents remember about a specific person (their name, job title, preferences). It travels with the user, not with the AI system. GDPR deletion = one database.
ai-agents — Agent Orchestration
Purpose: Agent tasks, decisions, metrics, and orchestration state. This is AI SYSTEM data, not user data.
Backend: backend-api (named connection), backend-ai-api (named connection)
| Collection | Purpose |
|---|---|
agent_tasks |
Task execution records |
agent_decisions |
AI decision history |
agent_metrics |
Performance metrics |
agent_patterns |
Learned behavior patterns |
agent_calibrations |
Confidence calibration data |
agent_processes |
Running process state |
decisions |
Architecture/implementation decisions |
agent_knowledges |
Platform knowledge base |
platform_patterns |
Platform-level patterns |
builder_profiles |
Space builder AI profiles |
tenant_user_profiles |
Per-tenant AI user profiles |
tenant_user_interactions |
Per-tenant interaction history |
configuration_sessions |
Module configuration sessions |
generated_modules |
AI-generated module records |
deployment_snapshots |
Deployment state snapshots |
space_agent_tasks |
Space-specific agent tasks |
space_builder_preferences |
Space builder AI preferences |
chat_sessions |
Chat session records (Session 98+) |
mcp_projects |
MCP project configurations |
ai-memory — Vector Embeddings
Purpose: Semantic search and vector embeddings. Separated for performance (vector indexes are memory-intensive).
Backend: backend-ai-api (named connection)
| Collection | Purpose |
|---|---|
agent_embeddings |
Vector embeddings for semantic search |
ai-context — AI Usage Tracking
Purpose: API usage metrics for AI services.
Backend: backend-api (named connection)
| Collection | Purpose |
|---|---|
ai_usages |
AI API call tracking |
ai-mcp-dev — MCP & Super-Intelligence
Purpose: MCP development tools, learning system, super-intelligence features. This is the AI's "learning brain."
Backend: backend-ai-api (named connection)
| Collection | Purpose |
|---|---|
sessions |
MCP session state |
session_counters |
Session ID generation |
mcp_configs |
MCP configuration |
mcp_usages |
MCP API call tracking |
handoffs |
Agent handoff records |
agent_registries |
Registered agent catalog |
core_rules |
Codebase rules and conventions |
learned_patterns |
Patterns learned from code |
trigger_states |
Automation trigger state |
episodes |
Super-intelligence episodes |
causal_graphs/nodes/edges |
Causal reasoning graphs |
reflections |
AI self-reflection records |
knowledge_gaps |
Identified knowledge gaps |
curiosity_triggers |
Proactive learning triggers |
learning_requests |
Queued learning tasks |
simulations |
Decision simulations |
ai-archive — Cold Storage
Purpose: Archived data for old decisions and embeddings. Keeps active databases lean.
Backend: backend-ai-api (named connection)
| Collection | Purpose |
|---|---|
archived_decisions |
Old archived decisions |
archived_embeddings |
Old archived embeddings |
archive_jobs |
Archive job state |
archive_policies |
Archive retention policies |
vitto-mind — Vitto's Autonomous Intelligence
Purpose: Vitto's own brain — operational state, strategies, skills, execution history. Runs on a SEPARATE cluster.
Backend: backend-vitto-api (default connection)
| Collection | Purpose |
|---|---|
execution_traces |
Task execution history |
strategy_memories |
Learned strategies |
agent_performances |
Self-performance metrics |
user_patterns |
Observed user behavior patterns (NOT user-owned data) |
active_tasks |
Currently running tasks |
autonomy_configs |
Autonomy level configuration |
autonomy_checkpoints |
Approval checkpoints |
codebase_entries |
Indexed codebase knowledge |
vitto_skills |
Vitto's skill definitions |
customer_sessions |
Customer interaction sessions |
proactive_alerts |
Proactive alert configuration |
vitto_memories |
Vitto's own memory (system-level, NOT per-user) |
Key distinction: vitto_memories is Vitto's system-level memory (how to do things). user_agent_memories in gograb-api is what Vitto knows about each user (who they are). Different concerns.
docs-database — Documentation System
Purpose: Documentation content and analytics. Runs on a SEPARATE cluster.
Backend: backend-docs-api (named connection)
| Collection | Purpose |
|---|---|
doc_files |
Documentation file content |
doc_projects |
Documentation projects |
doc_settings |
Documentation settings |
page_views |
Documentation analytics |
search_events |
Search analytics |
space_* — Per-Tenant Data
Purpose: Each space gets its own database for complete data isolation.
Naming: space_{slug}_{id} (e.g., space_chrome-space-1_79fe4437a631)
Backend: backend-api (dynamic connections)
Contents vary per space but typically include user content, pages, configurations, and space-specific data.
Deprecated / Unused
| Database/Config | Status | Action |
|---|---|---|
gograb-core |
Defined in API_DATABASE_NAMES but NO collections registered |
Remove from config |
gograb-analytics |
Defined in API_DATABASE_NAMES but NO collections registered |
Remove from config |
ai-tenants |
Marked DEPRECATED in code, superseded by space-specific data | Remove from config |
Rules for New Data
When creating a new collection, ask:
- Does this data belong to a user? (deletable on request) →
gograb-api - Is this AI system intelligence? (agent tasks, decisions, patterns) →
ai-agents - Is this a vector embedding? →
ai-memory - Is this MCP/learning data? →
ai-mcp-dev - Is this Vitto's operational state? →
vitto-mind - Is this documentation? →
docs-database - Is this space-specific tenant data? →
space_* - Is this old data being archived? →
ai-archive
Connection Configuration
Code references
- Database names:
libs/libs-api/backend-core/src/lib/config/database-names.config.ts - Connection factories:
libs/libs-api/backend-core/src/lib/config/mongoose.config.ts - backend-api module:
apis/backend-api/src/app/app.module.ts - backend-ai-api module:
apis/backend-ai-api/src/app/app.module.ts - backend-vitto-api module:
apis/backend-vitto-api/src/app/app.module.ts - UserAgentMemory module:
apis/backend-ai-api/src/app/shared/user-agent-memory.module.ts
Environment variables
# Main cluster (gograb-api + all ai-* databases)
MONGODB_CONNECTION_STRING=mongodb+srv://...
# Default database name for main API
MONGODB_DATABASE=gograb-api
# Docs cluster
MONGODB_CONNECTION_STRING_DOCS=mongodb+srv://...
# Vitto cluster
VITTO_MONGODB_URI=mongodb+srv://...
Last Updated: February 11, 2026 Session: 105 Status: Source of truth for all database decisions