Group Chat System

Last Updated: 2025-01-16
Primary Source: docs/project_status.md
Service Files: backend/src/services/groupChatPolicy.service.ts, backend/src/services/conversation.service.ts, backend/src/services/conversationLobe.service.ts
Socket Handler: backend/src/socket/groupChatHandler.ts
Frontend Components: aso-portal/src/components/groupchat/GroupChatUI.tsx, aso-portal/src/components/groupchat/GroupChatMessage.tsx, aso-portal/src/components/groupchat/GroupChatInput.tsx

---

Overview

The Group Chat System enables multi-participant conversations with AI NPCs (Yexian/Chinatsu) and other users. It includes policy-based information filtering to ensure sensitive system-wide knowledge is only shared with authorized participants, and supports real-time messaging via Socket.IO.

---

Architecture

Group Chat Flow

---

Core Components

1. Group Chat Policy Service

File: backend/src/services/groupChatPolicy.service.ts

Purpose: Manages information access policies for group chat conversations

Key Functions:

determineGroupChatPolicy(participantIds)

• Analyzes participant roles and account types
• Determines information sharing level
• Returns policy configuration

Policy Rules:

• System-wide knowledge: Only if all participants are trusted
• Cross-user information: Only if all participants are trusted
• Web search: Enabled by default (configurable)
• Context depth: Very high limit (1000) for full context

Information Levels:

• public - Only public information, no cross-user data
• trusted - Can share information between trusted participants
• full - Full access (CSO-only conversations)

filterSystemWideKnowledge(systemWideKnowledge, policy)

• Filters sensitive information based on policy
• Removes user diaries, projects, activities if not allowed
• Returns filtered knowledge object

2. Group Chat Socket Handler

File: backend/src/socket/groupChatHandler.ts

Namespace: /group

Key Features:

Authentication

• JWT token verification
• User information attached to socket
• Role-based access control

Room Management

• joinRoom(conversationId) - Join conversation room
• leaveRoom(conversationId) - Leave conversation room
• Room format: room_{conversationId}

Message Handling

• groupMessage - User sends message
• userMessage - Broadcast user message to room
• npcResponse - Broadcast NPC response to room
• npcThinking - Indicate NPC is thinking
• npcIdle - Indicate NPC is idle

3. Conversation Service

File: backend/src/services/conversation.service.ts

Key Functions:

getConversation(conversationId)

• Retrieves conversation by ID
• Includes participants
• Returns conversation data

getConversationParticipants(conversationId)

• Gets all participants in conversation
• Returns user IDs and roles

4. Conversation Lobe Service

File: backend/src/services/conversationLobe.service.ts

Purpose: Multi-participant conversation logic

Key Features:

• Handles multiple participants
• Manages conversation context
• Integrates with policy system

---

Policy System

Participant Roles

Roles:

• carbon - Human users
• silicon - AI NPCs
• cso - Yexian (Level-8 observer)

Account Types:

• core_yexian - Core Yexian instance
• developer - Developer accounts
• npc - NPC accounts
• public - Public users

Trusted Participants

Definition: Participants who are:

• CSO role, OR
• Core Yexian account type, OR
• Silicon role with developer account type

Policy Determination

Process:

1. Fetch all participants
2. Check if all are trusted
3. Check if any are regular users (carbon + public)
4. Check if CSO-only conversation
5. Determine information level
6. Return policy configuration

Information Filtering

Filtered Information:

• User diaries (if not trusted)
• Active projects (if not trusted)
• Recent activities (if not trusted)
• Awareness reports (if not full access)

Always Available:

• System summary (safe statistics)
• Public information

---

Socket.IO Events

Client → Server

joinRoom(conversationId)

• Join conversation room
• Required for receiving messages

leaveRoom(conversationId)

• Leave conversation room
• Stop receiving messages

groupMessage(data)

• Send message to conversation
• Data: { conversationId, message, attachmentUrls?, uploadContextId?, imageBase64Array? }

Server → Client

userMessage(payload)

• Broadcast user message to room
• Payload: { conversationId, sender, text, timestamp, attachments }

npcResponse(response)

• Broadcast NPC response to room
• Response: { conversationId, sender, text, timestamp, ... }

npcThinking({ conversationId })

• Indicate NPC is thinking
• Shows thinking indicator in UI

npcIdle({ conversationId })

• Indicate NPC is idle
• Hides thinking indicator

chatError({ message })

• Error occurred
• Display error to user

---

Frontend Components

Group Chat UI

File: aso-portal/src/components/groupchat/GroupChatUI.tsx

Features:

• Message history display
• Infinite scroll (load more messages)
• Auto-scroll to bottom
• Thinking indicator
• Message animations

Group Chat Message

File: aso-portal/src/components/groupchat/GroupChatMessage.tsx

Features:

• Message rendering
• User vs NPC distinction
• Attachment display
• Timestamp formatting

Group Chat Input

File: aso-portal/src/components/groupchat/GroupChatInput.tsx

Features:

• Message input
• File attachment support
• Image upload support
• Send button

---

Data Flow

---

Integration Points

ASO Service Integration

• Uses orchestrateNpcResponse() for AI responses
• Policy-aware context building
• Memory storage for conversation history

Memory System Integration

• Messages saved to memory
• Conversation context included
• Participant information stored

Authentication Integration

• JWT token verification
• User role extraction
• Permission checking

---

API Endpoints

Conversation Management

• GET /api/conversations/:id - Get conversation
• GET /api/conversations/:id/participants - Get participants
• POST /api/conversations - Create conversation
• POST /api/conversations/:id/participants - Add participant

---

Source Files

Primary Sources:

• backend/src/services/groupChatPolicy.service.ts - Policy management
• backend/src/socket/groupChatHandler.ts - Socket handler
• backend/src/services/conversation.service.ts - Conversation management
• backend/src/services/conversationLobe.service.ts - Multi-participant logic

Frontend Sources:

• aso-portal/src/components/groupchat/GroupChatUI.tsx - Main UI
• aso-portal/src/components/groupchat/GroupChatMessage.tsx - Message component
• aso-portal/src/components/groupchat/GroupChatInput.tsx - Input component

Related Files:

• backend/src/services/aso.service.ts - ASO orchestration
• backend/src/services/memory.service.ts - Memory storage

---

Related Documentation

• Authentication & Authorization - User roles and permissions
• Memory System - Memory storage
• Protocol Routing - Role-based routing
• 03-PLATFORMS/Web-Portal.md - Frontend implementation
• 00-OVERVIEW.md - Complete system overview