An AI-powered emotional analysis chatbot that understands what's really behind your words.
Chat naturally. Get empathetic replies. See your emotional patterns visualized in real time.

---

✨ What is Behind Your Words?

Behind Your Words is a full-stack emotional wellness app that combines:

• 🤖 Gemini AI — empathetic, context-aware conversational replies
• 🧠 HuggingFace NLP — real-time sentiment & emotion detection on every message
• 📊 Live Dashboard — pie charts, trend lines, and emotional insights
• 🔒 Privacy-first — raw messages are never stored. Only daily aggregated summaries.
• 📄 PDF Reports — download your emotional journey as a beautifully formatted report

---

🎬 Features at a Glance

Feature	Description
💬 Smart Chat	Gemini-powered empathetic replies with strict emotional focus
🎭 Emotion Detection	Detects joy, sadness, anger, fear, love, surprise per message
📈 Sentiment Tracking	Positive / Neutral / Negative classification in real time
🗂️ Dashboard Panel	Slide-in panel with pie chart + trend line chart
📅 Date Range Filter	View emotional history across any date range
🔄 Daily Comparison	"You're X% happier than yesterday" motivational messages
📄 PDF Export	Download full emotional report with all historical data
🔐 Auth	Smart login — auto-detects new vs existing users
🌐 Guest Mode	Chat & see session stats without signing in
🔑 API Key Rotation	Auto-rotates through 13 Gemini keys to maximize uptime

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                     FRONTEND (React + Vite)                  │
│  ┌──────────┐  ┌──────────────┐  ┌───────────────────────┐  │
│  │ ChatPage │  │ DashboardPanel│  │    LoginModal         │  │
│  └────┬─────┘  └──────┬───────┘  └──────────┬────────────┘  │
│       │               │                      │               │
│  ┌────▼───────────────▼──────────────────────▼────────────┐  │
│  │           Zustand Store  +  Axios API Service           │  │
│  └────────────────────────┬───────────────────────────────┘  │
└───────────────────────────┼─────────────────────────────────┘
                            │ HTTP
┌───────────────────────────▼─────────────────────────────────┐
│                    BACKEND (FastAPI)                          │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────────┐  │
│  │ /chat       │  │ /save-daily  │  │ /report (PDF)      │  │
│  └──────┬──────┘  └──────┬───────┘  └────────┬───────────┘  │
│         │                │                    │               │
│  ┌──────▼──────┐  ┌──────▼───────────────────▼───────────┐  │
│  │ NLP Service │  │        Supabase Service Client        │  │
│  │ + Chatbot   │  │     (bypasses RLS for backend ops)    │  │
│  │   Service   │  └───────────────────────────────────────┘  │
│  └──────┬──────┘                                             │
└─────────┼───────────────────────────────────────────────────┘
          │
┌─────────▼───────────────────────────────────────────────────┐
│                    EXTERNAL SERVICES                          │
│   Google Gemini API  │  HuggingFace Models  │  Supabase DB   │
└─────────────────────────────────────────────────────────────┘

---

🚀 Quick Start

Prerequisites

• Python 3.11+
• Node.js 18+
• A Supabase project
• A Google AI Studio API key

1. Clone & Setup

git clone https://github.com/yourusername/behind-your-words.git
cd behind-your-words

2. Backend Setup

cd backend
pip install -r requirements.txt
cp .env.example .env
# Fill in your keys in .env

backend/.env

GEMINI_API_KEY=your_gemini_key_here
GEMINI_API_KEYS_EXTRA=key2,key3,key4   # optional — for key rotation
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your_anon_key
SUPABASE_SERVICE_KEY=your_service_role_key

3. Frontend Setup

cd frontend
npm install
cp .env.example .env
# Fill in your Supabase keys

frontend/.env

VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your_anon_key
VITE_API_BASE_URL=http://localhost:8000

4. Supabase Database

Run this in your Supabase SQL Editor:

CREATE TABLE daily_emotions (
  id              uuid DEFAULT gen_random_uuid() PRIMARY KEY,
  user_id         uuid REFERENCES auth.users(id) ON DELETE CASCADE,
  date            date NOT NULL,
  happy_percent   numeric(5,2) DEFAULT 0,
  sad_percent     numeric(5,2) DEFAULT 0,
  neutral_percent numeric(5,2) DEFAULT 0,
  top_emotions    jsonb DEFAULT '[]',
  UNIQUE(user_id, date)
);

ALTER TABLE daily_emotions ENABLE ROW LEVEL SECURITY;

5. Launch 🚀

# Windows — just double-click or run:
start.bat

# Manual:
# Terminal 1
cd backend && python -m uvicorn app.main:app --reload --port 8000

# Terminal 2
cd frontend && npm run dev

Open http://localhost:5173 🎉

---

🧠 How It Works

User types a message
        │
        ▼
┌───────────────────────────────────────┐
│  FastAPI /chat endpoint               │
│                                       │
│  ┌─────────────────┐  ┌────────────┐  │
│  │  Gemini AI      │  │ NLP Models │  │
│  │  (reply)        │  │ (emotion + │  │
│  │                 │  │ sentiment) │  │
│  └────────┬────────┘  └─────┬──────┘  │
│           └────────┬────────┘         │
│                    ▼                  │
│         { reply, sentiment, emotion } │
└───────────────────────────────────────┘
        │
        ▼
Frontend stores in Zustand (in-memory)
        │
        ▼
Dashboard reads from same store → live charts
        │
        ▼
On dashboard open → saves to Supabase daily_emotions
        │
        ▼
PDF report fetches from Supabase → full history

---

📁 Project Structure

behind-your-words/
├── 🐍 backend/
│   ├── app/
│   │   ├── api/          # chat, auth, analysis routes
│   │   ├── services/     # chatbot (Gemini) + nlp (HuggingFace)
│   │   ├── schemas/      # Pydantic models
│   │   ├── core/         # config (env vars)
│   │   └── db/           # Supabase client
│   ├── tests/            # pytest + Hypothesis property tests
│   └── requirements.txt
│
├── ⚛️  frontend/
│   └── src/
│       ├── components/   # ChatWindow, DashboardPanel, LoginModal, Navbar
│       ├── pages/        # ChatPage
│       ├── services/     # api.js, supabaseClient.js
│       ├── store/        # Zustand chatStore
│       └── utils/        # formatters.js
│
└── 🚀 start.bat          # One-click launcher (Windows)

---

🧪 Testing

# Backend — property-based tests with Hypothesis
cd backend
pytest tests/ -v

# Frontend — Vitest + Testing Library
cd frontend
npm test

Test coverage includes:

• Property 1: NLP always returns valid classifications
• Property 2: Daily percentages are bounded [0, 100]
• Property 3: Upsert idempotency (one row per user per day)
• Property 4 & 5: Comparison message correctness
• Property 6: PDF contains required fields
• Property 7: Chat response schema completeness

---

🔐 Privacy & Security

• ✅ Raw chat messages are never stored in any database
• ✅ Only daily aggregated summaries (percentages + emotion counts) are saved
• ✅ Row Level Security (RLS) on Supabase — users can only access their own data
• ✅ JWT authentication on all protected endpoints
• ✅ All secrets loaded from environment variables — nothing hardcoded

---

🛠️ Tech Stack

Layer	Technology
Frontend	React 18, Vite, Tailwind CSS, Recharts, Zustand, Axios
Backend	FastAPI, Python 3.11, Uvicorn
AI / NLP	Google Gemini 2.5 Flash, HuggingFace Transformers
Database	Supabase (PostgreSQL + Auth)
PDF	ReportLab
Testing	pytest, Hypothesis, Vitest, fast-check

---

📄 License

MIT © 2026 Behind Your Words

---

"Every word you share carries a feeling. I'm here to understand it."