BOSS Agent Chat Architecture

Document Version: 1.0.0 Last Updated: January 1, 2026 Status: 🔒 PROTECTED - Consult before ANY chat-related changes

⚠️ CRITICAL: READ BEFORE MAKING CHANGES

This document defines the production-critical architecture for the Boss Agent chat system. You MUST consult this document before making ANY changes to:

• Frontend chat components (BOSSChat.tsx, BOSSChatEnhanced.tsx)
• Chat hooks (useBOSS.ts, useOrchestration.ts, useNervousSystem.ts)
• API routes (app/api/boss/chat/route.ts)
• Boss Agent chat endpoints (boss_agent_adk_production.py)
• Type definitions (lib/api/types.ts, lib/api/boss.ts)

Failure to follow this architecture WILL break production chat functionality.

Table of Contents

1. Architecture Overview
2. Data Flow Diagram
3. Component Hierarchy
4. Hook Interfaces
5. API Endpoints
6. Type Definitions
7. Response Format Contract
8. Integration Points
9. Common Pitfalls
10. Change Checklist
11. Testing Protocol

1. Architecture Overview

The Boss Agent chat system uses a layered architecture with clear separation of concerns:

┌─────────────────────────────────────────────────────────────────┐
│                      PRESENTATION LAYER                          │
│  ┌─────────────────┐  ┌─────────────────────────────────────┐   │
│  │   BOSSChat.tsx  │  │      BOSSChatEnhanced.tsx           │   │
│  │  (Primary Chat) │  │  (Enhanced with Nervous System)     │   │
│  └────────┬────────┘  └──────────────────┬──────────────────┘   │
└───────────┼──────────────────────────────┼──────────────────────┘
            │                              │
┌───────────▼──────────────────────────────▼──────────────────────┐
│                         HOOKS LAYER                              │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                    useChat() - PRIMARY                   │    │
│  │  Returns: messages, isStreaming, sendMessage, etc.       │    │
│  └─────────────────────────────────────────────────────────┘    │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────┐   │
│  │ useChatMutation  │  │ useMOACollabor.  │  │useNervousSys │   │
│  │   (Legacy)       │  │  (MOA Debate)    │  │  (KG/SRPVDAL)  │   │
│  └──────────────────┘  └──────────────────┘  └──────────────┘   │
└─────────────────────────────┬───────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────────┐
│                      API ROUTE LAYER                             │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │           /api/boss/chat/route.ts                        │    │
│  │  - Receives: { message, conversationId, context }        │    │
│  │  - Forwards to: Boss Agent /process                      │    │
│  │  - Returns: { id, response, content, metadata, error }   │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────┬───────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────────┐
│                    BOSS AGENT (Cloud Run)                        │
│  URL: https://boss-agent-adk-698171499447.us-central1.run.app    │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                    /process endpoint                     │    │
│  │  - SRPVDAL Pipeline (Sense → Reason → Decide → Act → Learn)│    │
│  │  - MOE Routing / MOA Collaboration                       │    │
│  │  - Returns: ProcessResponse                              │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘

2. Data Flow Diagram

Request Flow (User → Backend)

User types message
        │
        ▼
┌───────────────────────────────────────┐
│ BOSSChat.tsx                          │
│ sendMessage(input, options)           │
└───────────────────┬───────────────────┘
                    │
                    ▼
┌───────────────────────────────────────┐
│ useChat() Hook (useBOSS.ts)           │
│                                       │
│ 1. Add user message to state          │
│ 2. Set isStreaming = true             │
│ 3. Create AbortController             │
│ 4. POST to /api/boss/chat             │
└───────────────────┬───────────────────┘
                    │
                    ▼
┌───────────────────────────────────────┐
│ /api/boss/chat/route.ts               │
│                                       │
│ 1. Parse request body                 │
│ 2. Extract message from various keys  │
│ 3. Forward to Boss Agent /process     │
│ 4. Normalize response format          │
└───────────────────┬───────────────────┘
                    │
                    ▼
┌───────────────────────────────────────┐
│ Boss Agent ADK /process                │
│                                       │
│ 1. SRPVDAL Pipeline execution           │
│ 2. Claude Opus 4.6 processing         │
│ 3. Cell orchestration                 │
│ 4. Return ProcessResponse             │
└───────────────────────────────────────┘

Response Flow (Backend → User)

Boss Agent returns ProcessResponse
        │
        ▼
┌───────────────────────────────────────┐
│ /api/boss/chat/route.ts               │
│                                       │
│ Normalize to:                         │
│ {                                     │
│   id: data.message_id || Date.now(),  │
│   response: data.content || data...   │
│   content: data.content,              │
│   metadata: data.metadata,            │
│   error: false                        │
│ }                                     │
└───────────────────┬───────────────────┘
                    │
                    ▼
┌───────────────────────────────────────┐
│ useChat() Hook                        │
│                                       │
│ Extract content:                      │
│ data.response ||                      │
│ data.content ||                       │
│ data.message?.content ||              │
│ 'No response received'                │
│                                       │
│ Add assistant message to state        │
│ Set isStreaming = false               │
└───────────────────┬───────────────────┘
                    │
                    ▼
┌───────────────────────────────────────┐
│ BOSSChat.tsx                          │
│                                       │
│ Render messages array                 │
│ Show response to user                 │
└───────────────────────────────────────┘

3. Component Hierarchy

Primary Chat Components

components/chat/
├── BOSSChat.tsx              # PRIMARY - Full-featured chat
│   ├── Uses: useChat()       # Comprehensive state management
│   ├── Uses: useAgents()     # Agent list
│   ├── Uses: useCellRegistry() # Cell registry
│   ├── Uses: useNervousSystem() # KG/SRPVDAL context
│   └── Features:
│       ├── Orchestration mode selector
│       ├── MOA debate visualizer
│       ├── Nervous system panel
│       ├── Pending approvals view
│       └── Streaming response display
│
├── BOSSChatEnhanced.tsx      # ALTERNATIVE - Different UX
│   ├── Uses: useChatMutation() # Simple mutation
│   ├── Uses: useMOACollaboration() # MOA streaming
│   ├── Uses: useCellRegistry() # Cell registry
│   └── Uses: useNervousSystemActivity() # Activity monitor
│
├── OrchestrationModeSelector.tsx  # Mode tabs (Auto/MOE/MOA/Direct)
└── MOADebateVisualizer.tsx        # Debate rounds visualization

Supporting Components

components/
├── NervousSystemPanel        # Embedded in BOSSChat
│   ├── KG Context (WHAT)
│   ├── SRPVDAL Procedures (HOW)
│   ├── Causal Analysis (WHY)
│   └── Active Cells
│
├── MessageBubble             # Chat message display
├── StreamingResponse         # Typing indicator + partial response
└── PendingApprovalsView      # Action approval UI

4. Hook Interfaces

useChat() - PRIMARY HOOK

Location: hooks/api/useBOSS.ts

Purpose: Comprehensive chat state management for BOSSChat.tsx

interface UseChatOptions {
  onAgentStart?: (agentId: string, agentName: string, cellId: string) => void;
  onCellInvoked?: (cellId: string, endpoint: string) => void;
  onMOAContribution?: (contribution: AgentContribution) => void;
  onApprovalRequired?: (approval: ApprovalRequest) => void;
}

interface UseChatReturn {
  // Chat state
  messages: ChatMessage[];           // Full message history
  currentResponse: string;           // Streaming response text
  isStreaming: boolean;              // Is currently processing
  activeAgent: string | null;        // Currently active agent name
  activeCells: string[];             // Cells being used
  error: { message: string } | null; // Error state

  // MOA collaboration
  moaContributions: AgentContribution[];
  currentMOARound: number;

  // Approvals
  pendingApprovals: ApprovalRequest[];

  // Actions
  sendMessage: (content: string, options?: ChatOptions) => Promise<void>;
  stopStreaming: () => void;
  clearMessages: () => void;
  approveAction: (approvalId: string) => Promise<void>;
  rejectAction: (approvalId: string, reason?: string) => Promise<void>;

  // Metadata
  conversationId: string;
}

CRITICAL: This hook calls /api/boss/chat (Next.js route), NOT the Boss Agent directly.

useChatMutation() - LEGACY HOOK

Location: hooks/api/useBOSS.ts

Purpose: Simple mutation for BOSSChatEnhanced.tsx

// Returns TanStack Query mutation
const mutation = useChatMutation();

// Usage:
const result = await mutation.mutateAsync({
  message: string,
  conversationId?: string,
  options?: ChatOptions
});

// Result is ProcessResponse type

CRITICAL: Calls bossApi.chat.chat() which hits /api/v1/chat on Boss Agent.

useNervousSystem() - CONTEXT HOOK

Location: hooks/api/useNervousSystem.ts

interface UseNervousSystemReturn {
  kgContext: KGContext | null;
  srpvdalProcedure: SRPVDALProcedure | null;
  srpvdalRouting: SRPVDALRoutingDecision | null;
  causalAnalysis: RootCauseAnalysis | null;
  consultation: NervousSystemConsultation | null;

  isLoadingKG: boolean;
  isLoadingSRPVDAL: boolean;
  isLoadingCausal: boolean;
  isLoadingConsultation: boolean;

  queryKG: (query: string) => Promise<KGContext>;
  queryProcedure: (task: string) => Promise<SRPVDALProcedure | null>;
  queryRouting: (query: string) => Promise<SRPVDALRoutingDecision>;
  analyzeRootCause: (symptom: string) => Promise<RootCauseAnalysis>;
  consult: (query: string) => Promise<NervousSystemConsultation>;
}

useCellRegistry() - REGISTRY HOOK

Location: hooks/api/useBOSS.ts

// Returns:
{
  data: {
    cells: AgentInfo[];        // Array of cells
    agents: AgentInfo[];       // Array of agents
    orchestrators: AgentInfo[]; // Array of orchestrators
    lastDiscovery: string;     // Timestamp
  } | undefined;
  isLoading: boolean;
  error: Error | null;
}

⚠️ COMMON PITFALL: cellRegistry is an OBJECT, not an array. Access cells via cellRegistry?.cells?.map().

5. API Endpoints

Frontend Routes (Next.js)

Boss Agent Endpoints

API Client Structure (lib/api/boss.ts)

bossApi = {
  health: {
    getHealth(): Promise<HealthResponse>;
    getStatus(): Promise<StatusResponse>;
    getMetrics(): Promise<Record<string, unknown>>;
  },
  chat: {
    process(request: ChatRequest): Promise<ProcessResponse>;
    chat(request: ChatRequest): Promise<ProcessResponse>;
    coordinateTasks(tasks: Task[]): Promise<CoordinationResponse>;
  },
  agents: {
    list(): Promise<AgentInfo[]>;
    get(id: string): Promise<AgentInfo>;
    execute(id: string, task: string): Promise<ExecutionResult>;
    getRegistry(): Promise<Registry>;
  },
  sessions: { /* ... */ },
  conversations: { /* ... */ },
  kg: { /* ... */ },
  // ... more namespaces
}

6. Type Definitions

ChatRequest (Frontend → Backend)

// lib/api/boss.ts
interface ChatRequest {
  message: string;
  conversationId?: string;
  options?: ChatOptions;
}

// lib/api/types.ts (more complete)
interface ChatRequest {
  message: string;
  conversationId?: string;
  userId?: string;
  context?: Record<string, unknown>;
  options?: ChatOptions;
}

ChatOptions

interface ChatOptions {
  // Streaming
  stream?: boolean;
  maxTokens?: number;
  temperature?: number;

  // Orchestration
  orchestration?: 'auto' | 'moe' | 'moa' | 'direct';

  // MOE
  forceExperts?: string[];
  excludeExperts?: string[];
  explainRouting?: boolean;

  // MOA
  moaAgents?: string[];
  moaMode?: 'debate' | 'consensus' | 'pipeline' | 'parallel';
  streamDebate?: boolean;

  // Direct
  targetAgent?: string;

  // Nervous System
  consultNervousSystem?: boolean;
}

ProcessResponse (Backend → Frontend)

// lib/api/boss.ts
interface ProcessResponse {
  conversationId: string;
  message: ChatMessage;
  srpvdalCycle?: {
    sense: Record<string, unknown>;
    reason: Record<string, unknown>;
    decide: Record<string, unknown>;
    act: Record<string, unknown>;
    learn: Record<string, unknown>;
    cycleTime: number;
  };
  cellsUsed: string[];
  routingExplanation?: string;
  actionResults?: Record<string, unknown>[];
  pendingActions?: PendingAction[];
}

ChatMessage

interface ChatMessage {
  id: string;
  role: 'user' | 'assistant' | 'system' | 'agent';
  content: string;
  timestamp: string;
  metadata?: {
    agentId?: string;
    agentsInvoked?: string[];
    taskId?: string;
    confidence?: number;
    citations?: Citation[];
    toolCalls?: ToolCall[];
  };
}

7. Response Format Contract

Next.js Route Response (/api/boss/chat)

The route MUST return this format:

{
  id: string;           // Message ID
  response: string;     // Primary response content
  content?: string;     // Alternative content field
  metadata?: object;    // Additional metadata
  error: boolean;       // Error flag
}

useChat() Extraction Logic

The hook extracts content in this order:

const responseContent =
  data.response ||           // First: response field
  data.content ||            // Second: content field
  data.message?.content ||   // Third: nested message.content
  (typeof data.message === 'string' ? data.message : 'No response received');

⚠️ CRITICAL: If you change the response format, you MUST update this extraction logic.

useChatMutation() Extraction Logic

For BOSSChatEnhanced.tsx:

// ProcessResponse structure
response = chatResult.message?.content || 'No response received.';
metadata.routedTo = chatResult.routingExplanation;
metadata.confidence = chatResult.message?.confidence;

8. Integration Points

Hook Exports (hooks/api/index.ts)

// REQUIRED exports for chat functionality
export {
  useChat,           // Primary chat hook
  useChatMutation,   // Legacy mutation hook
  useProcess,        // Direct process mutation
  useAgents,         // Agent list
  useCellRegistry,   // Cell registry
  // ... other exports
} from './useBOSS';

export { useNervousSystem } from './useNervousSystem';

export {
  useMOACollaboration,
  useMOACollaborationMutation,
  // ... other exports
} from './useOrchestration';

Component Imports

// BOSSChat.tsx
import { useChat, useAgents, useCellRegistry, useNervousSystem } from '@/hooks/api';

// BOSSChatEnhanced.tsx
import { useChatMutation, useCellRegistry } from '@/hooks/api';
import { useMOACollaboration } from '@/hooks/api/useOrchestration';
import { useNervousSystem, useNervousSystemActivity } from '@/hooks/api/useNervousSystem';

9. Common Pitfalls

❌ WRONG: Accessing cellRegistry as array

// WRONG - cellRegistry is an object
cellRegistry?.map((cell) => ...)

// CORRECT
cellRegistry?.cells?.map((cell) => ...)

❌ WRONG: Using wrong ChatRequest property

// WRONG - 'context' is for general data
chat.mutateAsync({ message: "hi", context: { mode: "moe" } })

// CORRECT - 'options' is for chat options
chat.mutateAsync({ message: "hi", options: { orchestration: "moe" } })

❌ WRONG: Accessing non-existent response properties

// WRONG - ProcessResponse doesn't have these at top level
chatResult.response
chatResult.routed_to
chatResult.confidence

// CORRECT
chatResult.message?.content
chatResult.routingExplanation
chatResult.message?.confidence

❌ WRONG: Using wrong useNervousSystem properties

// WRONG - These property names don't exist
const { context, procedures, isLoading } = useNervousSystem();

// CORRECT
const {
  kgContext,
  srpvdalProcedure,
  isLoadingKG,
  isLoadingSRPVDAL
} = useNervousSystem();

❌ WRONG: Expecting array from srpvdalProcedure

// WRONG - srpvdalProcedure is a single object
procedures.map((proc) => ...)

// CORRECT - Wrap in array if needed
(srpvdalProcedure ? [srpvdalProcedure] : []).map((proc) => ...)

❌ WRONG: Missing task in MOACollaborationRequest

// WRONG - task is required
moaCollaboration.startCollaboration({ query: "..." })

// CORRECT
moaCollaboration.startCollaboration({
  query: "...",
  task: "...",  // Required!
  mode: "debate"
})

10. Change Checklist

Before making ANY changes to chat functionality, verify:

Pre-Change Verification

• [ ] Read this architecture document completely
• [ ] Understand the current data flow
• [ ] Identify all affected files
• [ ] Check type definitions in lib/api/types.ts and lib/api/boss.ts

During Development

• [ ] Maintain backward compatibility with existing response formats
• [ ] Update ALL components using changed hooks
• [ ] Update ALL hooks using changed API methods
• [ ] Keep type definitions in sync across files
• [ ] Add proper error handling

Pre-Commit Verification

• [ ] Run npm run lint - no new errors
• [ ] Run npx tsc --noEmit - check for type errors in chat files
• [ ] Test BOSSChat.tsx manually
• [ ] Test BOSSChatEnhanced.tsx manually
• [ ] Verify streaming works
• [ ] Verify error handling works
• [ ] Verify MOA collaboration works (if applicable)

Files to Check After Changes

11. Testing Protocol

Manual Testing Checklist

## BOSSChat.tsx Tests

1. [ ] Send a simple message → Receive response
2. [ ] Send message in MOE mode → Expert routing works
3. [ ] Send message in MOA mode → Debate visualization shows
4. [ ] Send message in Direct mode → Routes to selected agent
5. [ ] Click Stop while streaming → Cancels request
6. [ ] Click Clear → Clears all messages
7. [ ] Nervous System panel → Shows KG context
8. [ ] Error handling → Shows error message in chat

## BOSSChatEnhanced.tsx Tests

1. [ ] Send a simple message → Receive response
2. [ ] MOA collaboration → Debate panel shows
3. [ ] Direct cell selection → Cell dropdown works
4. [ ] Settings panel → Opens and closes
5. [ ] Mode switching → Tabs work correctly

## Edge Cases

1. [ ] Empty message → Should not send
2. [ ] Network error → Shows error gracefully
3. [ ] Timeout → Shows timeout message
4. [ ] Rapid messages → Handles correctly
5. [ ] Long response → Renders properly

Automated Tests (Future)

// tests/chat/useChat.test.ts
describe('useChat hook', () => {
  it('should add user message to messages array');
  it('should set isStreaming true when sending');
  it('should extract response from various formats');
  it('should handle errors gracefully');
  it('should support abort controller cancellation');
});

// tests/chat/BOSSChat.test.tsx
describe('BOSSChat component', () => {
  it('should render message input');
  it('should display messages');
  it('should show streaming indicator');
  it('should show nervous system panel');
});

Version History

Maintainers

• Architecture Owner: Development Team
• Last Review: January 1, 2026

Quick Reference Card

┌────────────────────────────────────────────────────────────────┐
│                    BOSS CHAT QUICK REFERENCE                   │
├────────────────────────────────────────────────────────────────┤
│                                                                │
│  PRIMARY HOOK: useChat() from '@/hooks/api'                    │
│  LEGACY HOOK:  useChatMutation() from '@/hooks/api'            │
│                                                                │
│  FRONTEND ROUTE: /api/boss/chat → Boss Agent /process          │
│                                                                │
│  RESPONSE FORMAT:                                              │
│    Route returns: { id, response, content, metadata, error }   │
│    Hook extracts: data.response || data.content || ...         │
│                                                                │
│  COMMON MISTAKES:                                              │
│    ✗ cellRegistry?.map()     → ✓ cellRegistry?.cells?.map()   │
│    ✗ context: { mode }       → ✓ options: { orchestration }   │
│    ✗ chatResult.response     → ✓ chatResult.message?.content  │
│    ✗ { context, procedures } → ✓ { kgContext, srpvdalProcedure }│
│                                                                │
│  BEFORE ANY CHANGE: Read BOSS_AGENT_CHAT_ARCHITECTURE.md       │
│                                                                │
└────────────────────────────────────────────────────────────────┘