🤖 Universal AI Chat Framework (UCAF)

Domain-agnostic AI chat framework with tagged customization zones, generative UI, and MCP integration

A production-ready, enterprise-grade AI chat framework built with AI SDK 5.0, Next.js 15, and React 19. Designed for rapid deployment across different domains (medical, maritime, financial, enterprise) with comprehensive customization through tagged zones.

✨ Key Features

🎯 Core Framework

• AI SDK 5.0 Integration - Latest Vercel AI SDK with streaming, tool calling, and generative UI
• Next.js 15 + React 19 - Modern React Server Components with Turbopack
• Domain-Agnostic Architecture - Tagged customization zones for easy adaptation
• TypeScript First - Comprehensive type safety throughout the framework

🎨 Generative UI System

• Dynamic Component Generation - AI generates React components beyond text responses
• Tool-Based UI Creation - Tools return data that renders as interactive components
• Domain-Specific Components - Medical charts, maritime trackers, financial summaries
• Real-Time Streaming - Live UI updates during AI interactions

🔌 Model Context Protocol (MCP)

• Standardized Integrations - MCP servers for filesystem, databases, search, and more
• Dynamic Tool Discovery - Automatically discover and register tools from MCP servers
• Multi-Server Support - Connect to multiple MCP servers simultaneously
• Protocol Compliance - Full MCP specification implementation

🏥 Domain Specializations

• Medical - HIPAA-compliant healthcare AI with medical terminology optimization
• Maritime - Vessel tracking, logistics, and shipping schedule management
• Financial - Secure financial analysis with compliance and audit trails
• Enterprise - General business tools with multi-tenant organization support

🎙️ Advanced Interactions

• Voice Input - Web Speech API with domain-specific terminology
• AI Reasoning Display - Show AI thinking process with compliance options
• Multi-Modal Support - Text, voice, and file upload capabilities
• Real-Time Streaming - Live response generation with tool execution

🔒 Enterprise Features

• Multi-Tenant Architecture - Organization-based isolation and access control
• Audit Trails - Comprehensive logging for compliance requirements
• Security First - HIPAA, SOC2, and other compliance frameworks
• Cost Optimization - Intelligent AI provider routing and usage tracking

🏷️ Domain Tag System

The framework uses tagged zones for easy customization. Search for these tags in the codebase:

| Tag | Description | Use Case | |-----|-------------|----------| | @MEDICAL-DOMAIN | Healthcare customizations | HIPAA compliance, medical terminology | | @MARITIME-DOMAIN | Shipping & logistics | Vessel tracking, maritime operations | | @FINANCIAL-DOMAIN | Finance customizations | Secure transactions, compliance | | @ENTERPRISE-DOMAIN | Business customizations | General enterprise features | | @COMPLIANCE-DOMAIN | Regulatory features | Audit trails, data governance | | @MULTI-TENANT-DOMAIN | Multi-organization | Tenant isolation, org-based auth | | @MCP-INTEGRATION | MCP server integration | Protocol connections, tool discovery | | @GENERATIVE-UI | Dynamic UI generation | AI-generated React components |

🚀 Quick Start

1. Framework Setup

# Clone the repository
git clone https://github.com/your-org/universal-ai-chat-framework
cd universal-ai-chat-framework

# Run automated setup
./scripts/setup-framework.sh

# The setup script will:
# ✅ Install dependencies
# ✅ Initialize shadcn/ui components  
# ✅ Create domain templates
# ✅ Set up TypeScript configuration
# ✅ Create environment template

2. Environment Configuration

# Copy environment template
cp .env.example .env.local

# Add your API keys
ANTHROPIC_API_KEY=your_anthropic_key
OPENAI_API_KEY=your_openai_key
XAI_API_KEY=your_xai_key

# Configure your domain
DEFAULT_DOMAIN=medical  # or maritime, financial, enterprise

3. Domain Customization

Choose your domain and customize the tagged zones:

# Medical domain example
grep -r "@MEDICAL-DOMAIN" src/
# Customize healthcare-specific features

# Maritime domain example  
grep -r "@MARITIME-DOMAIN" src/
# Customize shipping and logistics features

4. Development Server

npm run dev
# Visit http://localhost:3000

🏗️ Architecture Overview

graph TB
    UI[React UI Layer] --> Engine[Universal Chat Engine]
    Engine --> GenUI[Generative UI Manager]
    Engine --> Tools[Tool Registry]
    Engine --> MCP[MCP Integration]
    Engine --> AI[AI SDK 5.0]
    
    AI --> Anthropic[Anthropic Claude]
    AI --> OpenAI[OpenAI GPT]
    AI --> XAI[X.AI Grok]
    
    MCP --> FSServer[Filesystem Server]
    MCP --> DBServer[Database Server]
    MCP --> SearchServer[Search Server]
    
    Tools --> MedTools[Medical Tools]
    Tools --> MarTools[Maritime Tools]
    Tools --> FinTools[Financial Tools]
    
    GenUI --> MedUI[Medical Components]
    GenUI --> MarUI[Maritime Components]
    GenUI --> FinUI[Financial Components]

📊 Domain Examples

🏥 Medical Domain

// Medical case analysis with HIPAA compliance
const medicalConfig: DomainConfiguration = {
  name: 'medical',
  displayName: 'Medical AI Assistant',
  tools: [
    {
      name: 'analyzeMedicalCase',
      description: 'Analyze medical cases with HIPAA compliance',
      compliance: {
        hipaaCompliant: true,
        auditTrail: true,
        dataIsolation: true
      }
    }
  ],
  ui: {
    theme: 'medical',
    primaryColor: '#0066cc',
    voice: { 
      enabled: true, 
      medicalTerminology: true 
    }
  }
}

🚢 Maritime Domain

// Vessel tracking and logistics
const maritimeConfig: DomainConfiguration = {
  name: 'maritime',
  displayName: 'Maritime AI Assistant',
  tools: [
    {
      name: 'trackVessel',
      description: 'Real-time vessel tracking',
      parameters: z.object({
        vesselId: z.string(),
        includeRoute: z.boolean().optional()
      })
    }
  ],
  ui: {
    theme: 'maritime',
    primaryColor: '#1e40af'
  }
}

🎨 Generative UI Examples

Medical Case Analysis Component

// AI generates this component dynamically
<MedicalCaseAnalysis
  caseId="CASE-2024-001"
  analysis="Patient shows improvement in vital signs"
  recommendations={["Continue medication", "Schedule follow-up"]}
  complianceStatus="HIPAA_COMPLIANT"
/>

Maritime Vessel Tracker

// AI generates vessel tracking UI
<VesselTracker
  vesselId="MV-ATLANTIC-STAR"
  position={{ lat: 25.7617, lng: -80.1918 }}
  status="IN_TRANSIT"
  eta="2024-01-15T10:30:00Z"
/>

🔌 MCP Integration

Server Configuration

// Connect to MCP servers
const mcpClient = new MCPClient()

await mcpClient.registerServer({
  name: 'filesystem',
  transport: 'stdio',
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-filesystem'],
  capabilities: { tools: true, resources: true }
})

// Auto-discover and register tools
const tools = await mcpClient.discoverTools()

Available MCP Servers

• Filesystem - File operations and document management
• Database - PostgreSQL, MySQL, and other database integrations
• Search - Brave Search, Google Search, and web crawling
• Git - Repository management and code analysis
• Custom - Build your own domain-specific MCP servers

📁 Project Structure

universal-ai-chat-framework/
├── src/
│   ├── framework/
│   │   ├── core/
│   │   │   ├── UniversalChatEngine.tsx    # Main framework component
│   │   │   ├── GenerativeUIManager.tsx    # Dynamic UI generation
│   │   │   ├── MCPIntegration.ts          # MCP protocol client
│   │   │   ├── ToolRegistry.ts            # Tool management
│   │   │   └── VoiceManager.ts            # Voice input handling
│   │   ├── components/                     # Framework UI components
│   │   └── types/                         # TypeScript definitions
│   ├── domains/
│   │   ├── medical/                       # 🏥 Healthcare specialization
│   │   ├── maritime/                      # 🚢 Shipping & logistics
│   │   ├── financial/                     # 💰 Finance & banking
│   │   └── enterprise/                    # 🏢 General business
│   ├── components/ui/                     # shadcn/ui components
│   └── app/                              # Next.js App Router
├── scripts/
│   ├── setup-framework.sh                # Automated setup
│   ├── deploy-domain.js                  # Domain-specific deployment
│   └── tag-processor.js                  # Process domain tags
├── docs/
│   ├── DEPLOYMENT.md                     # Deployment guide
│   ├── DOMAINS.md                        # Domain customization
│   └── MCP.md                           # MCP integration guide
└── .env.example                         # Environment template

🚀 Deployment Options

Vercel (Recommended)

# One-click deploy
vercel

# With domain customization
vercel --env DEFAULT_DOMAIN=medical

Docker

# Build with domain
docker build --build-arg NEXT_PUBLIC_DEFAULT_DOMAIN=medical -t ai-chat .

# Run container
docker run -p 3000:3000 ai-chat

Azure Container Apps

# Deploy to Azure
az containerapp create \
  --name ai-chat-framework \
  --resource-group ai-chat-rg \
  --environment ai-chat-env \
  --image ai-chat:latest \
  --env-vars DEFAULT_DOMAIN=medical

See DEPLOYMENT.md for complete deployment instructions.

🔧 Customization Guide

1. Choose Your Domain

Select the domain that best fits your use case:

• Medical: Healthcare, patient management, HIPAA compliance
• Maritime: Shipping, vessel tracking, logistics
• Financial: Banking, transactions, compliance
• Enterprise: General business, CRM, operations

2. Find Tagged Zones

Search for domain-specific tags:

# Find medical customization points
grep -r "@MEDICAL-DOMAIN" src/

# Find maritime customization points  
grep -r "@MARITIME-DOMAIN" src/

3. Customize Components

Modify tagged zones to fit your needs:

// ████████████████████████████████████████████████████████████████
// █  🏥 @MEDICAL-DOMAIN: Customize healthcare features
// ████████████████████████████████████████████████████████████████
const medicalTools = [
  // Add your medical-specific tools here
]

4. Add Your Tools

Create domain-specific tools:

const customTool: ToolDefinition = {
  name: 'customDomainTool',
  description: 'Your domain-specific functionality',
  parameters: z.object({
    // Define your parameters
  }),
  execute: async (params) => {
    // Your tool implementation
  },
  compliance: {
    // Set compliance requirements
  }
}

🧪 Testing

# Run all tests
npm test

# Type checking
npm run type-check

# Linting
npm run lint

# Build test
npm run build

📚 Documentation

• Deployment Guide - Complete deployment instructions
• Domain Customization - Detailed customization guide
• MCP Integration - Model Context Protocol setup
• API Reference - Framework API documentation
• Examples - Domain-specific examples

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🌟 Acknowledgments

• Vercel AI SDK for the amazing AI framework
• Model Context Protocol for standardized AI integrations
• shadcn/ui for beautiful React components
• Next.js for the incredible React framework