Anna - AI Agent Platform Frontend

Modern Next.js 16 frontend for Anna, an AI agent platform with voice diarization capabilities.

Tech Stack

• Framework: Next.js 16 (App Router) with Turbopack
• Language: TypeScript (strict mode)
• Styling: Tailwind CSS with custom Dark/Red theme
• UI Components: shadcn/ui (Radix UI primitives)
• State Management:
  • TanStack Query v5 (server state)
  • Zustand v5 (client state)
• Forms: React Hook Form + Zod validation
• API Client: Axios for REST, native WebSocket for streaming

Getting Started

Prerequisites

• Node.js 20.9.0+ (Next.js 16 requirement)
• npm 9+
• Backend API Server - This frontend requires the speaker diarization backend API to be running. Get it from: https://github.com/snailbrainx/mcp-speaker-diarization

Installation

# Install dependencies
npm install

# Copy and configure environment variables
cp .env.example .env.local

# IMPORTANT: Edit .env.local and set your server IP
# Example: NEXT_PUBLIC_API_URL=http://10.0.23.5:8000
nano .env.local

# Start development server
npm run dev

The app will be available at:

• Local access: http://localhost:3000
• Network access: http://YOUR_SERVER_IP:3000 (e.g., http://10.0.23.5:3000)

Backend Connection

IMPORTANT: Update .env.local with your server's IP address:

# Use your actual server IP, not localhost!
NEXT_PUBLIC_API_URL=http://10.0.23.5:8000

Make sure the backend is running:

cd ../
./run_local.sh  # or docker-compose up

Backend should be accessible at http://YOUR_SERVER_IP:8000

MCP Server Connection

The backend includes a built-in Model Context Protocol (MCP) server at /mcp endpoint for AI agent integration:

Endpoint: http://YOUR_SERVER_IP:8000/mcp Transport: HTTP with Server-Sent Events (SSE) Protocol: JSON-RPC 2.0 (MCP 2024-11-05)

Available MCP Tools:

• get_latest_segments - Get recent conversation segments
• identify_speaker_in_segment - Identify or correct speaker in segment
• list_speakers - Get all enrolled speakers
• get_conversation - Get full conversation with transcript
• list_conversations - Get conversations with pagination
• rename_speaker - Rename speaker (updates all past segments)
• delete_speaker - Delete speaker profile
• delete_all_unknown_speakers - Cleanup all Unknown_* speakers
• reprocess_conversation - Re-analyze with current speakers
• update_conversation_title - Update conversation title
• search_conversations_by_speaker - Search by speaker name

Use with AI Agents:

• Connect from Flowise, Claude Desktop, or custom MCP clients
• Enables AI agents to identify speakers, query conversation history, and manage speaker profiles
• See main repository README for detailed MCP integration examples

Example Connection (Flowise/MCP client):

{
  "url": "http://10.0.23.5:8000/mcp",
  "transport": "http"
}

For more details, see the MCP server repository: https://github.com/snailbrainx/mcp-speaker-diarization

Project Structure

anna-frontend/
├── app/                    # Next.js App Router pages
│   ├── voice/             # Voice module
│   │   ├── speakers/      # Speaker management
│   │   ├── conversations/ # Conversation browsing
│   │   ├── process/       # Audio upload & processing
│   │   ├── settings/      # Voice settings
│   │   └── live/          # Live recording (WIP)
│   ├── agents/            # AI agents (future)
│   ├── tools/             # Tool management (future)
│   └── smart-home/        # Smart home (future)
│
├── components/            # React components
│   ├── layout/           # Layout components
│   ├── voice/            # Voice-specific components
│   └── ui/               # shadcn/ui components
│
├── lib/                   # Core utilities
│   ├── api/              # API client & endpoints
│   ├── hooks/            # React Query hooks
│   ├── stores/           # Zustand stores
│   ├── types/            # TypeScript types
│   └── utils/            # Utility functions
│
└── styles/               # Global styles & themes

Screenshots

Live Recording Real-time transcription with audio visualization	Speaker Management Enroll and manage speakers	Conversations List Browse past conversations
Conversation Detail Transcript view with multi-speaker segments	Process Audio Audio file upload interface	Voice Settings Profile management and configuration

Features

Voice Module (Complete)

• ✅ Live Recording: Real-time WebSocket streaming with VAD, live transcription, and word-level confidence
• ✅ Speaker Management: Enroll speakers (upload or record), rename, delete, with voice embedding storage
• ✅ Conversations: Browse past conversations with pagination, playback segments, view full transcripts
• ✅ Speaker Identification: Identify unknown speakers, auto-enroll new speakers, retroactive updates
• ✅ Audio Processing: Upload and process audio files with diarization and transcription
• ✅ Settings Management: Runtime configuration for thresholds, padding, silence detection, hallucination filtering
• ✅ Voice Profiles: Backup/restore speaker profiles, checkpoints, import/export as JSON
• ✅ Segment Audio: Playback any conversation segment with colored word-level confidence visualization

Future Modules

• 🔜 AI Agents: Agent orchestration and management
• 🔜 Tools: MCP server integration and tool management
• 🔜 Smart Home: Home automation integration

API Integration

All API calls go through the centralized API client in lib/api/:

// Example: Using React Query hooks
import { useSpeakers } from '@/lib/hooks/voice/useSpeakers';

function MyComponent() {
  const { data: speakers, isLoading } = useSpeakers();
  // ...
}

Theme

Anna uses a custom Dark/Red theme with compact spacing:

• Primary: Bright Red (#DC2626)
• Background: Deep Dark (#141414)
• Accent: Light Red (#F87171)
• Typography: Inter (body), JetBrains Mono (code)

Development

# Development server with Turbopack
npm run dev

# Type checking
npm run type-check

# Linting
npm run lint

# Production build
npm run build

# Start production server
npm start

Module System

Anna is designed with a modular architecture:

interface AppModule {
  id: string;
  name: string;
  icon: LucideIcon;
  enabled: boolean;
  routes: string[];
}

New modules can be added by:

1. Creating routes in app/{module-name}/
2. Adding components in components/{module-name}/
3. Updating sidebar in components/layout/Sidebar.tsx

Contributing

This is the beginning of Anna - a scalable AI agent platform. The voice module demonstrates the architecture that will be extended for agent management, tool integration, and smart home control.

License

ISC