Session 8 - Dual API Architecture & Backend Refactoring

Created backend-ai-api, shared authentication library, database naming conventions

Session 8: Dual API Architecture & Backend Refactoring

Date: December 12, 2025
Session ID: 8.1
Status: ✅ Complete

🎯 Session Goals

Extract AI workloads from backend-api to dedicated backend-ai-api
Create shared authentication library for reuse across APIs
Implement clear database naming conventions
Enable concurrent running of both APIs
Set up MCP (Model Context Protocol) for AI decision logging

✅ Completed Work

1. Created `backend-ai-api` Application

Location: apis/backend-ai-api/

A new NestJS application dedicated to AI workloads:

Port: 3001 (configurable via AI_API_PORT)
Databases: ai-agents, ai-context, ai-memory, ai-tenants
Features: Agent orchestration, decision logging, vector memory

Key Files:

src/main.ts - Custom [AI-API] logger with magenta color
src/app/app.module.ts - Multi-database MongoDB configuration
src/app/agents/ - Agent services and controllers

2. Created `@libs-api/auth-core` Library

Location: libs/libs-api/auth-core/

Shared authentication logic for both APIs:

AuthCoreModule.forRoot() - Configurable JWT authentication
JwtAuthGuard - Route protection
@CurrentUser() decorator - Extract user from JWT
@Public() decorator - Mark public routes

Usage:

import { AuthCoreModule } from '@libs-api/auth-core';

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

3. Created `@libs-api/backend-core` Library

Location: libs/libs-api/backend-core/

Shared backend configurations:

createMongooseConfig() - MongoDB factory for main API
createMongooseConfigForAI() - MongoDB factory for AI API
createCorsConfig() - CORS configuration
createDefaultValidationPipe() - Validation pipe
DEFAULT_THROTTLE_CONFIG - Rate limiting for main API
AI_THROTTLE_CONFIG - Rate limiting for AI API
AI_DATABASE_NAMES - Database name constants
AI_CONNECTION_NAMES - Connection name constants

4. Database Naming Convention

New Standard:

API	Database Prefix	Examples
`backend-api`	`gograb-*`	`gograb-api`, `gograb-core`
`backend-ai-api`	`ai-*`	`ai-agents`, `ai-context`, `ai-memory`
User spaces	`space_*`	`space_my-shop_abc123`

Configuration File: 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',
};

5. Custom NestJS Loggers

Both APIs have custom loggers with distinct colors:

backend-api (main.ts):

class ApiLogger extends ConsoleLogger {
  protected formatContext(context: string): string {
    return `\x1b[36m[API]\x1b[0m ${context}`;  // Cyan
  }
}

backend-ai-api (main.ts):

class AiApiLogger extends ConsoleLogger {
  protected formatContext(context: string): string {
    return `\x1b[35m[AI-API]\x1b[0m ${context}`;  // Magenta
  }
}

6. Concurrent Backend Running

Command: yarn dev:both-backends

Uses concurrently with colored prefixes:

{
  "dev:both-backends": "npx concurrently -n \"API,AI-API\" -c \"cyan,magenta\" \"yarn serve:backend\" \"yarn serve:backend-ai\""
}

7. MCP Configuration Fixed

Issue: spawn node ENOENT - Cursor couldn't find Node.js

Fix: Use absolute path to Node in ~/.cursor/mcp.json:

{
  "mcpServers": {
    "gograb-development-ai": {
      "command": "/Users/user/.local/share/fnm/node-versions/v24.11.1/installation/bin/node",
      "args": ["/path/to/editor2/tools/mcp-development-ai/dist/server.js"],
      "env": {
        "MONGODB_CONNECTION_STRING": "mongodb+srv://..."
      }
    }
  }
}

📁 Files Created/Modified

New Files

apis/backend-ai-api/ - Entire new application
libs/libs-api/auth-core/ - Entire new library
libs/libs-api/backend-core/src/lib/config/database-names.config.ts
libs/libs-api/backend-core/src/lib/config/mongodb.factory.ts
libs/libs-api/backend-core/src/lib/config/cors.factory.ts
libs/libs-api/backend-core/src/lib/config/throttler.config.ts
libs/libs-api/backend-core/src/lib/config/validation.config.ts
tools/scripts/database/clone-databases-to-new-naming.js
tools/scripts/database/migrate-ai-collections-to-context.js

Modified Files

apis/backend-api/src/main.ts - Custom [API] logger
apis/backend-api/src/app/app.module.ts - Use shared configs
apis/backend-api/src/app/ai-agents/ - Updated database names
tsconfig.base.json - Added @libs-api/* paths
package.json - Added new scripts
~/.cursor/mcp.json - Fixed node path

🔗 Architecture Diagram

Frontend (gograb-space:5200)
         │
         ├──────────────────────────────────────┐
         │                                      │
         ▼                                      ▼
   backend-api:3000                    backend-ai-api:3001
   ┌─────────────────┐                ┌─────────────────┐
   │ [API] Logger    │                │ [AI-API] Logger │
   │                 │                │                 │
   │ gograb-api      │                │ ai-agents       │
   │ gograb-core     │                │ ai-context      │
   │ space_*         │                │ ai-memory       │
   └────────┬────────┘                │ ai-tenants      │
            │                         │ ai-mcp-dev      │
            │                         └────────┬────────┘
            │                                  │
            └────────────────┬─────────────────┘
                             │
                   ┌─────────┴─────────┐
                   │ @libs-api/*       │
                   │ - auth-core       │
                   │ - backend-core    │
                   └───────────────────┘

🚀 How to Continue

Running the System

# Frontend
yarn dev:gograb

# Both backends (recommended)
yarn dev:both-backends

# Individual backends
yarn serve:backend      # Main API
yarn serve:backend-ai   # AI API

Using Shared Libraries

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

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

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

// Other configs
import { createCorsConfig, createDefaultValidationPipe, DEFAULT_THROTTLE_CONFIG } from '@libs-api/backend-core';

Using MCP

// Before starting a task
preflight({ task: "your task description" })

// After making decisions
log_decision({
  type: "implementation",
  question: "What approach to take?",
  options: ["A", "B"],
  chosen: "A",
  reasoning: "Because...",
  confidence: 0.9
})

📋 Pending/Future Work

Full AI API Migration: Move remaining AI services from backend-api to backend-ai-api
Vector Search Setup: Configure MongoDB Atlas Vector Search indexes for ai-memory
AI Agent Services: Complete implementation of agent orchestration
Frontend Integration: Update frontend services to use both APIs
Testing: Add comprehensive tests for new libraries

📚 Key Documentation

AGENTS.md - Updated with new backend architecture
README.md - Updated with dual API info
database-names.config.ts - Central database naming

Session 8 | December 12, 2025 | Dual API Architecture Complete