🤖 GoGrab Space - AI Agent Instructions

Directory: docs/english/GoGrab-Space/
Last Updated: January 5, 2026
Current Session: 22 (editor2 workspace) / 23 (gspace workspace) Schema Version: 5.0

⚡ START HERE - Required Reading Order

Before doing ANYTHING, read these in order:

1. This file (AGENTS.md) - You're here
2. README.md - Platform overview (87% complete)
3. modules/ - Read all files inside (module system is core to everything)
4. Check workspace setup - See if .env.local exists with WORKSPACE_ID
5. Latest Session - Check sessions/active.json for workspace and session number
6. Check MCP - Call preflight({ task: "your task" }) to get past decisions

⚠️ Session docs location (Schema v5.0): docs/english/sessions/{workspace}/session-X/

🏷️ Workspace Configuration (Schema v5.0)

What is a Workspace?

A workspace organizes sessions by feature/project (not by developer):

• Sessions route to: sessions/sessions-history/{workspace}/ (SINGLE SOURCE OF TRUTH)
• Session index: sessions/sessions-history/{workspace}/history.json (NEW)
• Docs route to: docs/english/sessions/{workspace}/

Setup

Create .env.local in repo root:

WORKSPACE_ID=gspace  # For GoGrab Space work

If not set, defaults to repo name ("editor2").

Examples

• WORKSPACE_ID=gspace → GoGrab Space feature work
• WORKSPACE_ID=mobile-app → Mobile app work
• No .env.local → Uses "editor2" (default)

NEW in v5.0

• Single Source of Truth: All session data in sessions/sessions-history/{workspace}/
• history.json: Quick index of all sessions per workspace
• Auto-Documentation: High-confidence decisions (≥95%) auto-generate markdown
• Test Session Isolation: Test sessions in _test_sessions/ subfolder

🎯 The Mission

"To produce the most advanced, incredible, groundbreaking, intelligent, robust and modern platform builder in the entire universe."

We are building the "Ferrari of Platform Builders" - a meta-modular system where:

• Everything is a module (structure + functionality unified)
• AI can generate complete modules
• Modules are reusable building blocks
• Visual + vibe coding workflows

🏗️ CRITICAL: Backend Architecture (Updated Dec 2025)

Two Backend APIs

Running the Backends

# Run main backend only
yarn serve:backend-api

# Run AI backend only
yarn serve:backend-ai

# Run BOTH simultaneously (recommended)
yarn serve:backends

The dev:both-backends command uses concurrently with colored prefixes:

• [API] (cyan) - Main backend logs
• [AI-API] (magenta) - AI backend logs

Shared Libraries (@libs-api/*)

Both backends share common code through these libraries:

🗄️ Database Architecture (Updated Dec 2025)

Database Naming Convention

MongoDB Cluster
├── gograb-api         # Main platform (users, spaces, subscriptions)
├── gograb-core        # Core platform data
├── gograb-analytics   # Analytics and metrics
│
├── ai-agents          # Agent tasks, decisions, patterns
├── ai-context         # AI usage, chat history, learning
├── ai-memory          # Vector embeddings, semantic search
├── ai-tenants         # User AI profiles
├── ai-mcp-dev         # mcp-gograb-ai development tools (Cursor AI) - Database stores MCP service data
│
└── space_{slug}_{id}  # Per-space tenant data

Using Database Names in Code

import { 
  AI_DATABASE_NAMES, 
  AI_CONNECTION_NAMES,
  API_DATABASE_NAMES 
} from '@libs-api/backend-core';

// In backend-ai-api modules:
MongooseModule.forRootAsync({
  connectionName: AI_CONNECTION_NAMES.AGENTS,
  useFactory: () => createMongooseConfigForAI(AI_DATABASE_NAMES.AGENTS),
})

// In services with @InjectModel:
@InjectModel(AgentTask.name, AI_CONNECTION_NAMES.AGENTS)

Important Constants File

Location: libs/libs-api/backend-core/src/lib/config/database-names.config.ts

export const AI_DATABASE_NAMES = {
  AGENTS: 'ai-agents',
  CONTEXT: 'ai-context',
  MEMORY: 'ai-memory',
  TENANTS: 'ai-tenants',
  MCP_DEV: 'ai-mcp-dev',
};

export const AI_CONNECTION_NAMES = {
  AGENTS: 'ai-agents',
  CONTEXT: 'ai-context',
  MEMORY: 'ai-memory',
  TENANTS: 'ai-tenants',
  MCP_DEV: 'ai-mcp-dev',
};

export const API_DATABASE_NAMES = {
  MAIN: 'gograb-api',
  CORE: 'gograb-core',
  ANALYTICS: 'gograb-analytics',
};

🚫 CRITICAL: DO NOT REINVENT - USE EXISTING SYSTEMS

Systems Already Built & Fully Functional

Key Documentation for These Systems

• Flash Persistence: theme-system/flash-persistence-integration.md
• Theme Styling: theme-system/theme-system.index.md
• Design Patterns: theme-system/design/design-prompts.md

🔐 Authentication System

Using @libs-api/auth-core

// In any NestJS module:
import { AuthCoreModule } from '@libs-api/auth-core';

@Module({
  imports: [
    AuthCoreModule.forRoot({
      jwtSecret: process.env.JWT_SECRET,
      jwtExpiresIn: '7d',
    }),
  ],
})
export class AppModule {}

Available Guards & Decorators

import { JwtAuthGuard, CurrentUser, Public } from '@libs-api/auth-core';

@Controller('protected')
@UseGuards(JwtAuthGuard)
export class MyController {
  
  @Public()  // Skip auth for this endpoint
  @Get('public')
  getPublic() { ... }
  
  @Get('me')
  getMe(@CurrentUser() user: JwtPayload) {
    return user;
  }
}

🔧 MongoDB Configuration

Using Shared Config Factories

import { 
  createMongooseConfig, 
  createMongooseConfigForAI,
  DEFAULT_THROTTLE_CONFIG,
  AI_THROTTLE_CONFIG,
} from '@libs-api/backend-core';

// For backend-api:
MongooseModule.forRootAsync({
  useFactory: () => createMongooseConfig('gograb-api'),
})

// For backend-ai-api:
MongooseModule.forRootAsync({
  connectionName: AI_CONNECTION_NAMES.AGENTS,
  useFactory: () => createMongooseConfigForAI(AI_DATABASE_NAMES.AGENTS),
})

MongoDB Options (Optimized)

Both config factories include:

• Connection pooling (min: 5, max: 50)
• Retry logic (5 retries with exponential backoff)
• Compression (zlib)
• Socket timeout (45s)
• Server selection timeout (5s)

🤖 MCP (Model Context Protocol) System v5.0

What is MCP?

MCP is our AI learning system. It logs decisions made during development to help future AI agents learn from past choices. v5.0 adds auto-documentation, simulation, and enhanced tracking.

Core MCP Tools

// BEFORE any task - get context:
preflight({ task: "your task description", categories: ["angular", "typescript"] })

// AFTER making decisions - log them:
log_decision({
  type: "implementation",
  question: "How should we structure this?",
  options: ["Option A", "Option B"],
  chosen: "Option A",
  reasoning: "Because...",
  confidence: 0.95  // ≥0.95 triggers auto-documentation!
})

// Find similar past decisions:
find_similar({ query: "How do we handle auth?" })

// Get codebase conventions:
get_conventions({ category: "angular" })

Enhanced MCP Tools (v5.0)

// Get comprehensive stats (git, outcomes, anti-patterns):
get_enhanced_stats()

// Get full session summary:
get_session_summary()

// Validate pending decisions:
run_outcome_validation()

// Learn from outcomes to update anti-patterns:
learn_from_outcomes()

// Initialize git tracking for session:
init_git_tracking()

Auto-Documentation (v5.0)

Decisions with ≥95% confidence or architecture/pattern types auto-generate markdown:

• Location: docs/english/sessions/{workspace}/session-X/
• Format: {sessionID}-{type}-{question-slug}.md

MCP Configuration

Location: ~/.cursor/mcp.json

{
  "mcpServers": {
    "gograb-development-ai": {
      "command": "/absolute/path/to/node",
      "args": ["/path/to/editor2/tools/mcp-development-ai/dist/server.js"],
      "env": {
        "MONGODB_CONNECTION_STRING": "mongodb+srv://..."
      }
    }
  }
}

Important: Use absolute path to node (e.g., /Users/user/.local/share/fnm/node-versions/v24.11.1/installation/bin/node)

📁 Documentation Structure

docs/english/GoGrab-Space/
│
├── README.md                        <- Platform overview & status
├── AGENTS.md                        <- YOU ARE HERE
│
├── modules/                         <- 🔴 CRITICAL - Read ALL files
│   ├── hybrid-module-creation.md    # ⭐ START HERE - The approach
│   ├── module-creation-guide.md     # Complete creation guide
│   ├── module-registration.md       # How modules register
│   ├── public-actions-guide.md      # Creating actions
│   ├── embeddable-components-guide.md # Creating widgets
│   └── modules-docs/                # Individual module documentation
│
├── libs/                            <- Library documentation
│   ├── libs-core/                   # Core libraries
│   ├── libs-structural/             # modularity-lib, singularity-lib
│   └── libs-ui/                     # UI components
│
├── architecture/                    <- System architecture decisions
│
├── theme-system/                    <- 🔴 MANDATORY for UI work
│
├── sessions/                        <- Session logs (check latest!)
│
└── backend/                         <- Backend API documentation

✅ Development Rules (MANDATORY)

Angular Rules

// ✅ Standalone components only
@Component({ standalone: true, ... })

// ✅ Use inject() function
private readonly service = inject(MyService);

// ✅ Separate files: .ts, .html, .scss
templateUrl: './my.component.html',
styleUrl: './my.component.scss'

// ✅ OnPush change detection
changeDetection: ChangeDetectionStrategy.OnPush

// ❌ NEVER: NgModules, constructor injection, inline templates

State Management

// ✅ Signals for local state
private readonly count = signal(0);

// ✅ autoFlashState for persistent state
private readonly settings = autoFlashState('settings', defaultSettings);

// ✅ RxJS for async operations
getData(): Observable<Data> { return this.http.get<Data>('/api/data'); }

// ❌ NEVER: Promises, setTimeout in production

Styling

// ✅ Use theme variables (see theme-system/THEME_CHEATSHEET.md)
background: var(--ux-surface);
color: var(--ux-on-surface);  // On colored bg: use --ux-on-{color}

// ✅ Use glassmorphism patterns
backdrop-filter: blur(16px);
background: rgba(var(--ux-surface-rgb), 0.8);

// ❌ NEVER: Hardcoded colors (#333, white), custom fonts not in theme

Backend Rules

// ✅ Use shared libraries
import { AI_DATABASE_NAMES, AI_CONNECTION_NAMES } from '@libs-api/backend-core';
import { AuthCoreModule, JwtAuthGuard } from '@libs-api/auth-core';

// ✅ Use database constants
@InjectModel(MyModel.name, AI_CONNECTION_NAMES.AGENTS)

// ❌ NEVER: Hardcode database names, duplicate auth logic

📋 Quick Reference Table

🎯 Session Workflow (Schema v5.0)

Starting a New Session

1. Read this file (AGENTS.md)
2. Check sessions/active.json for current workspace and session number
3. Call preflight({ task: "your task" }) via MCP
4. Check workspace history: sessions/sessions-history/{workspace}/history.json
5. Read the latest session docs in docs/english/sessions/{workspace}/session-X/
6. Continue work from where it left off

During the Session

• Call preflight() before major tasks
• Use existing systems (don't reinvent)
• Follow development rules (Angular, styling, state)
• Use flash persistence for frontend state
• Use theme-system for all styling
• Use @libs-api/* for backend shared code
• Log important decisions with log_decision() (≥95% confidence auto-documents!)

Ending a Session

• MCP auto-generates documentation for high-confidence decisions
• Session manifest auto-updated in sessions/sessions-history/{workspace}/
• Workspace history.json auto-updated by MCP
• ⚠️ Session docs go in: docs/english/sessions/{workspace}/session-X/
• Document pending tasks in session README.md

⚠️ Common Mistakes to Avoid

1. ❌ Creating new storage systems - Use @storage-system
2. ❌ Hardcoding styles - Use theme-system CSS variables
3. ❌ Using NgModules - Use standalone components
4. ❌ Using Promises - Use RxJS Observables
5. ❌ Using setTimeout - Use RxJS timer/delay
6. ❌ Constructor injection - Use inject() function
7. ❌ Inline templates - Separate .ts, .html, .scss files
8. ❌ Hardcoding database names - Use AI_DATABASE_NAMES / API_DATABASE_NAMES
9. ❌ Duplicating auth logic - Use @libs-api/auth-core
10. ❌ Ignoring MCP - Always call preflight() first!

🏆 Success Criteria

When completing tasks, ensure:

• Called preflight() before starting
• Uses existing systems (storage, theme, backend, auth-core)
• Follows Angular rules (standalone, inject, OnPush)
• Uses flash persistence for frontend state
• Uses theme-system for styling
• Uses @libs-api/* for backend shared code
• Uses database name constants (not hardcoded strings)
• Code compiles without errors
• Follows existing patterns in codebase
• Logged important decisions with log_decision()
• Updates relevant documentation

📚 Key Path Mappings

// Frontend paths
@libs-core/*          → libs/core/
@libs-foundational/*  → libs/libs-foundational/
@libs-ui/*            → libs/libs-ui/
@libs-ai/*            → libs/libs-ai/
@theme-system/*       → libs/theme-system/
@storage-system       → libs/libs-foundational/storage-system/

// Backend paths
@libs-api/auth-core   → libs/libs-api/auth-core/
@libs-api/backend-core → libs/libs-api/backend-core/

This file is the starting point for all AI agents working on GoGrab Space. Last Updated: January 5, 2026 | Session: 22 (editor2) / 23 (gspace) | Schema v5.0