ZheroHero AI - Advanced Multi-Model AI Chat Platform

A comprehensive AI chat interface that supports multiple AI models with advanced features like parallel conversations, folder organization, and Model Context Protocol (MCP) server integration.

🚀 Live Demo • 📖 Documentation • 🐛 Report Bug • 💡 Request Feature

---

🌟 Overview

ZheroHero AI is a modern, feature-rich AI chat platform inspired by MindDeck.ai, built with cutting-edge web technologies. It provides a seamless interface to interact with multiple AI providers through a single, unified platform.

✨ Key Features

• 🤖 Multi-Provider AI Support: Integrate with 5 major AI providers
• 📊 44+ AI Models: Access to the latest models from top providers
• 🎨 Modern UI/UX: Dark/light mode, responsive design, intuitive interface
• ⚡ Performance Optimized: React optimizations, lazy loading, efficient rendering
• 🔧 Advanced Configuration: Fine-tune model parameters for optimal results
• 🔍 Smart Search & Filtering: Find the right model quickly
• 📱 Mobile Responsive: Works seamlessly across all devices
• 🛡️ Type-Safe: Built with TypeScript for reliability

---

🚀 Current Implementation Status

✅ Phase 1: Foundation & Core Infrastructure (Completed)

• ✅ Next.js 14 setup with TypeScript
• ✅ Tailwind CSS configuration
• ✅ Sidebar navigation with routing
• ✅ Chat sidebar with search
• ✅ Theme toggle functionality
• ✅ Responsive layout system

✅ Phase 2: Chat Interface & Message System (Completed)

• ✅ Empty state with new chat buttons
• ✅ Basic chat interface
• ✅ Message components (user/AI)
• ✅ Chat input with send functionality
• ✅ Local chat storage with Zustand
• ✅ Message threading and history

✅ Phase 3: Models Management System (Completed)

• ✅ Complete models page with 44+ AI models
• ✅ Model cards grid (responsive 1/2/3/4 columns)
• ✅ Advanced model configuration dialogs
• ✅ Search and filtering by provider
• ✅ Import/export model configurations
• ✅ Performance optimizations (81% faster renders)
• ✅ Provider logos and "New" badges

🔄 Phase 4: AI Integration (Coming Next)

• 🔲 OpenAI API integration
• 🔲 Anthropic Claude integration
• 🔲 Google Gemini integration
• 🔲 xAI Grok integration
• 🔲 DeepSeek integration
• 🔲 Streaming responses

📋 Future Phases

• Phase 5: MCP Servers & Custom Integrations
• Phase 6: Advanced Features (Folders, Starred Chats, Export)
• Phase 7: Polish & Optimization

---

🤖 Supported AI Models

Provider	Models Count	Latest Models
OpenAI	22 models	GPT-5 series, O-series, GPT-4.1, GPT-4o
Anthropic	10 models	Claude Opus 4.1, Claude 4 series, Claude 3.7/3.5 Sonnet
Google Gemini	9 models	Gemini 2.5, 2.0, 1.5 series
xAI	3 models	Grok 4, Grok 3 series
DeepSeek	2 models	DeepSeek Chat, DeepSeek Reasoner

Total: 44+ AI Models across 5 major providers

---

🛠️ Tech Stack

Frontend Framework

• Next.js 14.2.32 - React framework with App Router
• TypeScript 5.0+ - Type-safe development
• React 18 - Latest React features and optimizations

Styling & UI

• Tailwind CSS 3.3+ - Utility-first CSS framework
• Lucide React - Beautiful, customizable icons
• Custom UI Components - Reusable component library
• Dark/Light Mode - System preference support

State Management

• Zustand - Lightweight state management
• Custom Hooks - Optimized state subscriptions
• Persistent Storage - Local storage integration
• Performance Middleware - Shallow comparisons and memoization

Performance & Optimization

• React.memo - Component memoization
• useMemo/useCallback - Expensive computation optimization
• Lazy Loading - Dynamic imports and code splitting
• Bundle Optimization - Tree shaking and minimization

Development Tools

• ESLint - Code quality and consistency
• TypeScript Strict Mode - Enhanced type checking
• Performance Monitoring - Real-time render tracking
• Sitemap Generation - SEO optimization

---

🚀 Getting Started

Prerequisites

• Node.js 18+
• npm or yarn
• Git

Installation

1. Clone the repository

   git clone https://github.com/fedec65/zherohero-ai.git
   cd zherohero-ai

2. Install dependencies

   npm install
   # or
   yarn install

3. Set up environment variables

   cp .env.example .env.local

   Configure your API keys:

   OPENAI_API_KEY=your_openai_key
   ANTHROPIC_API_KEY=your_anthropic_key
   GOOGLE_API_KEY=your_google_key
   XAI_API_KEY=your_xai_key
   DEEPSEEK_API_KEY=your_deepseek_key

4. Start the development server

   npm run dev
   # or
   yarn dev

5. Open your browser Navigate to http://localhost:3000

Build for Production

npm run build
npm run start

---

📁 Project Structure

zherohero-ai/
├── src/
│   ├── app/                    # Next.js App Router pages
│   │   ├── layout.tsx         # Root layout
│   │   ├── page.tsx           # Home page (chat)
│   │   ├── models/            # Models management page
│   │   └── mcp-servers/       # MCP servers page
│   ├── components/
│   │   ├── ui/                # Reusable UI components
│   │   ├── layout/            # Layout components
│   │   ├── chat/              # Chat interface components
│   │   ├── models/            # Model management components
│   │   └── mcp/               # MCP server components
│   └── lib/
│       ├── stores/            # Zustand state management
│       ├── types/             # TypeScript definitions
│       └── utils/             # Utility functions
├── public/
│   ├── logos/                 # Provider logos
│   └── icons/                 # App icons
└── docs/                      # Documentation

---

🎨 Features Overview

🗂️ Models Management

• 44+ AI Models from 5 major providers
• Advanced Configuration - Temperature, tokens, penalties
• Search & Filter - Find models by provider or name
• Import/Export - Save and share model configurations
• Performance Optimized - Smooth rendering of large model lists

💬 Chat Interface

• Multi-Model Conversations - Switch between models mid-chat
• Message History - Persistent chat storage
• Responsive Design - Works on desktop and mobile
• Dark/Light Mode - Automatic theme switching

⚡ Performance Features

• 81% Faster Renders - Optimized with React.memo
• Efficient State Management - Selective re-renders
• Bundle Optimization - Code splitting and lazy loading
• Real-time Monitoring - Development performance tracking

---

📊 Performance Metrics

Metric	Before Optimization	After Optimization	Improvement
Model Grid Render	~45ms	~8.4ms	81% faster
Model Card Render	Varies	~2.1ms	95% improvement
Filter/Sort Operations	~120ms	~35ms	70% faster
Bundle Size	N/A	19.3 kB	Optimized

---

🔧 Configuration

Model Configuration Options

interface ModelConfig {
  temperature: number // 0-2, controls creativity
  maxTokens?: number // Maximum response length
  topP: number // 0-1, nucleus sampling
  frequencyPenalty: number // -2 to 2, reduces repetition
  presencePenalty: number // -2 to 2, encourages variety
  systemPrompt?: string // Custom system instructions
  stopSequences?: string[] // Custom stop sequences
}

Theme Configuration

interface ThemeSettings {
  theme: 'light' | 'dark' | 'system'
  effectiveTheme: 'light' | 'dark'
  accentColor: string
  fontFamily: string
}

---

🛡️ API Integration (Phase 4)

Supported Providers

type AIProvider = 'openai' | 'anthropic' | 'gemini' | 'xai' | 'deepseek'

interface AIProviderConfig {
  apiKey: string
  baseURL: string
  defaultModel: string
  rateLimits: {
    requestsPerMinute: number
    tokensPerMinute: number
  }
}

Security Features

• Server-side API Key Storage - Keys never exposed to client
• Rate Limiting - Prevent API abuse
• Input Validation - Sanitize all user inputs
• Error Handling - Graceful failure recovery

---

🤝 Contributing

We welcome contributions! Here's how you can help:

Development Process

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/amazing-feature

3. Make your changes
4. Add tests if applicable
5. Run the test suite

   npm run test
   npm run lint
   npm run build

6. Commit your changes

   git commit -m "feat: add amazing feature"

7. Push to your branch

   git push origin feature/amazing-feature

8. Open a Pull Request

Contribution Guidelines

• Code Style: Follow existing patterns and ESLint rules
• Type Safety: Maintain TypeScript strict mode compliance
• Performance: Consider performance impact of changes
• Testing: Add tests for new features
• Documentation: Update README and docs as needed

---

📜 Scripts

Script	Description
npm run dev	Start development server
npm run build	Build for production
npm run start	Start production server
npm run lint	Run ESLint
npm run lint:fix	Fix linting issues
npm run type-check	Run TypeScript checks

---

🐛 Troubleshooting

Common Issues

Build Errors

# Clear Next.js cache
rm -rf .next
npm run dev

TypeScript Errors

# Regenerate TypeScript declarations
npm run type-check

Performance Issues

• Enable the performance monitor in development
• Check for unnecessary re-renders in React DevTools
• Review bundle analysis with npm run analyze

---

📈 Roadmap

🔄 Phase 4: AI Integration (Next)

• Real AI provider API integrations
• Streaming response support
• Error handling and retries
• Rate limiting implementation

📋 Phase 5: MCP Servers

• Model Context Protocol integration
• Custom server management
• Auto-injection capabilities

✨ Phase 6: Advanced Features

• Folder organization system
• Starred conversations
• Export/import functionality
• Advanced search capabilities

🎯 Phase 7: Polish & Production

• End-to-end testing
• Performance optimizations
• Accessibility improvements
• Production deployment optimizations

---

📄 License

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

---

🙏 Acknowledgments

• MindDeck.ai - Original design inspiration
• Next.js Team - Amazing React framework
• Vercel - Deployment platform
• Tailwind CSS - Utility-first CSS framework
• Lucide Icons - Beautiful icon library

---

🔗 Links

• 🌐 Website: zherohero-ai.vercel.app
• 📊 Repository: github.com/fedec65/zherohero-ai
• 🐛 Issues: Report bugs or request features
• 💬 Discussions: Join the conversation

---

Made with ❤️ by Federico Cesconi

Building the future of AI interaction, one conversation at a time.