+-----------------------------------------------------------------------------------+
|                           CONVEYOR AI CHAT SYSTEM                                  |
+-----------------------------------------------------------------------------------+
|                                                                                    |
|  +------------------------------------------+  +--------------------------------+  |
|  |           CHAT INTERFACE                 |  |        MCP SERVER              |  |
|  |  (ViteJS + HeroUI + WebSocket Client)   |  |    (Cloud Run Service)         |  |
|  |                                          |  |                                |  |
|  |  +------------------------------------+  |  |  - Claude Code Integration    |  |
|  |  | Chat Input / Message History       |  |  |  - Tool Registry              |  |
|  |  | Command Palette / Quick Actions    |  |  |  - Session Management         |  |
|  |  | WASM Module Runner (shared-ai)     |  |  |  - OAuth 2.0 Token Exchange   |  |
|  |  +------------------------------------+  |  +--------------------------------+  |
|  +------------------------------------------+                                      |
|                         |                                                          |
|                         v                                                          |
|  +-----------------------------------------------------------------------------------+
|  |                          CHAT ORCHESTRATOR (Cloud Run)                            |
|  |  +-------------+  +-----------------+  +----------------+  +----------------+    |
|  |  | Intent      |  | Command         |  | Context        |  | Response       |    |
|  |  | Classifier  |  | Parser          |  | Manager        |  | Generator      |    |
|  |  | (Gemini)    |  | (Regex + NLP)   |  | (Redis/PG)     |  | (Gemini 2.5)   |    |
|  |  +-------------+  +-----------------+  +----------------+  +----------------+    |
|  +-----------------------------------------------------------------------------------+
|                         |                                                          |
|                         v                                                          |
|  +-----------------------------------------------------------------------------------+
|  |                           FUNCTION DISPATCHER                                     |
|  |                                                                                   |
|  |     +----------------+  +----------------+  +----------------+  +-------------+   |
|  |     | case-manager   |  | simulation-    |  | db-query-      |  | airtable-   |   |
|  |     | Cloud Function |  | agent          |  | agent          |  | agent       |   |
|  |     |                |  | Cloud Function |  | Cloud Function |  | Cloud Func  |   |
|  |     +----------------+  +----------------+  +----------------+  +-------------+   |
|  |                                                                                   |
|  +-----------------------------------------------------------------------------------+
|                         |                                                          |
|                         v                                                          |
|  +-----------------------------------------------------------------------------------+
|  |                           DATA LAYER                                              |
|  |  +-------------------+  +-------------------+  +--------------------+             |
|  |  | Cloud SQL         |  | Airtable          |  | Secret Manager     |             |
|  |  | PostgreSQL        |  | (Cases, Clients)  |  | (API Keys, OAuth)  |             |
|  |  | (RuVector + RL)   |  |                   |  |                    |             |
|  |  +-------------------+  +-------------------+  +--------------------+             |
|  +-----------------------------------------------------------------------------------+
|                                                                                    |
+-----------------------------------------------------------------------------------+

                                    USER
                                      |
                    +----------------+------------------+
                    |                                   |
                    v                                   v
            +---------------+                  +-----------------+
            | Web Interface |                  | Claude Code     |
            | (chat-ui)     |                  | (MCP Protocol)  |
            +-------+-------+                  +--------+--------+
                    |                                   |
                    |     WebSocket (wss://)            |
                    |                                   |
                    v                                   v
            +----------------------------------------------+
            |           chat-orchestrator                   |
            |              (Cloud Run)                      |
            |                                               |
            |  +------------------------------------------+ |
            |  |              MESSAGE ROUTER              | |
            |  |                                          | |
            |  |   /chat  --> Intent Classifier           | |
            |  |   /cmd   --> Command Parser              | |
            |  |   /mcp   --> MCP Protocol Handler        | |
            |  |   /ws    --> WebSocket Manager           | |
            |  +------------------------------------------+ |
            |                                               |
            |  +------------------------------------------+ |
            |  |            GEMINI INTEGRATION            | |
            |  |                                          | |
            |  |   Model: gemini-2.5-pro                  | |
            |  |   Context Window: 1M tokens             | |
            |  |   Function Calling: Enabled             | |
            |  +------------------------------------------+ |
            +----------------------------------------------+
                    |
                    | HTTPS (Internal)
                    |
    +---------------+---------------+---------------+
    |               |               |               |
    v               v               v               v
+--------+   +-----------+   +----------+   +---------+
| case-  |   | simulation|   | db-query |   | airtable|
| manager|   | -agent    |   | -agent   |   | -agent  |
+--------+   +-----------+   +----------+   +---------+

/<command> [subcommand] [--flag=value] [positional args]

// services/FunctionExecutor.ts
class FunctionExecutor {
  // Detect intent from natural language
  detectIntent(input: string): FunctionCallResult | null;

  // Execute function call against Cloud Functions
  execute(functionCall: FunctionCallResult): Promise<FunctionExecutionResult>;

  // Process natural language end-to-end
  processNaturalLanguage(input: string): Promise<FunctionExecutionResult | null>;
}

User Input → Gemini AI → Function Call Decision → FunctionExecutor → Cloud Function → Result → Gemini → Natural Language Response

interface ChatResponse {
  id: string;                    // Message UUID
  timestamp: string;             // ISO 8601
  type: 'text' | 'data' | 'chart' | 'error';
  content: string;               // Human-readable response
  data?: Record<string, any>;    // Structured data payload
  source: string;                // Originating function
  metadata: {
    tokens_used: number;
    latency_ms: number;
    function_calls: string[];
  };
}

// chat-orchestrator/src/dispatcher/FunctionDispatcher.ts
interface CloudFunctionConfig {
  name: string;
  url: string;
  timeout: number;
  retries: number;
}

const CLOUD_FUNCTIONS: Record<string, CloudFunctionConfig> = {
  'case-manager': {
    name: 'case-manager',
    url: 'https://case-manager-hwqrrwrlna-uc.a.run.app',
    timeout: 30000,
    retries: 2,
  },
  'simulation-agent': {
    name: 'simulation-agent',
    url: 'https://simulation-agent-hwqrrwrlna-uc.a.run.app',
    timeout: 60000,
    retries: 1,
  },
  'db-query-agent': {
    name: 'db-query-agent',
    url: 'https://db-query-agent-hwqrrwrlna-uc.a.run.app',
    timeout: 30000,
    retries: 2,
  },
  'airtable-agent': {
    name: 'airtable-agent',
    url: 'https://airtable-agent-hwqrrwrlna-uc.a.run.app',
    timeout: 30000,
    retries: 2,
  },
};

// chat-orchestrator/src/ai/GeminiClient.ts
import { GoogleGenerativeAI } from '@google/generative-ai';

interface GeminiConfig {
  model: 'gemini-2.5-pro';
  maxOutputTokens: 8192;
  temperature: 0.7;
  topP: 0.95;
  tools: GeminiFunctionTool[];
}

const GEMINI_TOOLS: GeminiFunctionTool[] = [
  {
    name: 'query_cases',
    description: 'Query case data from the case management system',
    parameters: {
      type: 'object',
      properties: {
        action: { type: 'string', enum: ['list', 'get', 'search', 'stats'] },
        caseId: { type: 'string' },
        filters: { type: 'object' },
      },
    },
  },
  {
    name: 'run_simulation',
    description: 'Run RL simulation for case strategy optimization',
    parameters: {
      type: 'object',
      properties: {
        action: { type: 'string', enum: ['run_qlearning', 'get_optimal', 'stats'] },
        caseType: { type: 'string' },
        strategy: { type: 'string' },
      },
    },
  },
  {
    name: 'query_database',
    description: 'Execute database queries and generate reports',
    parameters: {
      type: 'object',
      properties: {
        action: { type: 'string', enum: ['query', 'report', 'schema', 'analytics'] },
        query: { type: 'string' },
        reportType: { type: 'string' },
      },
    },
  },
  {
    name: 'sync_airtable',
    description: 'Synchronize and query Airtable data',
    parameters: {
      type: 'object',
      properties: {
        action: { type: 'string', enum: ['sync', 'query', 'upsert', 'analyze'] },
        tableName: { type: 'string' },
        data: { type: 'object' },
      },
    },
  },
];

// chat-ui/src/wasm/WasmRunner.ts
import { QLearning, MonteCarlo, MinCut, VectorOps } from '@conveyor/shared-ai';

interface WasmModules {
  qlearning: typeof QLearning;
  montecarlo: typeof MonteCarlo;
  mincut: typeof MinCut;
  vectors: typeof VectorOps;
}

export class WasmRunner {
  private modules: WasmModules;
  private initialized: boolean = false;

  async initialize(): Promise<void> {
    // Load WASM modules from shared-ai package
    this.modules = {
      qlearning: await import('@conveyor/shared-ai/ml/QLearning'),
      montecarlo: await import('@conveyor/shared-ai/simulation/MonteCarlo'),
      mincut: await import('@conveyor/shared-ai/graph/MinCut'),
      vectors: await import('@conveyor/shared-ai/vectors/VectorOps'),
    };
    this.initialized = true;
  }

  async runLocalPrediction(caseData: CaseInput): Promise<StrategyPrediction> {
    // Run Q-Learning locally for instant predictions
    const ql = new this.modules.qlearning.QLearning({
      learningRate: 0.1,
      discountFactor: 0.95,
      explorationRate: 0.1,
    });

    // Load cached Q-table from IndexedDB
    const cachedQTable = await this.loadCachedQTable();
    if (cachedQTable) {
      ql.importQTable(cachedQTable);
    }

    return ql.getOptimalAction(caseData.stateKey);
  }
}

// mcp-server/src/server.ts
import { Server } from '@modelcontextprotocol/sdk/server';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio';

const server = new Server({
  name: 'conveyor-ai-mcp',
  version: '1.0.0',
});

// Register tools for Claude Code integration
server.setRequestHandler('tools/list', async () => ({
  tools: [
    {
      name: 'conveyor_case_query',
      description: 'Query Conveyor AI case management system',
      inputSchema: {
        type: 'object',
        properties: {
          action: { type: 'string' },
          caseId: { type: 'string' },
          filters: { type: 'object' },
        },
      },
    },
    {
      name: 'conveyor_simulation',
      description: 'Run RL simulations for case strategy',
      inputSchema: {
        type: 'object',
        properties: {
          action: { type: 'string' },
          caseType: { type: 'string' },
        },
      },
    },
    {
      name: 'conveyor_analytics',
      description: 'Generate analytics and reports',
      inputSchema: {
        type: 'object',
        properties: {
          reportType: { type: 'string' },
          period: { type: 'string' },
        },
      },
    },
  ],
}));

server.setRequestHandler('tools/call', async (request) => {
  const { name, arguments: args } = request.params;

  // Route to appropriate Cloud Function
  const response = await functionDispatcher.dispatch(name, args);

  return {
    content: [{ type: 'text', text: JSON.stringify(response) }],
  };
});

+-----------------------------------------------------------------------------------+
|                         AI SUGGESTIONS ARCHITECTURE                                |
+-----------------------------------------------------------------------------------+
|                                                                                    |
|  +------------------+     +-------------------+     +------------------------+     |
|  | SuggestionsPanel |     | useSuggestions    |     | suggestions.worker.ts  |     |
|  | (React Component)|<--->| (React Hook)      |<--->| (Web Worker Thread)    |     |
|  |                  |     |                   |     |                        |     |
|  | - Clickable cards|     | - State mgmt      |     | - Background processing|     |
|  | - Source links   |     | - Worker comms    |     | - Debounced API calls  |     |
|  | - Priority badges|     | - Context updates |     | - Response caching     |     |
|  +------------------+     +-------------------+     +------------------------+     |
|                                                              |                     |
|                                                              | HTTPS               |
|                                                              v                     |
|                                               +---------------------------+        |
|                                               |   suggestion-agent        |        |
|                                               |   (Cloud Function Gen2)   |        |
|                                               |                           |        |
|                                               |  - Gemini 3 Flash/Pro    |        |
|                                               |  - Google Search Grounding|        |
|                                               |  - Structured JSON Output |        |
|                                               +---------------------------+        |
|                                                                                    |
+-----------------------------------------------------------------------------------+

// suggestion-agent/index.js - Gemini 3 Structured Output
const SUGGESTION_SCHEMA = {
  type: 'object',
  properties: {
    suggestions: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          id: { type: 'string' },
          type: { type: 'string', enum: ['command', 'insight', 'task', 'optimization', 'learning'] },
          title: { type: 'string' },
          description: { type: 'string' },
          command: { type: 'string' },
          priority: { type: 'string', enum: ['high', 'medium', 'low'] },
          relevanceScore: { type: 'number' },
          grounded: { type: 'boolean' },
          sources: {
            type: 'array',
            items: {
              type: 'object',
              properties: {
                title: { type: 'string' },
                url: { type: 'string' },
              },
            },
          },
        },
        required: ['id', 'type', 'title', 'description', 'priority', 'relevanceScore'],
      },
    },
    analysis: {
      type: 'object',
      properties: {
        sessionSummary: { type: 'string' },
        topicsDiscussed: { type: 'array', items: { type: 'string' } },
        userIntent: { type: 'string' },
        nextBestAction: { type: 'string' },
      },
    },
    groundingMetadata: {
      type: 'object',
      properties: {
        searchQueries: { type: 'array', items: { type: 'string' } },
        sourcesUsed: { type: 'number' },
      },
    },
  },
  required: ['suggestions', 'analysis'],
};

// Enable dynamic grounding with Google Search
import { DynamicRetrievalMode } from '@google/generative-ai';

const modelConfig = {
  model: 'gemini-3-flash-preview', // or 'gemini-3-pro-preview'
  generationConfig: {
    responseMimeType: 'application/json',
    responseSchema: SUGGESTION_SCHEMA,
  },
  tools: [{
    googleSearchRetrieval: {
      dynamicRetrievalConfig: {
        mode: DynamicRetrievalMode.MODE_DYNAMIC,
        dynamicThreshold: 0.3, // Use grounding when confidence < 70%
      },
    },
  }],
};

// useSuggestions.ts - Hook for worker communication
interface WorkerMessage {
  type: 'analyze' | 'quick' | 'data_driven' | 'cancel';
  context: SessionContext;
  options?: { enableGrounding?: boolean; model?: string };
  requestId?: string;
}

interface WorkerResponse {
  type: 'suggestions' | 'error' | 'status';
  data?: SuggestionsResponse;
  error?: string;
  timing?: { startTime: number; endTime: number; duration: number };
}

// chat-orchestrator/src/websocket/WebSocketManager.ts
import { WebSocketServer, WebSocket } from 'ws';

interface WebSocketMessage {
  type: 'subscribe' | 'unsubscribe' | 'message' | 'status';
  channel?: string;
  payload?: any;
}

export class WebSocketManager {
  private wss: WebSocketServer;
  private channels: Map<string, Set<WebSocket>> = new Map();

  constructor(server: http.Server) {
    this.wss = new WebSocketServer({ server, path: '/ws' });
    this.setupHandlers();
  }

  private setupHandlers(): void {
    this.wss.on('connection', (ws, req) => {
      // Authenticate via query param or header
      const token = new URL(req.url, 'http://localhost').searchParams.get('token');
      if (!this.validateToken(token)) {
        ws.close(4001, 'Unauthorized');
        return;
      }

      ws.on('message', (data) => {
        const msg: WebSocketMessage = JSON.parse(data.toString());
        this.handleMessage(ws, msg);
      });
    });
  }

  broadcast(channel: string, payload: any): void {
    const subscribers = this.channels.get(channel);
    if (subscribers) {
      const message = JSON.stringify({ type: 'message', channel, payload });
      subscribers.forEach((ws) => {
        if (ws.readyState === WebSocket.OPEN) {
          ws.send(message);
        }
      });
    }
  }
}

+--------+     +---------------+     +----------------+     +----------+
|  User  | --> | Google OAuth  | --> | Token Exchange | --> | Chat API |
+--------+     | (Identity     |     | Service        |     |          |
               | Platform)     |     +----------------+     +----------+
               +---------------+           |
                                           v
                               +-----------------------+
                               | Cloud SQL             |
                               | (Session Store)       |
                               +-----------------------+

// chat-orchestrator/src/middleware/rateLimiter.ts
import { RateLimiterRedis } from 'rate-limiter-flexible';

const rateLimiters = {
  chat: new RateLimiterRedis({
    storeClient: redisClient,
    keyPrefix: 'rl:chat',
    points: 100,          // 100 requests
    duration: 60,         // per minute
    blockDuration: 60,    // block for 1 minute if exceeded
  }),

  commands: new RateLimiterRedis({
    storeClient: redisClient,
    keyPrefix: 'rl:cmd',
    points: 50,           // 50 commands
    duration: 60,         // per minute
  }),

  mcp: new RateLimiterRedis({
    storeClient: redisClient,
    keyPrefix: 'rl:mcp',
    points: 200,          // 200 MCP requests
    duration: 60,         // per minute
  }),
};

// chat-orchestrator/src/auth/permissions.ts
interface Permission {
  action: string;
  resource: string;
  conditions?: Record<string, any>;
}

const ROLE_PERMISSIONS: Record<string, Permission[]> = {
  admin: [
    { action: '*', resource: '*' },
  ],
  analyst: [
    { action: 'read', resource: 'cases' },
    { action: 'read', resource: 'simulations' },
    { action: 'execute', resource: 'reports' },
    { action: 'read', resource: 'airtable' },
  ],
  operator: [
    { action: 'read', resource: 'cases' },
    { action: 'create', resource: 'cases' },
    { action: 'update', resource: 'cases', conditions: { ownedBy: '${userId}' } },
    { action: 'execute', resource: 'simulations' },
  ],
  viewer: [
    { action: 'read', resource: 'cases' },
    { action: 'read', resource: 'reports' },
  ],
};

+-----------------------------------------------------------------------------------+
|                        GOOGLE CLOUD PLATFORM (new-project-473022)                  |
+-----------------------------------------------------------------------------------+
|                                                                                    |
|  +---------------------------+  +---------------------------+                     |
|  |     Cloud Run Region      |  |     Cloud SQL Region      |                     |
|  |     (us-central1)         |  |     (us-central1)         |                     |
|  |                           |  |                           |                     |
|  |  +---------------------+  |  |  +---------------------+  |                     |
|  |  | chat-orchestrator   |  |  |  | conveyor-ruvector-  |  |                     |
|  |  | (1024Mi, 2 CPU)     |--+--+--| db (PostgreSQL 15)  |  |                     |
|  |  +---------------------+  |  |  +---------------------+  |                     |
|  |                           |  |                           |                     |
|  |  +---------------------+  |  +---------------------------+                     |
|  |  | chat-ui             |  |                                                    |
|  |  | (512Mi, 1 CPU)      |  |  +---------------------------+                     |
|  |  +---------------------+  |  |     Cloud Functions       |                     |
|  |                           |  |     (us-central1)         |                     |
|  |  +---------------------+  |  |                           |                     |
|  |  | mcp-server          |  |  |  +-------------------+    |                     |
|  |  | (512Mi, 1 CPU)      |--+--+--| case-manager      |    |                     |
|  |  +---------------------+  |  |  +-------------------+    |                     |
|  |                           |  |  +-------------------+    |                     |
|  +---------------------------+  |  | simulation-agent  |    |                     |
|                                 |  +-------------------+    |                     |
|  +---------------------------+  |  +-------------------+    |                     |
|  |     Secret Manager        |  |  | db-query-agent    |    |                     |
|  |                           |  |  +-------------------+    |                     |
|  |  gemini-api-key           |  |  +-------------------+    |                     |
|  |  anthropic-api-key        |  |  | airtable-agent    |    |                     |
|  |  oauth-client-secret      |  |  +-------------------+    |                     |
|  |  jwt-signing-key          |  +---------------------------+                     |
|  |  ruvector-db-password     |                                                    |
|  +---------------------------+                                                    |
|                                                                                    |
|  +---------------------------+  +---------------------------+                     |
|  |     Cloud Armor           |  |     Cloud Monitoring      |                     |
|  |     (WAF + DDoS)          |  |     (Metrics + Alerts)    |                     |
|  +---------------------------+  +---------------------------+                     |
|                                                                                    |
+-----------------------------------------------------------------------------------+

User Input
    |
    v
+------------------+
| Input Validation |  <-- Zod schema validation
+------------------+
    |
    v
+------------------+
| Rate Limiter     |  <-- Redis-backed rate limiting
+------------------+
    |
    v
+------------------+
| Auth Middleware  |  <-- JWT validation
+------------------+
    |
    v
+------------------+     +------------------+
| Command Parser   | OR  | Intent Classifier|
| (if /command)    |     | (Gemini 2.5 Pro) |
+------------------+     +------------------+
    |                           |
    +-------------+-------------+
                  |
                  v
         +------------------+
         | Context Manager  |  <-- Load conversation history
         +------------------+
                  |
                  v
         +------------------+
         | Function         |  <-- Route to Cloud Function
         | Dispatcher       |
         +------------------+
                  |
    +-------------+-------------+-------------+
    |             |             |             |
    v             v             v             v
+--------+  +-----------+  +----------+  +---------+
| case-  |  | simulation|  | db-query |  | airtable|
| manager|  | -agent    |  | -agent   |  | -agent  |
+--------+  +-----------+  +----------+  +---------+
    |             |             |             |
    +-------------+-------------+-------------+
                  |
                  v
         +------------------+
         | Response         |  <-- Format and enrich response
         | Generator        |
         +------------------+
                  |
                  v
         +------------------+
         | WebSocket        |  <-- Broadcast to subscribers
         | Broadcaster      |
         +------------------+
                  |
                  v
            User Response

/extensions-cloudrun/
+-- packages/
|   +-- shared-ui/              # IMPLEMENTED - Reusable HeroUI components
|   +-- shared-api/             # IMPLEMENTED - API clients, auth, logger
|   +-- shared-config/          # IMPLEMENTED - Vite base config, TailwindCSS
|   +-- shared-wasm/            # IMPLEMENTED - WASM utilities
+-- apps/
|   +-- sales-pipeline/         # IMPLEMENTED - Sales extension
|   +-- financial-ops/          # IMPLEMENTED - Financial extension
|   +-- hr-compensation/        # IMPLEMENTED - HR extension
|   +-- compliance-legal/       # IMPLEMENTED - Compliance extension
|   +-- customer-success/       # IMPLEMENTED - Customer success extension
|   +-- revenue-ops/            # IMPLEMENTED - Revenue ops extension
|   +-- chat-system/            # IMPLEMENTED - Chat web interface + backend
|       +-- src/
|       |   +-- components/     # ChatWindow, CommandInput, CommandPalette, SuggestionsPanel
|       |   +-- hooks/          # useChat, useChatHistory, useSelfLearning, useSuggestions
|       |   +-- workers/        # suggestions.worker.ts (Web Worker for background AI)
|       |   +-- services/       # GeminiService, CommandRouter
|       |   +-- config/         # systemPrompt, constants
|       +-- nginx.conf          # CSP headers, static serving
|       +-- Dockerfile          # Cloud Run deployment
+-- infrastructure/
    +-- gcp/
        +-- functions/          # IMPLEMENTED - 6 Cloud Functions
            +-- airtable-agent/
            +-- case-manager/
            +-- simulation-agent/
            +-- db-query-agent/
            +-- suggestion-agent/  # NEW - AI suggestions with Gemini 3 + Google Search
            +-- pandadoc-webhook/