🌙 Lunara - AI Companion Chat Application

A modern, real-time AI chat application built with Next.js, featuring advanced voice chat capabilities, real-time messaging, and a beautiful user interface. Lunara provides an intelligent AI companion experience with natural conversation flows and cutting-edge voice interaction technology.

✨ Features

🤖 AI-Powered Conversations

Intelligent Responses: Powered by Google's Gemini AI with contextual understanding
Personality Customization: Choose from 5 AI personalities (friendly, professional, creative, analytical, empathetic)
Context-Aware: Maintains conversation history for meaningful, ongoing interactions
Custom AI Personalities: Fine-tuned prompts for different conversation styles

🎙️ Voice Chat Integration

Speech Recognition: Natural voice input using Web Speech API
Text-to-Speech: AI responses spoken aloud with customizable voice settings
Real-time Audio: Live voice conversations with visual feedback
Audio Level Monitoring: Real-time audio visualization and voice activity detection
Voice Customization: Adjustable speech rate, pitch, and voice preferences

💬 Real-Time Messaging

Live Updates: Messages appear instantly without page refresh using smart polling
Optimistic UI: Immediate feedback for better user experience
Typing Indicators: Visual feedback when Lunara is processing responses
Message Management: Edit, delete, and organize conversations

🎨 Modern UI/UX

Responsive Design: Fully optimized for mobile, tablet, and desktop devices
Dark/Light Themes: System-aware theme switching with smooth transitions
Smooth Animations: Framer Motion powered interactions and micro-animations
Glass Morphism: Modern design with backdrop blur effects and OKLCH colors
Accessibility: Built with Radix UI primitives for full accessibility support

👤 User Management

Secure Authentication: NextAuth.js with email/password and Google OAuth
Profile Management: Customizable user profiles with avatar uploads
Conversation History: Persistent chat history with search and organization
Data Export: Download your conversations in JSON or CSV format
Privacy Controls: Granular privacy settings and data management

🔧 Advanced Features

Conversation Management: Search, organize, and manage chat sessions
Notification System: Real-time activity notifications with priority levels
Settings Panel: Comprehensive customization for voice, theme, and AI behavior
Mobile Optimized: Touch-friendly interface with safe area support
API Key Management: Personal Gemini API key support for unlimited usage
Maintenance Mode: Built-in maintenance mode for updates and deployments

🏗️ Tech Stack

Frontend

Next.js 15 - React framework with App Router and Server Components
TypeScript 5 - Type-safe development with strict mode
Tailwind CSS 4 - Utility-first styling with OKLCH colors and modern features
Framer Motion - Smooth animations and transitions
Radix UI - Accessible component primitives and design system
Zustand - Lightweight state management with TypeScript support
React Hook Form - Performant forms with easy validation

Backend & Database

Next.js API Routes - Serverless API endpoints with middleware
Prisma - Type-safe database ORM with migrations and client generation
PostgreSQL - Robust relational database with advanced features
NextAuth.js - Authentication with multiple providers and session management
Zod - TypeScript-first schema validation with static type inference
bcryptjs - Password hashing library for Node.js

AI & Voice Technology

Google Gemini AI - Advanced language model for intelligent responses
@google/generative-ai - Official Google Generative AI SDK
Web Speech API - Browser-native speech recognition
Speech Synthesis API - Text-to-speech capabilities
WebRTC - Real-time communication (planned future enhancement)

UI/UX Libraries

shadcn/ui - Re-usable components built using Radix UI and Tailwind CSS
next-themes - Perfect dark mode in Next.js with system theme detection
Sonner - An opinionated toast component for React
class-variance-authority - Type-safe component variants with TypeScript
tailwind-merge - Merge Tailwind CSS classes without style conflicts
clsx - Tiny utility for constructing className strings conditionally

Development & Deployment

ESLint 9 - Code linting with Next.js and TypeScript rules
PostCSS - CSS transformation tool with plugin ecosystem
Turbopack - Incremental bundler optimized for JavaScript and TypeScript
Vercel - Optimized deployment platform for Next.js
cross-env - Cross-platform environment variable setting

🚀 Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

Node.js 18+ - Download
PostgreSQL 14+ - Download or use a cloud provider
Google Gemini API Key - Get your key
Git - Download

Quick Start

Clone the repository

git clone https://github.com/Celestial-0/Lunara.git
cd Lunara

Install dependencies
```
npm install
```

Set up environment variables

cp .env.example .env.local

Fill in your environment variables in .env.local:

# Database
DATABASE_URL="postgresql://username:password@localhost:5432/lunara"

# NextAuth
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="your-nextauth-secret-key"

# Google OAuth (optional)
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

# AI
GEMINI_API_KEY="your-gemini-api-key"

Set up the database

# Generate Prisma client
npm run db:generate

# Push database schema
npm run db:push

Start the development server
```
npm run dev
```
Open your browser Navigate to http://localhost:3000 and start chatting with Lunara!

🎙️ Voice Chat Setup

Getting Your Gemini API Key

Visit Google AI Studio
- Go to https://makersuite.google.com/app/apikey
- Sign in with your Google account
Create API Key
- Click "Create API Key"
- Choose your project or create a new one
- Copy the generated API key
Add to Environment
- Add to your .env.local file: GEMINI_API_KEY="your-api-key-here"
- Or add directly in the app settings for personal use

Browser Compatibility & Permissions

Supported Browsers

✅ Chrome/Chromium: Full support for all voice features
✅ Microsoft Edge: Full support for all voice features
⚠️ Firefox: Limited voice recognition support
⚠️ Safari: Limited voice features, no speech recognition

Required Permissions

🎤 Microphone Access: Required for voice input and audio level monitoring
🔊 Audio Playback: Automatic for text-to-speech responses
🔒 HTTPS: Voice features work best over HTTPS in production

Optimizing Voice Quality

Use a quality microphone or headset for best recognition
Speak clearly and at a normal pace
Minimize background noise
Ensure stable internet connection for AI processing

🎯 Usage Guide

Getting Started with Conversations

Sign up/Login
- Use email and password or sign in with Google OAuth
- Complete your profile setup for a personalized experience
Start Your First Chat
- Click "New Conversation" or begin typing in the chat interface
- Choose an AI personality that matches your conversation style
- Ask questions, seek advice, or just have a friendly chat
Voice Chat Features
- Click the phone icon in the chat header to start voice mode
- Allow microphone permissions when prompted
- Click "Start Talking" and speak naturally to Lunara
- Lunara will respond with both text and voice

Managing Your Experience

Search Conversations: Use the conversation manager to find past chats
Edit Titles: Click the edit icon to rename conversations
Export Data: Download your conversation history from settings
Customize Settings: Adjust voice, theme, and AI behavior preferences
Manage API Keys: Add your personal Gemini API key for unlimited usage

⚙️ Configuration

AI Personality Settings

Customize Lunara's conversation style in the Settings panel:

🤗 Friendly: Warm, conversational, and supportive responses
💼 Professional: Business-focused, efficient, and direct communication
🎨 Creative: Imaginative, colorful language, and innovative thinking
📊 Analytical: Logical, data-driven, and detailed explanations
💝 Empathetic: Understanding, emotionally aware, and compassionate

Voice Configuration

Fine-tune voice interaction settings:

Voice Speed: Adjust speech rate from 0.5x to 2.0x
Voice Pitch: Modify voice pitch from 0.5x to 2.0x
Enable/Disable: Toggle voice features on/off
Audio Feedback: Visual audio level monitoring
Browser Compatibility: Works best in Chrome and Edge

API Key Management

For unlimited usage, add your personal Gemini API key:

Visit Google AI Studio
Create a new API key
Add it in Settings → API Key Management
Enjoy unlimited conversations without rate limits

Theme & Appearance

System: Automatically matches your device's theme
Light: Clean, bright interface for daytime use
Dark: Easy on the eyes for evening conversations

🛠️ Development

Project Architecture

Lunara/
├── app/                          # Next.js App Router
│   ├── api/                     # API routes and endpoints
│   │   ├── auth/               # Authentication endpoints
│   │   ├── chat/               # AI chat processing
│   │   ├── conversations/      # Conversation management
│   │   ├── messages/           # Message handling
│   │   ├── notifications/      # Notification system
│   │   ├── preferences/        # User settings
│   │   ├── profile/            # Profile management
│   │   ├── search/             # Search functionality
│   │   └── export/             # Data export
│   ├── auth/                   # Authentication pages
│   ├── chat/                   # Main chat interface
│   ├── maintenance/            # Maintenance mode pages
│   ├── globals.css             # Global styles and Tailwind
│   ├── layout.tsx              # Root layout component
│   └── page.tsx                # Home page
├── components/                  # React components
│   ├── auth/                   # Authentication components
│   │   ├── AuthProvider.tsx    # Auth context provider
│   │   └── SignInForm.tsx      # Login/signup form
│   ├── chat/                   # Chat-specific components
│   │   ├── ChatInterface.tsx   # Main chat UI
│   │   ├── VoiceChat.tsx       # Voice chat interface
│   │   ├── MessageBubble.tsx   # Individual messages
│   │   ├── Sidebar.tsx         # Navigation sidebar
│   │   ├── SettingsDialog.tsx  # Settings panel
│   │   ├── ProfileDialog.tsx   # Profile management
│   │   ├── ConversationManager.tsx  # Chat organization
│   │   ├── NotificationCenter.tsx   # Notifications
│   │   ├── AudioControls.tsx   # Audio controls
│   │   ├── TypingIndicator.tsx # Loading states
│   │   └── ApiKeyDialog.tsx    # API key management
│   ├── core/                   # Core UI components
│   │   ├── ThemeProvider.tsx   # Theme management
│   │   ├── ThemeToggle.tsx     # Theme switcher
│   │   └── HomeUI.tsx          # Landing page
│   └── ui/                     # Reusable UI components (Radix)
├── lib/                        # Utilities and configurations
│   ├── auth.ts                 # NextAuth configuration
│   ├── prisma.ts               # Database client
│   ├── store.ts                # Zustand state management
│   ├── utils.ts                # Utility functions
│   ├── api-client.ts           # API client wrapper
│   ├── hooks/                  # Custom React hooks
│   │   ├── useApi.ts           # API integration hook
│   │   ├── useRealTimeMessages.ts  # Real-time updates
│   │   └── useVoiceChat.ts     # Voice chat functionality
│   └── generated/              # Prisma generated files
├── prisma/                     # Database schema and migrations
│   ├── schema.prisma           # Database schema
│   └── migrations/             # Database migrations
├── public/                     # Static assets
├── types/                      # TypeScript type definitions
│   └── types.ts                # Shared type definitions
├── .env.example                # Environment variables template
├── next.config.ts              # Next.js configuration
├── tailwind.config.ts          # Tailwind CSS configuration
├── tsconfig.json               # TypeScript configuration
└── package.json                # Dependencies and scripts

Key Components Deep Dive

Core Chat Components

ChatInterface: Main chat UI with real-time messaging, voice controls, and mobile optimization
VoiceChat: Voice interaction with speech recognition and synthesis
MessageBubble: Individual message display with timestamps and status
Sidebar: Navigation, conversation list, and user management
NotificationCenter: Real-time notifications with priority levels

State Management

Zustand Store: Lightweight state management for conversations, messages, and UI state
Real-time Updates: Custom hooks for polling and optimistic updates
Persistence: Session storage for UI state and local caching

Database Schema

Users: Authentication and profile data with NextAuth integration
Conversations: Chat sessions with metadata and timestamps
Messages: Individual chat messages with role-based content
UserPreferences: Settings, theme, and AI personality configuration
UserProfile: Extended profile information and avatar management
Notifications: Real-time activity notifications with read status

Development Scripts

# Development
npm run dev              # Start development server with Turbopack
npm run build           # Build for production
npm run start           # Start production server
npm run lint            # Run ESLint

# Database
npm run db:generate     # Generate Prisma client
npm run db:push         # Push schema to database
npm run db:migrate      # Run database migrations
npm run db:studio       # Open Prisma Studio

Environment Variables

# Database
DATABASE_URL="postgresql://user:password@localhost:5432/lunara"

# Authentication
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="your-secret-key"

# Google OAuth (optional)
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

# AI Integration
GEMINI_API_KEY="your-gemini-api-key"

# Optional Features
MAINTENANCE_MODE="false"

🚀 Deployment

Vercel (Recommended)

Lunara is optimized for Vercel deployment:

Connect Repository
- Fork this repository to your GitHub account
- Connect your Vercel account to GitHub
- Import the Lunara project

Configure Environment Variables

DATABASE_URL="your-production-database-url"
NEXTAUTH_URL="https://your-domain.vercel.app"
NEXTAUTH_SECRET="your-production-secret"
GEMINI_API_KEY="your-gemini-api-key"
GOOGLE_CLIENT_ID="your-google-client-id"      # Optional
GOOGLE_CLIENT_SECRET="your-google-client-secret"  # Optional

Database Setup
- Use a PostgreSQL provider (Railway, Supabase, PlanetScale, etc.)
- Run migrations: npx prisma migrate deploy
- Generate client: npx prisma generate
Deploy
- Push to main branch for automatic deployment
- Vercel handles build optimization and CDN distribution

Alternative Deployment Options

Docker Deployment

# Use official Node.js runtime
FROM node:18-alpine

# Set working directory
WORKDIR /app

# Copy package files
COPY package*.json ./

# Install dependencies
RUN npm ci --only=production

# Copy app source
COPY . .

# Generate Prisma client
RUN npx prisma generate

# Build application
RUN npm run build

# Expose port
EXPOSE 3000

# Start application
CMD ["npm", "start"]

Self-Hosted Setup

Clone repository on your server
Install Node.js 18+ and PostgreSQL
Set up environment variables
Run database migrations
Build and start the application
Configure reverse proxy (nginx/Apache)

🤝 Contributing

We welcome contributions to Lunara! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.

Getting Started

Fork the repository

git fork https://github.com/Celestial-0/Lunara.git

Clone your fork

git clone https://github.com/your-username/Lunara.git
cd Lunara

Create a feature branch
```
git checkout -b feature/amazing-feature
```
Make your changes
- Follow the existing code style
- Add tests for new features
- Update documentation as needed

Commit your changes

git commit -m 'feat: add amazing feature'

Push to your branch
```
git push origin feature/amazing-feature
```
Open a Pull Request
- Describe your changes clearly
- Link to any relevant issues
- Wait for review and feedback

Development Guidelines

Code Style: Follow TypeScript and ESLint configurations
Commits: Use conventional commit messages (feat:, fix:, docs:, etc.)
Testing: Ensure all tests pass before submitting
Documentation: Update README and code comments for new features

Areas for Contribution

🐛 Bug Fixes: Check the issues tab for known bugs
✨ Features: Voice enhancements, UI improvements, new AI personalities
📚 Documentation: API docs, tutorials, code comments
🧪 Testing: Unit tests, integration tests, E2E tests
🎨 Design: UI/UX improvements, animations, themes
🌐 Internationalization: Multi-language support

📄 License

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

What this means:

✅ Commercial use allowed
✅ Modification allowed
✅ Distribution allowed
✅ Private use allowed
❌ No warranty provided
❌ No liability assumed

📞 Support & Community

Getting Help

📖 Documentation: Check this README and inline code comments
🐛 Bug Reports: Create an issue with detailed information
💡 Feature Requests: Open a discussion to propose new features
❓ Questions: Use GitHub Discussions for general questions

Stay Updated

⭐ Star the repository to stay notified of updates
👀 Watch releases for new version announcements
🍴 Fork to contribute and customize for your needs

🗺️ Roadmap

Upcoming Features

Long-term Vision

AI-powered conversation coaching and improvement suggestions
Integration with productivity tools and calendars
Voice-based automation and smart home control
Advanced emotional intelligence and context understanding
Blockchain integration for privacy and data ownership

Built with ❤️ using modern web technologies

Experience the future of AI conversation today!

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
.vscode		.vscode
app		app
components		components
lib		lib
prisma		prisma
public		public
types		types
.env.example		.env.example
.gitignore		.gitignore
API.md		API.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
components.json		components.json
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
proxy.ts		proxy.ts
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

🌙 Lunara - AI Companion Chat Application

✨ Features

🤖 AI-Powered Conversations

🎙️ Voice Chat Integration

💬 Real-Time Messaging

🎨 Modern UI/UX

👤 User Management

🔧 Advanced Features

🏗️ Tech Stack

Frontend

Backend & Database

AI & Voice Technology

UI/UX Libraries

Development & Deployment

🚀 Getting Started

Prerequisites

Quick Start

🎙️ Voice Chat Setup

Getting Your Gemini API Key

Browser Compatibility & Permissions

Supported Browsers

Required Permissions

Optimizing Voice Quality

🎯 Usage Guide

Getting Started with Conversations

Managing Your Experience

⚙️ Configuration

AI Personality Settings

Voice Configuration

API Key Management

Theme & Appearance

🛠️ Development

Project Architecture

Key Components Deep Dive

Core Chat Components

State Management

Database Schema

Development Scripts

Environment Variables

🚀 Deployment

Vercel (Recommended)

Alternative Deployment Options

Docker Deployment

Self-Hosted Setup

🤝 Contributing

Getting Started

Development Guidelines

Areas for Contribution

📄 License

What this means:

📞 Support & Community

Getting Help

Stay Updated

🗺️ Roadmap

Upcoming Features

Long-term Vision

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages