Skip to content

README.md

Latest commit

 

History

History
291 lines (227 loc) · 8.95 KB

README.md

File metadata and controls

291 lines (227 loc) · 8.95 KB

📚 Chronicles - AI-Powered Knowledge Management System

Vercel React TypeScript Vite License

Transform conversations into organized knowledge with AI-powered insights

🚀 Live Demo • 📖 Documentation • 🤝 Contributing

📸 Screenshots & Architecture

Chronicles Architecture Diagram
QR Code

✨ Features

🎙️ Real-time Conversation Detection

  • Automatically detects when ElevenLabs conversations end
  • Real-time conversation monitoring and event handling
  • Smart popup notifications for completed sessions

📊 Knowledge Base Management

  • Organized story categorization system
  • AI-powered content analysis and insights
  • Interactive knowledge gap identification
  • Advanced search and filtering capabilities

🔄 Conversation Sync

  • Seamless ElevenLabs integration with API wrapper
  • Transcript capture and processing
  • Conversation metadata extraction
  • Real-time sync with knowledge base

🤖 AI-Powered Features

  • Intelligent conversation summarization
  • Key topic extraction
  • Knowledge gap analysis
  • Smart content suggestions

🎨 Modern UI/UX

  • Beautiful shadcn/ui component library
  • Responsive design with Tailwind CSS
  • Dark/light theme support
  • Intuitive navigation and user experience

🛠️ Tech Stack

Frontend

  • React 18 - Modern UI library with hooks
  • TypeScript - Type-safe development
  • Vite - Lightning-fast build tool
  • Tailwind CSS - Utility-first CSS framework
  • shadcn/ui - Beautiful component library
  • React Router - Client-side routing
  • React Query - Server state management

Backend & Services

  • Vercel - Serverless deployment platform
  • Supabase - Backend-as-a-Service database
  • ElevenLabs API - AI conversation platform
  • OpenAI API - AI text processing and embeddings

Development Tools

  • ESLint - Code linting and quality
  • Concurrently - Run multiple scripts
  • React Hook Form - Form state management
  • Zod - Schema validation

🚀 Quick Start

Prerequisites

  • Node.js 18+ and npm
  • ElevenLabs API account
  • Supabase project (optional)
  • OpenAI API key (optional, for embeddings)

1. Clone & Install

git clone https://github.com/Susmithareddya/Chronicles.git
cd Chronicles
npm install

2. Environment Setup

# Copy environment template
cp .env.example .env

# Edit .env with your API keys
VITE_ELEVEN_LABS_API_KEY=your-elevenlabs-api-key
VITE_OPENAI_API_KEY=your-openai-api-key
VITE_SUPABASE_URL=your-supabase-url
VITE_SUPABASE_ANON_KEY=your-supabase-key

3. Development Server

# Start development server
npm run dev

# Or start with API routes (recommended)
npm run dev:api

# Or start both frontend and API
npm run dev:full

4. Proxy Server (Optional)

For enhanced ElevenLabs integration:

cd server
npm install
npm start

Visit http://localhost:5173 to start using Chronicles!

📁 Project Structure

Chronicles/
├── 📁 src/
│   ├── 📁 components/          # Reusable UI components
│   │   ├── ConversationSync*.tsx    # Conversation management
│   │   ├── KnowledgeBase*.tsx       # Knowledge base UI
│   │   └── ui/                      # shadcn/ui components
│   ├── 📁 pages/               # Route components
│   │   ├── Index.tsx                # Main dashboard
│   │   ├── ConversationSync.tsx     # Sync interface
│   │   └── KnowledgeGaps.tsx        # Gap analysis
│   ├── 📁 services/            # API and business logic
│   │   ├── conversationDetectionService.ts
│   │   ├── elevenlabsService.ts
│   │   └── supabaseClient.ts
│   └── 📁 lib/                 # Utilities and configurations
├── 📁 server/                  # Proxy server (optional)
├── 📁 api/                     # Vercel serverless functions
└── 📁 public/                  # Static assets

🎯 Core Features Deep Dive

Conversation Detection Service

Real-time monitoring of ElevenLabs conversations with automatic event handling:

const detectionService = new ConversationDetectionService();
const unsubscribe = detectionService.addEventListener((event) => {
  if (event.status === 'ended') {
    // Handle conversation completion
    processConversation(event.conversationId);
  }
});

Knowledge Base Dashboard

Interactive dashboard for managing and exploring your knowledge:

  • Story Cards: Visual representation of conversations
  • Category Filtering: Organize by topics and themes
  • Search: Find specific conversations quickly
  • Analytics: Insights into conversation patterns

ElevenLabs Integration

Comprehensive API wrapper for ElevenLabs services:

  • Conversation retrieval and management
  • Transcript processing and analysis
  • Real-time status monitoring
  • Error handling and retry logic

🔧 Configuration

Environment Variables

Variable Description Required
VITE_ELEVEN_LABS_API_KEY ElevenLabs API authentication ✅
VITE_OPENAI_API_KEY OpenAI API for embeddings 🟡
VITE_SUPABASE_URL Supabase project URL 🟡
VITE_SUPABASE_ANON_KEY Supabase anonymous key 🟡
VITE_USE_PROXY Use proxy server mode ❌
VITE_PROXY_URL Proxy server URL ❌

Development Scripts

npm run dev          # Start Vite development server
npm run dev:api      # Start Vercel dev server with API routes
npm run dev:full     # Start both frontend and API concurrently
npm run build        # Production build
npm run build:dev    # Development build
npm run lint         # Run ESLint
npm run preview      # Preview production build

🚀 Deployment

Vercel (Recommended)

Chronicles is optimized for Vercel deployment:

# Install Vercel CLI
npm i -g vercel

# Deploy to production
vercel --prod

Environment Variables on Vercel

Add these environment variables in your Vercel dashboard:

  • VITE_ELEVEN_LABS_API_KEY
  • VITE_OPENAI_API_KEY (optional)
  • VITE_SUPABASE_URL (optional)
  • VITE_SUPABASE_ANON_KEY (optional)

🧪 Testing & Development

Available Test Features

  • Conversation Sync Tester: Test ElevenLabs integration
  • WebSocket Bypass: Direct API testing
  • Webhook Tester: Test event handling
  • Quick Test Button: Rapid development testing

Development Mode Features

// Test conversation popup (dev only)
window.testConversationPopup();

📊 API Routes

Vercel Serverless Functions

  • /api/elevenlabs/conversations - Fetch conversations
  • /api/elevenlabs/agents - List available agents
  • /api/elevenlabs/conversation/[id] - Get specific conversation

Health Check

  • /api/health - Service status and connectivity

🤝 Contributing

We welcome contributions! Please follow these steps:

  1. Fork the repository
  2. Create a 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

Development Guidelines

  • Follow TypeScript best practices
  • Use existing component patterns
  • Maintain consistent code style with ESLint
  • Test your changes thoroughly
  • Update documentation as needed

📝 License

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

🙋‍♂️ Support

🎉 Acknowledgments

  • shadcn/ui for the beautiful component library
  • ElevenLabs for the powerful conversation AI platform
  • Vercel for seamless deployment
  • Supabase for backend infrastructure

Built with ❤️ by the Chronicles team

⭐ Star this repo if you find it helpful!