EchoAI

A modern, responsive AI chat workspace built with React, TypeScript, and Google Gemini

Features • Quick Start • Installation • Deployment • Contributing

📱 Demo

🖥️ Desktop View

📱 Mobile View

🎨 UI Screenshots

Light Mode	Dark Mode
Settings Modal	Error Handling

🚀 Try EchoAI Live • 📖 View Documentation

📊 Project Status

Status	Description
🟢 Stable	Production ready
🟢 Active	Regular updates
🟢 Maintained	Bug fixes & features
🟢 Documented	Comprehensive docs

🎯 Current Version: `v2.0.0`

✅ Workspace UI: Sidebar with saved chat history, "New Chat", and an editable profile
✅ Design: "Midnight Indigo" dark theme + premium light theme, with a signature animated AI orb
✅ AI Chat: Google Gemini integration, suggestion grid, retry & error recovery
✅ Security: Session-scoped API key storage, input validation
🔄 Roadmap: See Issues for upcoming features

🌟 Features

🎨 Modern Workspace Interface

Sidebar Navigation: Persistent chat history with rename/delete, a one-click "New Chat", and an editable local profile
"Midnight Indigo" Theme: A premium dark-first design with a polished light variant, toggleable anytime
Signature AI Orb: A pure-CSS glass-marble orb used as the brand mark, hero and thinking indicator
Responsive Design: Fixed sidebar on desktop, slide-in drawer on mobile — works across all devices
Accessibility: Keyboard-navigable, clear focus styles, and prefers-reduced-motion support

🤖 AI-Powered Conversations

Gemini Integration: Powered by Google Gemini 2.5 Flash for intelligent, contextual responses
Smart Suggestions: Pre-built prompts for common use cases
Context Awareness: Maintains conversation context throughout the chat
Error Recovery: Intelligent retry mechanisms with fallback options

💬 Saved Conversations

Multiple Chats: Start as many conversations as you like and switch between them instantly
Persistent History: Conversations are saved in your browser and survive reloads
Auto-Titles: Each chat is named from your first message — rename or delete anytime

🔐 Flexible API Key Management

User API Keys: Use your own Google Gemini API key for personal use
Server Fallback: Built-in server with default API key for easy setup
Session Storage: Your API key is kept only for the current browser session and never sent to our servers
Key Validation: Real-time API key testing and validation

⚡ Performance & Reliability

Fast Loading: Optimized bundle size and lazy loading
Error Handling: Comprehensive error handling with user-friendly messages
Retry Logic: Automatic retry mechanisms for failed requests
Offline Support: Graceful degradation when offline

🛠️ Developer Experience

TypeScript: Full type safety and excellent developer experience
Modern Stack: React 18, Vite, Tailwind CSS, and more
Hot Reload: Fast development with instant feedback
ESLint & Prettier: Consistent code formatting and quality

📋 Table of Contents

Click to expand

📱 Demo
🌟 Features
🚀 Quick Start
📦 Installation
⚙️ Configuration
💻 Usage
🏗️ Architecture
📚 API Documentation
🚀 Deployment
🤝 Contributing
📄 License
🙏 Acknowledgments
📞 Support

🚀 Quick Start

⚡ Get up and running in under 5 minutes!

📋 Prerequisites

Requirement	Version	Download
Node.js	≥ 20.0.0	Download
npm	Latest	Included with Node.js
Gemini API Key	Any	Get Key

⚡ One-Command Setup

# Clone, then let EchoAI install deps, configure env vars, and start both apps
git clone https://github.com/droidbg/EchoAI.git && cd EchoAI && npm run dev

npm run dev is end-to-end: it installs the client & server dependencies (first run only), sets safe defaults like VITE_SERVER_URL, interactively asks for your GEMINI_API_KEY (with steps to get one), then starts the client and server together.

1. Clone the Repository

git clone https://github.com/droidbg/EchoAI.git
cd EchoAI

2. Install Dependencies

# Install client dependencies
cd client
npm install

# Install server dependencies
cd ../server
npm install

3. Configure Environment

# Copy environment templates
cp client/.env.example client/.env
cp server/.env.example server/.env

Edit the environment files:

client/.env:

VITE_SERVER_URL=http://localhost:3080/

server/.env:

GEMINI_API_KEY=AIza-your-gemini-api-key-here

4. Start the Application

# Terminal 1: Start the server
cd server
npm start

# Terminal 2: Start the client
cd client
npm start

Visit http://localhost:5173 to see EchoAI in action! 🎉

📦 Installation

Option 1: Full Stack Setup (Recommended)

This setup includes both the React frontend and Node.js backend:

# Clone and setup
git clone https://github.com/droidbg/EchoAI.git
cd EchoAI

# Install all dependencies
npm run install:all

# Configure environment
cp client/.env.example client/.env
cp server/.env.example server/.env

# Start both client and server
npm run dev

Option 2: Client-Only Setup

If you prefer to use your own backend or API:

# Clone and setup client only
git clone https://github.com/droidbg/EchoAI.git
cd EchoAI/client

# Install dependencies
npm install

# Configure environment
cp .env.example .env

# Start client
npm start

Option 3: Server-Only Setup

For deploying just the backend:

# Clone and setup server only
git clone https://github.com/droidbg/EchoAI.git
cd EchoAI/server

# Install dependencies
npm install

# Configure environment
cp .env.example .env

# Start server
npm start

⚙️ Configuration

Environment Variables

Client Configuration (`client/.env`)

Variable	Description	Default	Required
`VITE_SERVER_URL`	Backend server URL	`http://localhost:3080/`	Yes
`VITE_DEBUG`	Enable debug mode	`false`	No

Server Configuration (`server/.env`)

Variable	Description	Default	Required
`GEMINI_API_KEY`	Your Gemini API key	-	Yes
`PORT`	Server port	`3080`	No
`NODE_ENV`	Environment mode	`development`	No
`CLIENT_URL`	Client URL for CORS	-	No (production)

API Key Setup

Using Your Own API Key (Recommended)

Get a Gemini API Key:
- Visit Google AI Studio
- Create a new API key
- Copy the key (starts with AIza)
Add to EchoAI:
- Click the settings gear icon in the top-right corner
- Paste your API key in the "Gemini API Key" field
- Click "Save Key"
- The system will test your key automatically

Using Server API Key

Add to Server Environment:

# In server/.env
GEMINI_API_KEY=AIza-your-gemini-api-key-here

Restart the Server:
```
cd server
npm start
```

💻 Usage

Basic Chat

Start a Conversation: Type your message in the input field
Send Message: Press Enter or click the send button
View Response: The AI response will appear in the chat
Continue Chatting: Keep the conversation going naturally

Using Suggestions

EchoAI provides helpful suggestions to get you started:

"Explain quantum computing" - Get explanations of complex topics
"Write a creative story" - Generate creative content
"Help with coding" - Get programming assistance
"Plan a vacation" - Get travel planning help

Error Handling

When errors occur, EchoAI provides helpful options:

Try Again: Retry the failed request
Use Your API Key: Switch to your personal API key
Clear Error: Dismiss the error and continue

Settings

Access settings by clicking the gear icon:

API Key Management: Add, test, or remove your API key
Theme Toggle: Switch between dark and light modes
Key Status: See which API key is currently active

🏗️ Architecture

Frontend (React + TypeScript)

client/
├── src/
│   ├── components/             # React components
│   │   ├── Sidebar.tsx         # Workspace nav: history, new chat, profile
│   │   ├── Header.tsx          # Top bar: status, settings, theme toggle
│   │   ├── Orb.tsx             # Signature animated AI orb
│   │   ├── ChatBody.tsx        # Message list + welcome / suggestion grid
│   │   ├── ChatInput.tsx       # Composer
│   │   ├── AiChat.tsx          # AI message bubble
│   │   ├── UserChat.tsx        # User message bubble
│   │   ├── TypingIndicator.tsx # Thinking animation
│   │   ├── InlineErrorOptions.tsx # In-bubble retry / use-own-key actions
│   │   └── SettingsModal.tsx   # API key settings
│   ├── utils/                  # Utilities & state
│   │   ├── Api.ts              # API communication
│   │   ├── ApiKeyManager.ts    # API key management
│   │   └── useConversations.ts # Reducer-backed chat store (localStorage)
│   ├── App.tsx                 # Workspace shell & orchestration
│   └── main.tsx                # Application entry point
├── public/                     # Static assets
└── package.json                # Dependencies and scripts

Backend (Node.js + Express)

server/
├── index.js               # Main server file
├── package.json          # Dependencies and scripts
├── vercel.json           # Vercel deployment config
└── .env.example          # Environment template

Technology Stack

Frontend

React 18 - Modern React with hooks, useReducer state and concurrent features
TypeScript - Type-safe JavaScript development
Vite - Fast build tool and development server
Tailwind CSS 4 - Utility-first styling layered over a custom design-token system
Fraunces + Plus Jakarta Sans - Distinctive serif/sans type pairing
React Query - Data fetching for chat requests
Auto Animate - Smooth list animations
localStorage - Client-side persistence for saved conversations

Backend

Node.js - JavaScript runtime
Express - Web application framework
Google GenAI SDK - Official @google/genai client for Gemini
CORS - Cross-origin resource sharing
dotenv - Environment variable management

📚 API Documentation

Server Endpoints

Health Check

GET /

Response:

{
  "status": "healthy",
  "service": "EchoAI Server",
  "version": "2.0.0",
  "timestamp": "2024-12-19T10:30:00.000Z",
  "environment": "development"
}

Chat Completion

POST /
Content-Type: application/json

{
  "message": "Hello, how are you?"
}

Response:

{
  "message": "Hello! I'm doing well, thank you for asking. How can I help you today?",
  "usage": {
    "promptTokenCount": 10,
    "candidatesTokenCount": 20,
    "totalTokenCount": 30
  },
  "model": "gemini-2.5-flash"
}

Error Responses:

Status	Error	Description
400	Invalid request	Missing or invalid message
401	Invalid API key	Gemini API key is invalid
402	Insufficient quota	Gemini API quota exceeded
429	Rate limit exceeded	Too many requests
500	Internal server error	Server-side error

Client API

Message Type

interface Message {
  sender: 'user' | 'ai';
  message: string;
  isError?: boolean;
  errorId?: string;
}

API Functions

// Fetch AI response
fetchResponse(messages: Message[]): Promise<{ message: string }>

// API Key Management
ApiKeyManager.getApiKey(): string | null
ApiKeyManager.setApiKey(key: string): void
ApiKeyManager.clearApiKey(): void
ApiKeyManager.validateApiKeyFormat(key: string): { isValid: boolean; message: string }
ApiKeyManager.testApiKey(key: string): Promise<{ isValid: boolean; message: string }>

🚀 Deployment

Option 1: Vercel (Recommended)

Deploy Client

# Install Vercel CLI
npm i -g vercel

# Deploy client
cd client
vercel

# Follow the prompts to configure

Deploy Server

# Deploy server
cd server
vercel

# Add environment variables in Vercel dashboard
# GEMINI_API_KEY=your-key-here

Option 2: Railway

Deploy Full Stack

# Install Railway CLI
npm i -g @railway/cli

# Login and deploy
railway login
railway init
railway up

Option 3: Self-Hosted

Using Docker

# Dockerfile for server
FROM node:24-alpine
WORKDIR /app
COPY server/package*.json ./
RUN npm ci --only=production
COPY server/ .
EXPOSE 3080
CMD ["npm", "start"]

Using PM2

# Install PM2
npm i -g pm2

# Start server with PM2
cd server
pm2 start index.js --name echoai-server
pm2 startup
pm2 save

Environment Variables for Production

# Server
GEMINI_API_KEY=AIza-your-production-key
NODE_ENV=production
PORT=3080
CLIENT_URL=https://your-client-domain.com

# Client
VITE_SERVER_URL=https://your-server-domain.com

🤝 Contributing

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

Quick Contribution Guide

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and test them
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Development Setup

# Fork and clone
git clone https://github.com/droidbg/EchoAI.git
cd EchoAI

# Install dependencies
npm run install:all

# Start development servers
npm run dev

Code Style

Use TypeScript for all new code
Follow ESLint and Prettier configurations
Add JSDoc comments for complex functions
Write meaningful commit messages
Test your changes thoroughly

📄 License

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

🙏 Acknowledgments

Google for the Gemini models and the GenAI SDK
React Team for the excellent framework
Vercel for the deployment platform
All Contributors who help make EchoAI better

📞 Support

Documentation: GitHub Wiki
Issues: GitHub Issues
Discussions: GitHub Discussions
Security: Security Policy

Made with ❤️ by the EchoAI Contributors

⭐ Star us on GitHub • 🐛 Report Bug • 💡 Request Feature

Name		Name	Last commit message	Last commit date
Latest commit History 62 Commits
.github		.github
client		client
docs		docs
scripts		scripts
server		server
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
.talismanrc		.talismanrc
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
package-lock.json		package-lock.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation