Multi-Agent Conversational AI for Data-Driven Insights

Transform PSA's Global Insights dashboard data into actionable business intelligence through natural conversational interaction

🎯 Overview

Wharffle is an intelligent multi-agent chatbot platform designed to revolutionize how PSA's Global Insights dashboard data is accessed and interpreted. By combining advanced AI capabilities with a modular agent architecture, Wharffle automates complex port performance analysis and enables fast, informed decision-making aligned with PSA's global strategy.

The Problem

Port operators and managers spend significant time manually interpreting complex visual data from multiple dashboards. This process is time-consuming, error-prone, and delays critical operational decisions.

The Solution

Wharffle acts as an intelligent intermediary, translating complex visual data into clear, actionable business language. Users simply ask questions through a natural chat interface, and specialized AI agents collaborate behind the scenes to provide timely, accurate insights.

✨ Key Features

🤖 Multi-Agent Collaboration

• Specialized Agents: Each agent is an expert in specific data domains (vessel operations, metrics analysis, sustainability, business insights, scheduling)
• Dynamic Activation: Only relevant agents engage per query, optimizing speed and computational efficiency
• Smart Coordination: Agents work together seamlessly to provide comprehensive answers

💬 Conversational Interface

• Natural Language: Users interact using simple, conversational language—no technical knowledge required
• Context Awareness: The system maintains conversation context and understands follow-up questions
• Real-Time Response: Streaming responses keep users engaged with instant feedback

📊 Real-Time Data Interpretation

• Trend Analysis: Automatically identifies patterns and anomalies in operational metrics (berth times, arrival accuracy, carbon savings)
• Proactive Insights: Continuously analyzes data to generate key insights without waiting for manual requests

🎨 Interactive Insight Exploration

• Drag & Drop Integration: Users can drag insights directly from the dashboard into Wharffle
• Deep Dive Analysis: Trigger follow-up questions and deeper analysis on specific insights
• Contextual Inquiry: Personalize inquiries based on specific dashboard data

🏗️ Architecture

Tech Stack

Frontend:

• React 19+: Modern UI framework with latest hooks and features
• TypeScript: Type-safe development with excellent IDE support
• Vite: Lightning-fast build tool and development server
• Tailwind CSS: Utility-first CSS framework for responsive design
• Shadcn UI: Accessible component primitives

Communication:

• WebSocket: Real-time bidirectional communication with the backend
• Reconnecting WebSocket: Automatic reconnection with exponential backoff

Styling & UI:

• Shadcn UI: Modern User Interface Library
• Lucide React: Modern icon library
• Sonner: Toast notifications
• React Markdown: Rich text rendering with syntax highlighting (Shiki)
• Dark Mode Support: Next Themes integration

Build & Tooling:

• Bun: Fast JavaScript runtime and package manager
• ESLint: Code quality and consistency
• TypeScript Compiler: Strict type checking

🚀 Getting Started

Prerequisites

• Bun (v1.0+): Install Bun
• Node.js (v18+): For TypeScript compilation
• WebSocket Backend: Wharffle backend service running on ws://localhost:8080

Installation

1. Clone the repository

   git clone https://github.com/Spchdt/Wharffle.git
   cd Warffle

2. Install dependencies

   bun install

3. Set up environment variables (if needed) Create a .env.local file:

   VITE_WS_URL=ws://localhost:8080/ws

Development

Start the development server with hot module replacement:

bun run dev

The application will be available at http://localhost:5173

Building for Production

bun run build

This will:

1. Compile TypeScript code
2. Bundle with Vite
3. Generate optimized production assets in dist/

Preview Production Build

bun run preview

Linting

Check code quality:

bun run lint

🔌 WebSocket Communication

Message Types

Wharffle uses a structured WebSocket protocol for real-time communication:

Type 1: Chat Responses

{
  "type": 1,
  "data": {
    "status": 1,        // 1=agent selection, 2=generating, 3=complete
    "response": "...",  // AI-generated response
    "agentUsage": [2, 5] // IDs of agents used
  }
}

Type 2: Auto-Generated Insights

{
  "type": 2,
  "data": {
    "insights": [
      {
        "title": "Peak Load Alert",
        "content": "...",
        "agents": [1, 2]
      }
    ],
    "status": 0
  }
}

Type 3: Suggestion Cards

{
  "type": 3,
  "data": {
    "cards": [...],
    "status": 0
  }
}

Type 4: Error Handling

{
  "type": 4,
  "data": {
    "error": "Connection timeout",
    "code": "TIMEOUT"
  }
}

Connection Management

The client automatically handles:

• Connection establishment: Triggered on app load
• Reconnection: Exponential backoff (500ms → 8000ms) on disconnect
• Message parsing: Robust error handling for malformed messages
• Status tracking: Real-time connection state updates

🤖 Agent System

Agent Specialties

Wharffle deploys specialized agents for different operational domains:

Agent ID	Name	Specialty
1	Vessel Agent	Vessel operations and logistics
2	Metrics Agent	Performance metrics and analytics
3	Sustainability Agent	Carbon footprint and sustainability data
4	Business Agent	Business intelligence and strategy
5	Schedule Agent	Scheduling and planning

How It Works

1. User Query: User submits a question
2. Query Analysis: System determines which agents are needed
3. Agent Activation: Only relevant agents are activated
4. Collaborative Analysis: Agents analyze relevant data
5. Response Generation: Synthesized response combining agent insights
6. Delivery: Response streamed to user with agent usage information

Built with ❤️ by the Kopibara Team