FreeTalk — AI Companion Chatbot with Admin Dashboard

A full-stack conversational AI application built with React, FastAPI, Groq API, and Redis. Includes a companion chatbot frontend and an admin dashboard to view all user conversations and metadata.

🚀 Live Demo

Frontend: freetalk.imranansari.in
API Docs: api.freetalk.imranansari.in/docs

🎯 Features

User App (Frontend)

💬 Real-time chat with Groq API-powered LLM
🌍 Multi-language support — Hindi, English, Hinglish
👥 Dynamic companion persona — Priya (for male users) / Imran (for female users)
📱 Device detection — tracks device name per user
💾 Full chat history — stored in Redis, persists across sessions
🧠 Configurable AI model — model specified via .env (default: Groq's open-source 120B)
🎨 Beautiful dark UI — rose/purple accent theme

Admin Dashboard (Separate App)

🛡️ Secure login — HTTP Basic Auth with credentials from .env
👥 User management — browse all users with metadata
💬 Full chat history — view complete conversation for any user
📊 User metadata — device name, gender, message count, first/last seen timestamps
🔍 Search & filter — find users by ID, device, or gender

📋 Project Structure

freetalk-v2/
├── backend/                 # FastAPI server
│   ├── main.py             # Core API + admin routes
│   ├── requirements.txt
│   └── .env.example
├── frontend/               # User chat app (React + Vite)
│   ├── src/
│   │   ├── App.jsx         # Main app logic
│   │   ├── components/     # Chat, header, input, welcome
│   │   ├── utils/api.js    # API client
│   │   └── App.css         # Dark theme styles
│   ├── index.html
│   ├── package.json
│   └── vite.config.js
└── admin/                  # Admin dashboard (React + Vite)
    ├── src/
    │   ├── App.jsx         # Auth + dashboard router
    │   ├── Login.jsx       # Login page
    │   ├── Dashboard.jsx   # Main admin UI
    │   ├── UserList.jsx    # User list sidebar
    │   ├── ChatView.jsx    # Chat history viewer
    │   ├── admin.css
    │   └── main.jsx
    ├── index.html
    ├── package.json
    └── vite.config.js

🚀 Setup

Prerequisites

Groq API key (get one from console.groq.com)
Redis running on localhost:6379
Node.js 16+ and Python 3.8+

Step 1: Backend Setup

cd backend

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install dependencies
pip install -r requirements.txt

# Copy and edit .env
cp .env.example .env
# Set ADMIN_USERNAME, ADMIN_PASSWORD, GROQ_API_KEY, and GROQ_DEFAULT_MODEL

# Run server
uvicorn main:app --reload --port 8000

Backend will be live at: http://localhost:8000

Step 2: Frontend Setup (User App)

cd frontend

# Install dependencies
npm install

# Run dev server
npm run dev

Frontend will be live at: http://localhost:5173

Step 3: Admin Dashboard Setup

cd admin

# Install dependencies
npm install

# Run dev server (runs on port 5174)
npm run dev

Admin dashboard will be live at: http://localhost:5174

🔧 Configuration

Backend (.env)

REDIS_HOST=localhost
REDIS_PORT=6379
ADMIN_USERNAME=admin
ADMIN_PASSWORD=your_strong_password_here
GROQ_API_BASE_URL=https://api.groq.com/openai
GROQ_API_KEY=your_groq_api_key_here
GROQ_DEFAULT_MODEL=openai/gpt-oss-120b
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5174

Environment Variables

REDIS_HOST — Redis hostname (default: localhost)
REDIS_PORT — Redis port (default: 6379)
ADMIN_USERNAME — Admin login username
ADMIN_PASSWORD — Admin login password
GROQ_API_BASE_URL — Groq API base URL (default: https://api.groq.com/openai)
GROQ_API_KEY — Your Groq API key (required)
GROQ_DEFAULT_MODEL — Model to use for chat (default: openai/gpt-oss-120b)
ALLOWED_ORIGINS — Comma-separated CORS origins

💬 How It Works

User Flow

First visit — User generates unique ID (stored in localStorage)
Send message — App detects device name automatically
Gender detection — API extracts gender from first messages
Persona assignment:
- Male user → Companion name shows as "Priya"
- Female user → Companion name shows as "Imran"
- Other → Shows "FreeTalk"
Full history stored — All messages saved in Redis with 30-day TTL
Clear chat — Removes local data + generates new user ID (no API call)

Admin Flow

Login — HTTP Basic Auth with credentials from .env
See all users — Lists users with metadata (device, gender, message count)
View history — Click any user to see full chat conversation
Filter/search — Search by user ID, device name, or gender

📡 API Endpoints

Chat Endpoints

POST /chat/{user_id} — Send message (with device_name in body)
GET /history/{user_id} — Fetch chat history
DELETE /history/{user_id} — Clear history (API kept, but frontend doesn't call it)
GET /models — List available models

Admin Endpoints (HTTP Basic Auth)

GET /admin/users — List all users with metadata
GET /admin/users/{user_id}/history — Get full chat history for a user

Health

GET /health — Check API, Redis, and Groq connectivity

🗄️ Redis Key Structure

chat:history:{user_id}     → [messages...]              (TTL: 30 days)
chat:meta:{user_id}        → {device_name, first_seen, last_seen, ...}
gender:{user_id}           → "male" | "female" | "other"
freetalk:users             → Set of all user_ids

🎨 Styling

Both apps use a dark theme with rose/purple accents:

Color Variables:

Background: #0f0f13
Surface: #1a1a24
Accent (Priya): #c2678a (rose)
Accent (Arjun): #7c6af7 (purple)
Text: #e8e8f0

Fully responsive — works on desktop, tablet, mobile.

🧠 Models

Backend uses Groq API models. The model is configured via GROQ_DEFAULT_MODEL in .env:

Recommended models:

openai/gpt-oss-120b — Powerful open-source model (default)
mixtral-8x7b-32768 — Fast and efficient
llama2-70b-4096 — High quality responses

View all available Groq models at console.groq.com.

🔐 Security

Admin login — HTTP Basic Auth (use HTTPS in production!)
User IDs — Random, non-sequential
No passwords stored — Credentials in .env only
Conversation privacy — Full history in Redis, admin-only access

For production:

Use HTTPS/TLS
Add rate limiting
Implement JWT or OAuth for admin
Use environment variables from a secrets manager

🛑 Clear Chat Behavior

When user clicks "Clear":

✅ Removes all localStorage data
✅ Generates new user ID
✅ Does NOT call delete API (history remains in Redis for admin)
✅ Starts fresh conversation

📊 Admin Dashboard Features

User List

Sort by last seen (most recent first)
See device type (iPhone, Android, Windows PC, Mac, etc.)
Message count per user
First and last seen timestamps
Gender indicator

Chat View

Full conversation history
Timestamps for each message (if available)
User vs bot messages clearly marked
User metadata (device, gender, first/last seen)

🚨 Troubleshooting

Groq API not responding

Verify GROQ_API_KEY is set correctly in .env
Check your Groq API key has not expired on console.groq.com
Ensure GROQ_DEFAULT_MODEL exists and is available in your Groq account
Check backend logs for connectivity errors

Redis connection failed

# Check Redis is running
redis-cli ping
# Should return: PONG

# If not installed:
sudo systemctl start redis  # Linux
brew services start redis   # macOS

Admin login fails

Verify ADMIN_USERNAME and ADMIN_PASSWORD in .env
Check backend is running on port 8000
Clear browser auth cache (open dev tools → Network tab)

Frontend can't connect to backend

Check backend runs on http://localhost:8000
Verify CORS is enabled (should be by default)
Check .env in frontend/admin for correct VITE_API_URL

📝 Notes

Chat history is never deleted from Redis, only when admin explicitly uses DELETE API
User IDs are persistent — same ID = same user across sessions
Model is set via GROQ_DEFAULT_MODEL in .env at startup (not dynamically changeable)
Admin dashboard is separate app on port 5174 to keep concerns clean
Previously used Ollama for local model inference, but switched to Groq API for better performance and reliability

🎓 Learning Outcomes

This project demonstrates:

Full-stack development (React + FastAPI)
Real-time streaming (SSE)
Multi-language NLP prompt engineering
Redis for session management
Admin authentication and authorization
Responsive UI design

📄 License

MIT — Free to use and modify.

Built with ❤️ using React, FastAPI, Groq API, and Redis

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
admin		admin
backend		backend
frontend		frontend
README.md		README.md
docker-compose.yml		docker-compose.yml
makefile		makefile

Latest commit

History

Folders and files

Repository files navigation