🏗️ Architecture: How should data be organized between user data, agent data, ...

Date: 2026-01-31
Time: 16:12:39 UTC
Session: editor2-75.16
Agent: backend
Confidence: 100%
Status: ✅ Documented

📋 Decision Context

Question:

How should data be organized between user data, agent data, and custom agent data in a multi-tenant AI platform?

Task: Session 75.15: Define multi-tenant data architecture for AI platform with custom agents support

🎯 Decision Made

Chosen:

Three-tier data segregation: (1) User Space databases for user-owned data, (2) Shared ai-agents database for platform agent operations, (3) Custom agent collections within user Space databases for user-created agents

Options Considered:

1. Single shared database for everything
2. Database-per-user only
3. Three-tier segregation with Space databases

💭 Reasoning

THE GOLDEN RULE: User data NEVER lives in shared databases.

Data Architecture Overview

Tier 1: User Space Databases (space_{slug}_{id})

• Owner: The user
• Location: Dedicated MongoDB database per user
• Contains: Universes, modules, themes, pages, widgets, flows, AND files generated FOR the user
• Access: ONLY via backend-api (port 3000) using SpaceDatabaseService
• Examples:
  • User's universe layouts
  • User's custom modules
  • AI-generated files/reports belonging to user
  • User's custom agent configurations (future)

Tier 2: Shared AI-Agents Database (ai-agents / ai-mcp-dev)

• Owner: The platform
• Location: Shared MongoDB database
• Contains: Platform-level agent operations, decisions, handoffs, conventions
• Access: Direct from backend-ai-api (port 3001)
• Examples:
  • Handoff records (with spaceId linking to user)
  • Decision logs for learning
  • Agent sessions and events
  • Platform conventions

Tier 3: Custom Agent Data (within user Space)

• Owner: The user
• Location: Collections within user's Space database
• Contains: User-created custom agents, their configurations, their outputs
• Access: Via backend-api SpaceDatabaseService
• Future collections:
  • space_agents - User's custom agent definitions
  • space_agent_runs - Execution history
  • space_agent_memory - Per-agent persistent memory
  • files.chunks/files.files - GridFS for agent outputs

Routing Rules

1. backend-ai-api → backend-api (HTTP): For ANY user-specific data

   • File uploads: POST /api/spaces/:spaceId/files/internal
   • Module operations: POST /api/spaces/:spaceId/modules
   • Universe operations: POST /api/spaces/:spaceId/universes

2. backend-ai-api → MongoDB directly: ONLY for shared platform data

   • Handoff creation/updates
   • Decision logging
   • Agent status tracking

Why This Matters for Custom Agents

When users create custom agents:

• Agent definition → space_agents in user's Space DB
• Agent memory → space_agent_memory in user's Space DB
• Agent outputs → GridFS in user's Space DB
• Agent handoffs → Shared handoffs collection WITH spaceId reference

This enables:

• Users own their agent configurations
• Users can export/import agents
• Users can share agents between Spaces
• Platform can still track handoffs globally for learning

📁 Files Involved

• apis/backend-api/src/app/spaces/space-database.service.ts
• apis/backend-api/src/app/spaces/space-files.controller.ts
• apis/backend-ai-api/src/app/vitto/vitto-file-storage.service.ts
• apis/backend-ai-api/src/app/schemas/handoff.schema.ts
• docs/english/GoGrab-Space/guides/PLATFORM-MASTER-GUIDE.md

🔗 Related

• Decision ID: dev_1769875959111_k6ge5yp
• Session: 75
• Workspace: editor2

Auto-generated by MCP Smart Consolidation