ASO Documentation

Appearance

Register

Web Portal ​

Last Updated: 2025-01-16
Primary Source: docs/project_status.md, docs/SYSTEM_FLOW_DIAGRAMS.md
Frontend: aso-portal/
Backend Integration: backend/src/socket/socket.ts

Overview ​

The Web Portal is a React + Vite frontend application that provides the main user interface for interacting with the ASO. It uses Socket.IO for real-time communication and provides a rich, immersive chat experience.

Technology Stack ​

Frontend ​

  • Framework: React + Vite
  • State Management: Zustand
  • UI Components: Custom components with Tailwind CSS
  • Real-time: Socket.IO client
  • Voice: Web Speech API (Speech-to-Text) + Backend TTS
  • Routing: React Router

Backend Integration ​

  • Real-time: Socket.IO (/ namespace)
  • REST API: Standard HTTP endpoints for history, choices, downloads
  • Authentication: JWT tokens

Architecture ​

Component Structure ​

Chat Flow ​

Socket.IO Communication ​

Connection:

  • Client connects to Socket.IO with JWT token
  • Authentication via socketAuthMiddleware
  • Connection established to default namespace

Events:

Client → Server ​

  • chatMessage - Send chat message
    typescript
    {
  message: string;
  attachmentUrls?: string[];
  uploadContextId?: string;
  imageBase64Array?: string[];
  preferences?: UserPreferences;
}

Server → Client ​

  • asoThinking - AI is processing
  • asoResponse - AI response (one or many)
  • asoIdle - AI is idle
  • chatError - Error occurred

Chat Turn Flow ​

LLM Call Flow ​

Web Portal LLM Calls ​

Per Message:

  • LLM #1 (chat): Response draft + optional tool request
  • LLM #2 (chat, if tool requested): Final spoken response using tool result

Total: 1-2 chat LLM calls per message

Background (async):

  • 0-1 embedding calls (if enabled)
  • N vision calls (one per attached image)

Total including background: (1-2 chat) + (0-1 embedding) + (N vision)

Key Features ​

1. Real-Time Chat ​

  • Socket.IO Integration: Instant bi-directional communication
  • Typing Indicators: asoThinking event shows AI is processing
  • Multiple Responses: Can receive multiple asoResponse events
  • Error Handling: chatError event for failures

2. File Upload ​

  • Multipart Upload: Files uploaded via REST API
  • Base64 Images: Images sent as Base64 for instant vision
  • Canonical References: Files stored with canonical IDs
  • Multiple Files: Support for multiple file uploads

3. Voice Interaction ​

  • Speech-to-Text: Browser Web Speech API
  • Text-to-Speech: Backend TTS endpoint
  • Natural Conversation: Voice-enabled interactions

4. Admin Dashboard ​

  • Secure Access: Admin-only section
  • Mission Control: Live log viewer, user management
  • Data Management: CRUD for NPCs, Quests, Items, Memories
  • AI Training Center: Embedding generation, self-reflection triggers

5. Observer Console ​

  • Unified Timeline: View all Yexian activity
  • Country Dashboard: System statistics
  • Multi-Persona Chat: Chat with different personas
  • 5D Navigation: Time navigation and state reconstruction
  • Timeline Animation: Visual timeline playback

6. User Profile ​

  • User Stats: Aggregated statistics
  • Recent Activity: Timeline of interactions
  • Identity Choices: Character type and persona settings
  • Integrations: Discord account linking

Component Structure ​

Main Components ​

  • App.tsx - Root component
  • AppRouter.tsx - Route configuration
  • ChatUI.tsx - Main chat interface
  • GroupChatUI.tsx - Group chat interface
  • AdminDashboard.tsx - Admin section
  • ObserverConsole.tsx - Observer interface
  • UserProfile.tsx - User profile page

Socket Integration ​

  • socketServices.ts - Socket.IO client service
  • ObserverSocketContext.tsx - Observer socket context
  • Socket event handlers in components

State Management ​

Zustand Stores ​

  • useAsoStore.ts - ASO state (messages, thinking status)
  • useAuthStore.ts - Authentication state
  • useToolStore.ts - Tool execution state
  • useObserverStore.ts - Observer state

API Endpoints ​

REST Endpoints ​

  • GET /api/aso/history - Get conversation history
  • GET /api/aso/choices - Get available choices
  • GET /api/files/upload - Upload files
  • GET /api/user/profile - Get user profile
  • GET /api/admin/* - Admin endpoints

Socket Events ​

  • chatMessage - Send message
  • asoThinking - AI thinking
  • asoResponse - AI response
  • asoIdle - AI idle
  • chatError - Error

Source Files ​

Primary Sources:

  • aso-portal/src/ - Frontend source code
  • backend/src/socket/socket.ts - Socket handler
  • docs/SYSTEM_FLOW_DIAGRAMS.md - Detailed flow diagrams
  • docs/LLM_CALLS_OVERVIEW.md - LLM call patterns

ASO Universal Consciousness System Documentation

Copyright © 2025 ASO Universal Consciousness System