PROJECT_README.md

# FaceVision AI 🧠

A real-time facial expression recognition web app powered by **MediaPipe Face Landmarker** running fully in-browser (WASM), with a **FastAPI** backend for logging emotion data to a **Neon PostgreSQL** database.

---

## Project Structure

```
FACE RECOGNIZATION/
├── frontend/          # Next.js App Router + Tailwind CSS
│   ├── app/
│   │   ├── hooks/
│   │   │   ├── useFaceTracking.ts   # MediaPipe integration & emotion classification
│   │   │   └── useEmotionLogger.ts  # 10s window logging to backend
│   │   ├── components/
│   │   │   ├── EmotionDisplay.tsx
│   │   │   └── StatsPanel.tsx
│   │   ├── FaceVisionApp.tsx        # Main client component
│   │   ├── page.tsx
│   │   └── globals.css
│   └── .env.local                   # NEXT_PUBLIC_BACKEND_URL
│
└── backend/           # FastAPI + SQLAlchemy
    ├── app/
    │   ├── main.py       # FastAPI app, CORS, endpoints
    │   ├── database.py   # SQLAlchemy engine + session
    │   ├── models.py     # EmotionLog ORM model
    │   └── schemas.py    # Pydantic schemas
    ├── requirements.txt
    ├── run.py            # Start with: python run.py
    └── .env.example      # Copy to .env and fill DATABASE_URL
```

---

## Getting Started

### 1. Backend Setup

```bash
cd backend

# Create virtual environment
python -m venv venv
venv\Scripts\activate          # Windows
# source venv/bin/activate     # macOS/Linux

# Install dependencies
pip install -r requirements.txt

# Configure database
copy .env.example .env
# Edit .env → set DATABASE_URL to your Neon PostgreSQL connection string

# Start the server
python run.py
# → http://localhost:8000
# → Swagger UI: http://localhost:8000/docs
```

### 2. Frontend Setup

```bash
cd frontend

# Install dependencies (already done if you just cloned)
npm install

# Start development server
npm run dev
# → http://localhost:3000
```

---

## Environment Variables

### Frontend (`frontend/.env.local`)
```
NEXT_PUBLIC_BACKEND_URL=http://localhost:8000
```

### Backend (`backend/.env`)
```
DATABASE_URL=postgresql://user:password@your-neon-host.neon.tech/facerecog?sslmode=require
```

---

## How It Works

1. **Camera** – `react-webcam` accesses your device camera at up to 60 FPS.
2. **AI Model** – MediaPipe Face Landmarker WASM model is downloaded from CDN and runs entirely in the browser.
3. **Classification** – 8 key blendshapes are scored to classify: **Happy, Sad, Angry, Surprised, Neutral**.
4. **Smoothing** – A 5-frame moving average prevents rapid flickering.
5. **Logging** – Every 10 seconds, the mode emotion is POSTed to the backend without blocking the video loop.
6. **Database** – FastAPI saves logs to Neon PostgreSQL via SQLAlchemy.

---

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/` | Health check |
| POST | `/api/logs` | Log emotion entry |
| GET | `/api/logs` | List all logs |
| DELETE | `/api/logs` | Clear all logs |

Interactive docs at: `http://localhost:8000/docs`