# Pulse Point

**Real-time Customer Feedback & Happiness Intelligence Platform for T-Mobile**

A modern, AI-powered customer feedback system that helps T-Mobile identify issues early, measure satisfaction, and reward engaged customers through gamification.

## 🎯 Overview

Pulse Point is an intelligent customer experience platform that captures real-time feedback, analyzes sentiment with AI, and provides actionable insights. Built with enterprise scalability and user engagement at its core.

## ✨ Key Features

### 📊 **Intelligence Dashboard**
- Real-time happiness score (defaults to 100 for satisfied customers)
- Comprehensive sentiment distribution charts
- Average ratings and response analytics
- Visual data representation with animated charts

### 🐛 **Issue Reporting System**
- 8 issue categories (Network, Billing, Service, etc.)
- Priority levels (Low, Medium, High, Critical)
- Direct-to-team escalation
- Early problem detection before escalation

### 🎮 **Gamification Engine**
- Points system for engagement
- Badges and achievements
- Quest challenges
- Spin-to-win rewards
- Leaderboards

### 🤖 **AI-Powered Analysis**
- Google Gemini API for sentiment detection
- Real-time feedback classification
- Automated insights generation
- Predictive analytics

### 🔐 **Secure Authentication**
- Auth0 integration
- User profile management
- Activity tracking
- Personalized experience

## 🏗️ Architecture

```
Frontend (React 19 + Vite)
    ↓
Auth0 (Authentication)
    ↓
Firebase (Realtime Database)
    ↓
AI Pipeline (Google Gemini)
    ↓
Real-time Analytics Dashboard
```

## 🚀 Quick Start

### 1. Install Dependencies

```bash
npm install
```

### 2. Configure Environment

Create `.env.local` with your credentials:

```env
# Firebase Configuration
VITE_FIREBASE_API_KEY=your_key
VITE_FIREBASE_AUTH_DOMAIN=your_domain
VITE_FIREBASE_DATABASE_URL=your_url
VITE_FIREBASE_PROJECT_ID=your_project_id
VITE_FIREBASE_STORAGE_BUCKET=your_bucket
VITE_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
VITE_FIREBASE_APP_ID=your_app_id

# Auth0 Configuration
VITE_AUTH0_DOMAIN=your_domain.auth0.com
VITE_AUTH0_CLIENT_ID=your_client_id
VITE_AUTH0_REDIRECT_URI=http://localhost:5173/callback

# AI Services
VITE_GEMINI_API_KEY=your_gemini_key
```

### 3. Run Development Server

```bash
npm run dev
```

Navigate to `http://localhost:5173`

## 📚 Documentation

- **[AUTH0_INTEGRATION.md](./docs/AUTH0_INTEGRATION.md)** - Complete Auth0 setup guide
- **[AUTH0_SETUP.md](./docs/AUTH0_SETUP.md)** - Quick Auth0 configuration
- **[ARCHITECTURE.md](./ARCHITECTURE.md)** - System design and data flow
- **[UI_ENHANCEMENTS.md](./UI_ENHANCEMENTS.md)** - Design system documentation

## 🛠️ Tech Stack

### Frontend
- **React 19** - Latest React with concurrent features
- **Vite** - Lightning-fast build tool
- **Custom CSS** - Design system with CSS variables
- **React Hot Toast** - Beautiful notifications

### Backend & Services
- **Firebase Realtime Database** - Real-time data sync
- **Auth0** - Enterprise authentication
- **Google Gemini AI** - Advanced sentiment analysis

### Features
- **Dark/Light Mode** - Full theme support
- **Responsive Design** - Mobile-first approach
- **Real-time Updates** - Live data synchronization
- **Gamification** - Engagement mechanics

## 📊 Project Structure

```
src/
├── components/
│   ├── AIAssistant.jsx          # AI chat interface
│   ├── HappinessDashboard.jsx   # Analytics dashboard
│   ├── IssueReporter.jsx        # Issue reporting form
│   ├── Quests.jsx               # Gamification quests
│   ├── Profile.jsx              # User profiles
│   ├── Leaderboard.jsx          # Rankings
│   ├── SpinWheel.jsx            # Rewards system
│   ├── UserMenu.jsx             # User dropdown
│   ├── ThemeToggle.jsx          # Dark/light mode
│   ├── AuthenticationGuard.jsx  # Route protection
│   ├── LoginButton.jsx          # Auth0 login
│   └── LogoutButton.jsx         # Auth0 logout
├── services/
│   ├── firebase.js              # Firebase config
│   ├── gemini.js                # AI integration
│   ├── gamification.js          # Points & badges
│   └── feedbackPipeline.js      # Feedback processing
├── hooks/
│   └── useTheme.js              # Theme management
└── styles/                      # Component styles
```

## 🎯 Core Features Breakdown

### 1. Happiness Intelligence
- Measures customer satisfaction in real-time
- Defaults to 100 (happy) and adjusts based on feedback
- Visual sentiment distribution charts
- Trending analysis

### 2. Early Issue Detection
- Customers report problems directly
- Categorized and prioritized automatically
- Rewards users for proactive reporting (25 points)
- Prevents small issues from becoming major problems

### 3. Engagement & Retention
- Point-based reward system
- Achievement badges
- Daily streaks
- Spin-to-win prizes
- Community leaderboards

## 📈 Key Metrics

- **Happiness Score**: 0-100 scale (defaults to 100)
- **Response Rate**: Track customer engagement
- **Issue Resolution**: Monitor problem-solving speed
- **User Retention**: Gamification impact on loyalty
- **Sentiment Trends**: Track satisfaction over time

## 🚀 Deployment

### Build for Production
```bash
npm run build
```

### Deploy to Vercel
```bash
npm install -g vercel
vercel --prod
```

## 🎨 Design System

- **Primary Color**: Magenta (#e91e63)
- **Theme Support**: Dark & Light modes
- **Typography**: System fonts with custom scaling
- **Animations**: Smooth transitions and micro-interactions
- **Accessibility**: WCAG AA compliant

## 📱 Progressive Web App (Future)

- Offline support
- Push notifications
- App-like experience
- Home screen installation

## 📄 License

MIT License - Built for T-Mobile

## 🤝 Contributing

This is a proprietary T-Mobile project. For internal contributions, please follow the company's development guidelines.

---

**Pulse Point** - Taking the pulse of customer satisfaction, one feedback at a time. 💓

*Built with modern web technologies for enterprise-scale customer engagement.*