Backend AI API Documentation

Dedicated AI backend service for training, MCP, agents, and platform intelligence

Backend AI API Documentation

The Backend AI API is a dedicated NestJS backend service running on port 3001 (locally) that handles all AI-specific functionality for the GoGrab platform.

🎯 Purpose

The Backend AI API is separate from backend-api to:

Isolate AI-specific workloads
Scale independently
Manage AI-specific databases (ai-agents, ai-memory, ai-tenants)
Provide dedicated resources for training and inference

🏗️ Architecture

┌─────────────────────────────────────────────────┐
│              GoGrab Platform                    │
├─────────────────────────────────────────────────┤
│                                                 │
│  Frontend (gograb-space)                        │
│  Port 5200 (local)                              │
│         │                                       │
│         ├─────────────┬────────────────┐        │
│         │             │                │        │
│         ▼             ▼                ▼        │
│                                                 │
│  backend-api     backend-ai-api                 │
│  Port 3000       Port 3001                      │
│  /api/*          /ai-api/*                      │
│                                                 │
│  Services:       Services:                      │
│  - Auth          - Platform AI Training         │
│  - Users         - MCP Tools                    │
│  - Spaces        - Agent Orchestration          │
│  - Modules       - Vector Memory                │
│  - Analytics     - Intelligence Layer           │
│                  - Training Datasets            │
│                                                 │
└─────────────────────────────────────────────────┘

📚 Documentation

Deployment Instructions - Complete Railway deployment guide
Architecture - System design and components (coming soon)
API Reference - Endpoint documentation (coming soon)

🚀 Quick Start

Local Development

# Start backend-ai-api only
yarn serve:backend-ai

# Or start both backends together
yarn serve:backends

Backend AI API will be available at: http://localhost:3001/ai-api

Health Check

# Local
curl http://localhost:3001/ai-api/health

# Production
curl https://backend-ai-api-production.up.railway.app/ai-api/health

🔑 Key Features

1. Platform AI Training

Train specialized agents for module/widget generation
Manage training datasets
Track agent performance and learning

2. MCP (Model Context Protocol) Services

Intelligent preflight context
Decision logging and pattern mining
Agent specialization tracking
Cross-tier intelligence transfer

3. Agent Orchestration

Route requests to specialized agents
Manage agent capabilities
Dynamic agent creation
Sub-agent hierarchies

4. Vector Memory & Embeddings

Semantic search for agent decisions
Pattern matching and retrieval
Context-aware suggestions

5. Platform Intelligence

Cross-teaching between development and platform AI
Predictive decision intelligence
Self-improving agent systems

🔧 Configuration

Environment Variables

# Required
NODE_ENV=production
PORT=3001  # Local (Railway uses dynamic PORT)
MONGODB_CONNECTION_STRING=your-connection-string
JWT_SECRET=your-secret  # MUST match backend-api!

# Optional
ANTHROPIC_API_KEY=sk-ant-xxx
OPENAI_API_KEY=sk-xxx

Shared with backend-api

⚠️ CRITICAL: The following must be identical between backend-api and backend-ai-api:

JWT_SECRET - Enables token sharing for authentication
SYSTEM_TOKEN - For internal service communication
MONGODB_CONNECTION_STRING - Uses same cluster, different databases

📊 Databases

The Backend AI API uses dedicated MongoDB databases:

Database	Purpose
`ai-agents`	Agent definitions, capabilities, performance
`ai-memory`	Vector embeddings, semantic search
`ai-tenants`	Tenant-specific AI learning (future)
`ai-context`	Shared context with backend-api

🌐 Endpoints

Health & Status

GET /ai-api/health - Service health check
GET /ai-api/platform/stats - Platform statistics

Platform Agents

GET /ai-api/platform/agents - List all agents
POST /ai-api/platform/agents/:agentId/train - Train agent
GET /ai-api/platform/agents/:agentId/knowledge - Get agent knowledge

MCP Tools (Development AI)

Accessible via MCP server, not HTTP

🔗 Related Documentation

Backend API Documentation

MCP Documentation

Platform AI

AI Libraries - NX libraries for AI features
Agent Training Center
Agent Knowledge

🐛 Troubleshooting

Common Issues

Port Already in Use:

# Kill process on port 3001
lsof -ti:3001 | xargs kill -9

Authentication Fails:

Verify JWT_SECRET matches backend-api
Check token is being sent in Authorization header
Test token from backend-api works on backend-ai-api

MongoDB Connection Fails:

Check connection string URL encoding
Verify IP whitelist (0.0.0.0/0 for Railway)
Test connection with mongosh

📞 Support

Railway Dashboard: https://railway.com/project/3990549d-4313-47e4-9682-d17b382bdba2/service/fa00811a-db8e-4232-a23f-2becd96615c7
Deployment Guide: deployment-instructions
Backend API Docs: Backend API Overview

✅ Status

✅ Deployed: Railway (production)
✅ Running: Port 3001 (local), Dynamic (Railway)
✅ Health Check: Passing
✅ Authentication: Shared with backend-api
✅ Documentation: Complete

Last Updated: December 15, 2025
Version: 1.0.0
Status: Production-Ready ✅