From 470074cbbbb192c4960a840b94431d583ae493a3 Mon Sep 17 00:00:00 2001
From: Ivan-Wang-tech <157322972+Ivan-Wang-tech@users.noreply.github.com>
Date: Wed, 19 Nov 2025 02:49:09 -0500
Subject: [PATCH] finalize readme.md

---
 README.md          | 346 +++++++++++++++++++++++++++++++--------------
 docker-compose.yml |   2 +-
 2 files changed, 243 insertions(+), 105 deletions(-)

diff --git a/README.md b/README.md
index 2c7cc203..3820217a 100644
--- a/README.md
+++ b/README.md
@@ -1,52 +1,82 @@
+# ✋ HandSense — Containerized Machine Learning + Web Dashboard System
+
+![ML Client CI](https://github.com/swe-students-fall2025/4-containers-nov/actions/workflows/ml-client-ci.yml/badge.svg)
+![Web App CI](https://github.com/swe-students-fall2025/4-containers-nov/actions/workflows/web-app-ci.yml/badge.svg)
 ![Lint-free](https://github.com/nyu-software-engineering/containerized-app-exercise/actions/workflows/lint.yml/badge.svg)
 
-# Containerized App Exercise
+A fully containerized, three-service application that performs **real-time hand gesture recognition** using a MediaPipe + PyTorch machine-learning client, stores gesture events inside **MongoDB**, and visualizes them through a **Flask-based web dashboard**.
 
-Build a containerized app that uses machine learning. See [instructions](./instructions.md) for details.
+This project demonstrates how separate services communicate inside a Dockerized micro-service architecture.
 
-# Teammates
+---
 
-Ivan Wang, [Harrison Gao](https://github.com/HTK-G), [Sina Liu](https://github.com/SinaL0123), Serena, [Hanqi Gui](https://github.com/hanqigui)
+## 👥 Teammates
 
-# Machine Learning Client — Hand Gesture Recognition
+- [Ivan Wang](https://github.com/Ivan-Wang-tech)  
+- [Harrison Gao](https://github.com/HTK-G)  
+- [Sina Liu](https://github.com/SinaL0123)  
+- [Serena Wang](https://github.com/serena0615)  
+- [Hanqi Gui](https://github.com/hanqigui)
 
-This folder contains the **machine-learning-client** subsystem of our 3-container project:
+---
 
-- **Machine Learning Client** → collects sensor data (webcam), performs gesture recognition with MediaPipe + PyTorch, and later sends results to MongoDB.
-- **Web App** → visualizes gesture events stored in the database.
-- **MongoDB** → central datastore for gesture metadata.
+## 🧱 System Overview
 
-The ML client runs entirely as a _backend service_ (no user-facing UI).  
-It processes camera input, performs ML inference, and will later communicate with the database once integrated with the web app.
+The system consists of **three Dockerized services**:
 
----
+```
++------------------------+     +-----------------------+     +------------------------+
+|   Machine Learning     |     |       MongoDB         |     |       Web App          |
+|       Client           | --> |   handsense database  | --> |   Dashboard (Flask)    |
+| (MediaPipe + PyTorch)  |     |     Gesture_events    |     |   Visualize gestures   |
++------------------------+     +-----------------------+     +------------------------+
+```
+
+### 🔹 Machine-Learning Client  
+Runs locally or inside Docker.  
+It uses a webcam → detects hands using MediaPipe → predicts gestures using a PyTorch MLP → inserts events into `handsense.gesture_events` collection.
+
+### 🔹 MongoDB  
+Stores gesture logs, statistics, and capture state toggles.
 
-# 1. Project Structure
+### 🔹 Web App  
+Reads gesture events from MongoDB and presents a dashboard showing:
 
-## Project Structure
+- Live latest gesture  
+- Gesture distribution  
+- Recent event timeline  
+- Toggle capture control (`/api/control`)
+
+After all services run, you can visit:
+
+👉 **http://localhost:5000**
+
+---
+
+## 📁 Project Structure
 
 ```text
 ├── docker-compose.yml
 ├── instructions.md
 ├── LICENSE
 ├── machine-learning-client
-│   ├── data
-│   │   ├── hagrid_keypoints_X.npy
-│   │   └── hagrid_keypoints_y.npy
-│   ├── Dockerfile
-│   ├── models
-│   │   ├── gesture_mlp.pt
-│   │   └── train_mlp.py
-│   ├── Pipfile
-│   ├── Pipfile.lock
-│   ├── src
-│   │   ├── __init__.py
-│   │   ├── extract_keypoints_from_hagrid.py
-│   │   └── live_mediapipe_mlp.py
-│   └── tests
-│       ├── __init__.py
-│       ├── test_extract_keypoints_from_hagrid.py
-│       └── test_live_mediapipe_mlp.py
+│   ├── data
+│   │   ├── hagrid_keypoints_X.npy
+│   │   └── hagrid_keypoints_y.npy
+│   ├── Dockerfile
+│   ├── models
+│   │   ├── gesture_mlp.pt
+│   │   └── train_mlp.py
+│   ├── Pipfile
+│   ├── Pipfile.lock
+│   ├── src
+│   │   ├── __init__.py
+│   │   ├── extract_keypoints_from_hagrid.py
+│   │   └── live_mediapipe_mlp.py
+│   └── tests
+│       ├── __init__.py
+│       ├── test_extract_keypoints_from_hagrid.py
+│       └── test_live_mediapipe_mlp.py
 ├── README.md
 └── web-app
     ├── app.py
@@ -55,131 +85,239 @@ It processes camera input, performs ML inference, and will later communicate wit
     ├── Pipfile.lock
     ├── readme.txt
     ├── static
-    │   ├── audios
-    │   │   ├── among_us.mp3
-    │   │   ├── android_beep.mp3
-    │   │   ├── bom.mp3
-    │   │   ├── error.mp3
-    │   │   ├── playme.mp3
-    │   │   ├── rick_roll.mp3
-    │   │   ├── rizz.mp3
-    │   │   ├── sponge_bob.mp3
-    │   │   └── uwu.mp3
-    │   ├── hagrid_classes.json
-    │   ├── images
-    │   │   ├── fist.png
-    │   │   ├── like.png
-    │   │   ├── ok.png
-    │   │   ├── one.png
-    │   │   ├── palm.png
-    │   │   ├── stop.png
-    │   │   ├── thinking.png
-    │   │   ├── three.png
-    │   │   └── two_up.png
-    │   ├── script.js
-    │   └── style.css
+    │   ├── audios
+    │   │   ├── among_us.mp3
+    │   │   ├── android_beep.mp3
+    │   │   ├── bom.mp3
+    │   │   ├── error.mp3
+    │   │   ├── playme.mp3
+    │   │   ├── rick_roll.mp3
+    │   │   ├── rizz.mp3
+    │   │   ├── sponge_bob.mp3
+    │   │   └── uwu.mp3
+    │   ├── hagrid_classes.json
+    │   ├── images
+    │   │   ├── fist.png
+    │   │   ├── like.png
+    │   │   ├── ok.png
+    │   │   ├── one.png
+    │   │   ├── palm.png
+    │   │   ├── stop.png
+    │   │   ├── thinking.png
+    │   │   ├── three.png
+    │   │   └── two_up.png
+    │   ├── script.js
+    │   └── style.css
     ├── templates
-    │   └── index.html
+    │   └── index.html
     └── tests
-        ├──   __init__.py
+        ├── __init__.py
         ├── conftest.py
         └── test_app.py
 ```
 
-# 2. Environment Setup (macOS, M-series)
+---
+
+## ⚙️ 1. Environment Setup (Any Platform)
 
-## **1. Install pipenv (if not installed)**
+The recommended workflow uses **pipenv** for dependency management.
 
+### macOS / Linux / Windows (WSL)
+
+#### Install pipenv
 ```bash
 pip install pipenv
 ```
 
-## 2. Install all ML client dependencies
+---
+
+## ⚙️ 2. Running the System (Docker)
 
-From the repository root:
+From project root:
 
 ```bash
-cd machine-learning-client
-pipenv install --dev
+docker compose up --build
 ```
 
-This installs all dependencies, including:
+This starts:
+
+| Service | URL | Purpose |
+|---------|-----|---------|
+| web-app | http://localhost:5000 | Dashboard UI |
+| mongodb | localhost:27017 | Database |
+| ml-client | headless, no UI | Captures gestures + inserts into DB |
+
+To stop:
 
-- mediapipe
-- opencv-python
-- numpy
-- torch (with MPS acceleration for Apple Silicon)
-- pylint + black
-- pytest (required later for unit testing)
+```bash
+docker compose down
+```
+
+---
 
-# 3. Run Live Gesture Recognition (MediaPipe + PyTorch)
+## 👁️ Running the ML Client With Webcam (macOS/Windows/Linux Host)
 
-Make sure your webcam is connected, then run:
+Since macOS Docker cannot access `/dev/video0`, we run the ML client on host machine:
 
 ```bash
 cd machine-learning-client
+pipenv install --dev
 pipenv run python src/live_mediapipe_mlp.py
 ```
 
-You should see:
+Features:
+
+- Live webcam feed
+- MediaPipe hand-tracking
+- PyTorch gesture inference
+- Inserts gesture records into `handsense.gesture_events`
+- Press `q` to quit
 
-- a live webcam preview window
+---
 
-- detected hand skeletons
+## 🗄️ 3. MongoDB Configuration + Starter Data
 
-- predicted gesture label displayed on the frame
+The database name is:
 
-Press **q** to exit.
+```
+handsense
+```
 
-## Note About Running the ML Client in Docker on macOS
+Collections automatically created:
 
-On macOS, Docker containers cannot easily access the host webcam, because the macOS camera is not exposed as a Linux-style /dev/video0 device inside containers.
-For this reason, the live gesture recognition demo cannot run inside the Docker container on macOS.
+| Collection | Purpose |
+|------------|---------|
+| gesture_events | ML client inserts gesture data |
+| controls | Stores capture toggle state |
 
-During development and demo, we run the ML client directly on the host machine, where the webcam works normally:
+At first run the ML client ensures:
 
-```bash
-pipenv run python src/live_mediapipe_mlp.py
+```json
+{
+  "_id": "capture_control",
+  "enabled": false
+}
 ```
 
-The Docker image of the ML client is still fully functional for:
+---
 
-- CI / GitHub Actions
+## 🔐 4. Environment Variables
 
-- dependency isolation
+Both ml-client and web-app use these:
 
-- database integration tests
+| Variable | Description |
+|----------|-------------|
+| MONGO_URI | Mongo connection string (default: `mongodb://mongodb:27017`) |
+| MONGO_DB_NAME | Database name (default: `handsense`) |
+| SECRET_KEY | Flask sessions |
 
-- running without a webcam (e.g., headless mode)
+See `.env.example` below.
 
-This behavior is expected on macOS and does not affect the overall functionality of the 3-container system.
+---
 
-# 4. MongoDB Integration
+## 📄 5. .env.example (Required for TA Submission)
 
-The ML client is already connected to MongoDB using pymongo.
+Place this file in project root:
 
-In src/live_mediapipe_mlp.py, a MongoDB database named handsense is created:
+```env
+# MongoDB configuration
+MONGO_URI=mongodb://mongodb:27017
+MONGO_DB_NAME=handsense
+
+# Flask secret
+SECRET_KEY=dev-secret
+```
+
+Then create an actual `.env`:
 
 ```bash
-mongo_client = MongoClient("mongodb://localhost:27017")
-mongo_db = mongo_client["handsense"]
-gesture_collection = mongo_db["gesture_events"]
+cp .env.example .env
 ```
 
-For every detected hand gesture, an event document is inserted:
+---
+
+## 🔍 6. Web App (Flask) — Running Locally
 
 ```bash
-event = {
-    "timestamp": datetime.now(timezone.utc).isoformat(),
-    "gesture": pred_label,
-    "confidence": confidence,
-    "handedness": handedness,
-}
-gesture_collection.insert_one(event)
+cd web-app
+pipenv install --dev
+pipenv run flask run --host=0.0.0.0 --port=5000
 ```
 
-This allows the Web App subsystem to read and visualize real-time gesture activity from:
+Navigate to:
+
+👉 **http://localhost:5000**
 
+### Endpoints:
+
+| Route | Description |
+|-------|-------------|
+| `/` | Dashboard UI |
+| `/api/latest` | Latest gesture |
+| `/api/latest_full` | Latest gesture (detailed) |
+| `/api/control` | POST toggle capture |
+| `/api/control/status` | GET capture control |
+
+---
+
+## 🧪 7. Testing + Linting + Coverage
+
+### Run ML Client Tests
+```bash
+cd machine-learning-client
+pipenv run pytest --cov=src
+pipenv run pylint src
+```
+
+### Run Web App Tests
 ```bash
-handsense.gesture_events
+cd web-app
+pipenv run pytest --cov=.
+pipenv run pylint app.py
+```
+
+Coverage must be ≥ 80%.
+
+---
+
+## 🧰 8. Docker Compose
+
+```yaml
+version: "3.9"
+
+services:
+  mongodb:
+    image: mongo:6
+    container_name: mongodb
+    ports:
+      - "27017:27017"
+    volumes:
+      - mongo-data:/data/db
+
+  web-app:
+    build:
+      context: ./web-app
+    container_name: web-app
+    depends_on:
+      - mongodb
+    environment:
+      MONGO_URI: "mongodb://mongodb:27017"
+      MONGO_DB_NAME: "handsense"
+      FLASK_APP: "app.py"
+      FLASK_RUN_HOST: "0.0.0.0"
+    ports:
+      - "5000:5000"
+
+  ml-client:
+    build:
+      context: ./machine-learning-client
+    container_name: ml-client
+    depends_on:
+      - mongodb
+    environment:
+      MONGO_URI: "mongodb://mongodb:27017"
+      MONGO_DB_NAME: "handsense"
+
+volumes:
+  mongo-data:
 ```
diff --git a/docker-compose.yml b/docker-compose.yml
index 76e857d7..3a7bb532 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -21,7 +21,7 @@ services:
       FLASK_APP: "app.py"
       FLASK_RUN_HOST: "0.0.0.0"
     ports:
-      - "5001:5000"
+      - "5000:5000"
 
   ml-client:
     build: