{"id":51060269,"url":"https://github.com/abhirajthakur/facewatch","last_synced_at":"2026-06-23T01:30:23.729Z","repository":{"id":356758983,"uuid":"1233940010","full_name":"abhirajthakur/facewatch","owner":"abhirajthakur","description":"Real-time face detection streaming platform built with FastAPI, React, WebSockets, PostgreSQL, Docker, and dlib — without OpenCV.","archived":false,"fork":false,"pushed_at":"2026-05-09T15:29:40.000Z","size":143,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-09T17:27:39.426Z","etag":null,"topics":["alembic-migration","fastapi","python","reactjs","websockets"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/abhirajthakur.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-09T14:42:42.000Z","updated_at":"2026-05-09T15:29:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/abhirajthakur/facewatch","commit_stats":null,"previous_names":["abhirajthakur/facewatch"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/abhirajthakur/facewatch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abhirajthakur%2Ffacewatch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abhirajthakur%2Ffacewatch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abhirajthakur%2Ffacewatch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abhirajthakur%2Ffacewatch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/abhirajthakur","download_url":"https://codeload.github.com/abhirajthakur/facewatch/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abhirajthakur%2Ffacewatch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34672250,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-22T02:00:06.391Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alembic-migration","fastapi","python","reactjs","websockets"],"created_at":"2026-06-23T01:30:23.213Z","updated_at":"2026-06-23T01:30:23.723Z","avatar_url":"https://github.com/abhirajthakur.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FaceWatch\n\nReal-time face detection and ROI (Region of Interest) streaming platform built with FastAPI, React, WebSockets, PostgreSQL, Docker, and dlib.\n\nFaceWatch captures live webcam frames from the browser, streams them to a FastAPI backend over WebSockets, performs face detection in real-time, stores ROI metadata in PostgreSQL, draws bounding boxes without OpenCV, and streams processed frames back to the frontend.\n\n# Demo\n\nhttps://github.com/user-attachments/assets/f902b220-67b0-48ce-ba13-2601e12607fa\n\n# Features\n\n- Real-time webcam streaming\n- Face detection using dlib\n- ROI (Region of Interest) bounding box rendering without OpenCV\n- WebSocket-based low-latency communication\n- Dockerized full-stack architecture\n- Automatic Alembic migrations on container startup\n- Environment-based configuration\n\n# Tech Stack\n\n## Backend\n\n- Python 3.11\n- FastAPI\n- SQLAlchemy\n- Alembic\n- PostgreSQL\n- dlib\n- Pillow\n- uv\n- WebSockets\n\n## Frontend\n\n- React\n- TypeScript\n- Vite\n\n## Infrastructure\n\n- Docker\n- Docker Compose\n- Nginx\n\n# Architecture\n\n```text\n    ┌──────────────┐\n    │   Browser    │\n    │ React + TS   │\n    └──────┬───────┘\n           │\n           │ (1) webcam frames via WebSocket\n           ▼\n┌──────────────────────────┐\n│      FastAPI Backend     │\n│  WebSocket + REST APIs   │\n└──────────┬───────────────┘\n           │\n           │ (2) decode JPEG frames\n           ▼\n┌──────────────────────────┐\n│   Face Detection Layer   │\n│   dlib + Pillow Drawing  │\n└──────────┬───────────────┘\n           │\n           │ (3) persist ROI metadata\n           ▼\n┌──────────────────────────┐\n│       PostgreSQL         │\n│      ROI Persistence     │\n└──────────┬───────────────┘\n           │\n           │ (4) latest ROI/frame retrieval\n           ▼\n┌──────────────────────────┐\n│      REST Endpoints:     │\n│     /api/frame/process   │\n│     /api/video/latest    │\n│     /api/roi/latest      │\n└──────────────────────────┘\n\n\nContainerized Deployment\n\n┌──────────────────────────────────────────────────────┐\n│                   Docker Compose                     │\n│                                                      │\n│  ┌─────────────┐   ┌─────────────┐   ┌────────────┐  │\n│  │  Frontend   │   │   Backend   │   │ PostgreSQL │  │\n│  │    Nginx    │   │   FastAPI   │   │     DB     │  │\n│  └─────────────┘   └─────────────┘   └────────────┘  │\n│                                                      │\n└──────────────────────────────────────────────────────┘\n```\n\n# API Endpoints\n\n## WebSocket\n\n### `WS /ws/video`\n\nPrimary real-time streaming endpoint.\n\nAccepts:\n\n- live webcam frames\n\nReturns:\n\n- processed frame\n- ROI metadata\n\n## REST Endpoints\n\n### `POST /api/frame/process`\n\nAccepts a single image frame upload and returns:\n\n- processed frame\n- ROI metadata\n\nThis endpoint exists to satisfy the explicit API ingestion requirement independently from the WebSocket transport layer.\n\n### `GET /api/video/latest`\n\nReturns the latest processed video frame.\n\n### `GET /api/roi/latest`\n\nReturns the latest detected ROI metadata.\n\n### `GET /health`\n\nHealth check endpoint.\n\n# Project Structure\n\n```text\nfacewatch/\n├── backend/\n│   ├── app/\n│   ├── alembic/\n│   ├── Dockerfile\n│   └── pyproject.toml\n├── frontend/\n│   ├── src/\n│   ├── Dockerfile\n│   └── package.json\n└── docker-compose.yml\n```\n\n\n# Getting Started\n\n## Run with Docker\n\n### Prerequisites\n\n- Docker\n- Docker Compose\n\n### Run the Application\n\n```bash\nDOCKER_BUILDKIT=1 docker-compose up --build\n```\n\nFrontend:\n\n```text\nhttp://localhost:5173\n```\n\nBackend:\n\n```text\nhttp://localhost:8000\n```\n\nSwagger Docs:\n\n```text\nhttp://localhost:8000/docs\n```\n\n## Environment Variables\n\n### Backend\n\n```env\nDEBUG=true\nFRONTEND_URL=http://localhost:5173\nDATABASE_URL=postgresql+asyncpg://postgres:postgres@postgres:5432/facewatch\nSYNC_DATABASE_URL=postgresql://postgres:postgres@postgres:5432/facewatch\n```\n\n## Run Without Docker\n\n### Prerequisites\n\n- Python 3.11\n- PostgreSQL\n- uv\n- Node.js 20+\n\n## Backend Setup\n\n### Navigate to Backend\n\n```bash\ncd backend\n```\n\n### Install Dependencies\n\n```bash\nuv sync\n```\n\n### Configure Environment Variables\n\nCreate:\n\n```text\nbackend/.env\n```\n\n```env\nDEBUG=true\nFRONTEND_URL=http://localhost:5173\nDATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/facewatch\nSYNC_DATABASE_URL=postgresql://postgres:postgres@localhost:5432/facewatch\n```\n\n### Run Database Migrations\n\n```bash\nuv run alembic upgrade head\n```\n\n### Start Backend Server\n\n```bash\nuv run uvicorn app.main:app --reload\n```\n\nBackend will run on:\n\n```text\nhttp://localhost:8000\n```\n\n## Frontend Setup\n\n### Navigate to Frontend\n\n```bash\ncd frontend\n```\n\n### Install Dependencies\n\n```bash\nnpm install\n```\n\n### Configure Environment Variables\n\nCreate:\n\n```text\nfrontend/.env\n```\n\n```env\nVITE_WS_URL=ws://localhost:8000/ws/video\n```\n\n### Start Frontend\n\n```bash\nnpm run dev\n```\n\nFrontend will run on:\n\n```text\nhttp://localhost:5173\n```\n\n\n# Design Decisions\n\n## Why dlib?\n\ndlib provides:\n\n- lightweight face detection\n- CPU-only inference\n- easy containerization\n- no OpenCV dependency\n\n## Why Pillow Instead of OpenCV?\n\nThe assignment explicitly prohibited OpenCV.\n\nPillow was used to:\n\n- render bounding boxes\n- manipulate image frames\n- encode/decode JPEG frames\n\nwithout introducing unnecessary complexity.\n\n# Expectations / Notes\n\n## dlib Build Time\n\nThe first Docker build may take several minutes because:\n\n- dlib contains native C++ extensions\n- compilation occurs during dependency installation\n\nSubsequent builds are significantly faster due to Docker layer caching.\n\n## Webcam Permissions\n\nThe browser will request webcam access permission when the frontend loads.\nThe application will not function correctly unless webcam access is granted.\n\n## Lighting Conditions\n\nThe dlib frontal face detector performs best under:\n\n- reasonable lighting\n- frontal face orientation\n- moderate image contrast\n\nVery poor lighting conditions may reduce detection reliability.\n\n# Database Migrations\n\nAlembic migrations run automatically during backend container startup.\n\nNo manual migration step is required.\n\n# AI Usage Disclosure\n\nAI-assisted development tools were used during implementation for:\n\n- architecture planning\n- debugging assistance\n- Docker optimization\n- frontend structure guidance\n- documentation refinement\n\nAll generated code was manually reviewed, modified, tested, and integrated into the final solution.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabhirajthakur%2Ffacewatch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabhirajthakur%2Ffacewatch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabhirajthakur%2Ffacewatch/lists"}