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

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

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