docs: Completely overhaul README with Smart India Hackathon problem framing, new features, and unified setup commands

README.md

@@ -1,64 +1,112 @@
-# InnerVoice — AI Emotional Wellness Tracker
+<div align="center">
+  <img src="https://raw.githubusercontent.com/LonelyGuy12/InnerVoice/main/frontend/public/logo.png" alt="InnerVoice Logo" width="120" />
+  <h1>InnerVoice</h1>
+  <p><strong>AI-driven Emotional Wellness Tracker & Proactive Support Network</strong></p>
+</div>
 
-InnerVoice is a full-stack web application that allows users to record daily 60-second voice check-ins. The AI analyzes their voice to detect emotional signatures using acoustic features, tracking mental wellness trends over time.
+---
+
+## 🚀 The Problem
+
+*Problem Statement inspired by the Smart India Hackathon framework:*
+
+Mental health decline is often a silent trajectory. When individuals experience prolonged periods of stress or depression, their primary support networks—therapists, partners, and close friends—are completely disconnected from their day-to-day emotional state, forcing interventions to be reactive (during a crisis) rather than proactive.
+
+Furthermore, traditional written journaling causes high cognitive friction resulting in low adherence, and standard mood-tracking apps rely on subjective 1-to-10 sliders that fail to capture subconscious emotional exhaustion.
+
+## 💡 The Solution
+
+**InnerVoice** is a full-stack platform that completely removes the friction of self-reflection. Users simply speak their mind for 60 seconds into their device. 
+
+Instead of just parsing text, InnerVoice **listens**. It utilizes advanced, localized ML models (`wav2vec2`) to extract acoustic features (pitch, speech rate, energetic variance, conversational pauses) to uncover latent emotions. 
+
+Additionally, InnerVoice breaks the isolation of mental health struggles through its **Trusted Circle** architecture. The platform automatically broadcasts Weekly Emotional Trend Reports (synthesized by an LLM) to a pre-authenticated support system to facilitate early human intervention.
+
+---
+
+## 🔥 Key Features
 
-## Tech Stack
-- **Frontend**: Next.js 14, TailwindCSS, Recharts, Framer Motion
-- **Backend**: FastAPI, SQLAlchemy (SQLite/PostgreSQL)
-- **AI/ML**: `wav2vec2` (Emotion Classification), `librosa` (Acoustic Features), `OpenAI Whisper` (Transcription), `GPT-3.5` (Insights/Chat)
+1. **Zero-Friction Voice Journaling**
+   - Client-side recording with real-time waveform visualization.
+   - Immediate audio-to-text transcription powered by OpenAI Whisper.
 
-## Demo Mode
-The UI is fully connected and defaults to **Demo Mode**, meaning it uses 30 days of pre-generated realistic mock data. You can explore the Dashboard, Timeline, and Chat without running the backend or providing an API key. 
-To disable Demo Mode, click the "Demo Mode ON" button in the sidebar or edit `.env.local`.
+2. **Acoustic Acoustic Analysis**
+   - `librosa` extracts physiological distress markers: pitch deviation, energy (RMS), speech rate, and zero-crossing rate (pauses/filler words).
+   - Emotion classification via localized HuggingFace Models (`wav2vec2-lg-xlsr-en-speech-emotion-recognition`).
+
+3. **Trusted Circle Architecture (Brevo Integration)**
+   - Allow users to invite therapists or partners to their secure network. 
+   - Proactive broadcasting of LLM-synthesized Weekly Trend Reports directly to via automatic Transactional Emails using the Brevo API.
+   - Granular CRUD management of trusted members.
+
+4. **Multi-Factor Correlation & Contextual Engagement**
+   - **Sleep/Mood Correlation**: Visual and statistical mapping linking sleep deprivation securely to mood degradation.
+   - **Contextual Prompts**: AI reads your previous 5 entries to generate highly personalized daily journaling prompts specifically tailored to your emotional state.
+   - **Advanced Theming**: Fully responsive Dark/Light mode architecture.
+   - **Crisis Safety Net**: Local and international resources triggered automatically.
+
+---
+
+## 🛠️ Tech Stack
+
+- **Frontend**: Next.js 14, React context, TailwindCSS, Recharts, Framer Motion
+- **Backend**: FastAPI, SQLAlchemy, SQLite/PostgreSQL
+- **Communications**: Brevo Transactional Email REST API via `httpx`
+- **AI/ML**: `wav2vec2`, `librosa`, OpenRouter / OpenAI for generation
 
 ---
 
-## 🚀 Quick Start (Production/Live Mode)
+## ⚙️ Quick Start (Local Deployment)
 
-If you want to run the real AI pipeline locally:
+### 1. Backend Setup
 
-### 1. Backend Setup (FastAPI + AI Services)
 The backend requires Python 3.10+ and downloads ~1.5GB of ML models on first run.
+
 ```bash
 cd backend
 python3 -m venv venv
 source venv/bin/activate
 pip install -r requirements.txt
+```
+
+**Configuration**:
+Rename `.env.example` to `.env` and configure your API keys:
+```env
+OPENROUTER_API_KEY="your_ai_key"
+BREVO_API_KEY="your_brevo_api_key"
+BREVO_SENDER_EMAIL="your_brevo_verified_sender@email.com"
+```
 
-# Start the server (runs on http://localhost:8000)
-uvicorn main:app --reload
+**Run Server**:
+```bash
+python -m uvicorn main:app --reload
 ```
+*API runs locally at http://localhost:8000*
 
-*Note: For the AI Companion and Insights to work, rename `backend/.env.example` to `backend/.env` and add your `OPENAI_API_KEY`.*
+### 2. Frontend Setup
 
-### 2. Frontend Setup (Next.js)
 ```bash
 cd frontend
 npm install
 
-# Start the dev server (runs on http://localhost:3000)
+# Start the dev server 
 npm run dev
 ```
 
-Visit `http://localhost:3000` to start recording.
+*Visit `http://localhost:3000` to interact with InnerVoice!*
+
+### 3. Database Seeding (Testing Mode)
+If you want to test the multi-week timeline and Trusted Circle functionality without recording 30 days of real audio, you can seed the SQLite database with rich mock entries:
 
-### 3. Database Seeding (Optional)
-If you want to test the live backend but don't want to record 30 days of real audio first, you can seed the SQLite database with 30 days of realistic mock entries:
 ```bash
 cd backend
 source venv/bin/activate
 python seed_data.py
 ```
-This generates a user ID. Add that ID to `frontend/.env.local` as `NEXT_PUBLIC_DEMO_USER_ID`.
+This script generates a user ID. Add that ID to your `frontend/.env.local` as `NEXT_PUBLIC_DEMO_USER_ID` or simply browse in the generic UI Demo Mode.
 
 ---
 
-## Technical Features Implemented
-- **Web Audio API**: Client-side recording with real-time waveform visualization.
-- **Acoustic Extraction**: `librosa` extracts pitch, energy (RMS), tempo, pause duration, and zero-crossing rate (filler words).
-- **Emotion Inference**: HuggingFace `wav2vec2-lg-xlsr-en-speech-emotion-recognition` model lazy-loaded on the server.
-- **Trend Detection**: Week-over-week deviation analysis triggers alerts (e.g., "Mood declined 24%").
-- **State Injection Chat**: Custom GPT context window is injected with the last 30 days of voice metrics before the user asks a question, enabling personalized insights without fine-tuning.
+## 🔒 Privacy & Architecture
 
-## Privacy Note
-Audio files are converted in-memory and deleted immediately after the feature-extraction pipeline completes. We only store acoustic metrics (floats), the transcription, and the detected emotion.
+Audio files are converted in-memory within the backend ML pipeline and are **deleted securely and immediately** after the acoustic feature-extraction completes. We only permanently store quantified acoustic metrics (floats), the speech transcription string, and the categorical detected emotion.