PROJECT_SUMMARY.md

# Malaria AI - Full Project Journey & Technical Summary 🚀

## Introduction & Aim
The goal of this project was to build an intelligent, production-ready AI system capable of diagnosing malaria from microscope slide imagery. What started as an experimental Jupyter Notebook evolved through several architectural iterations into a robust, cloud-deployed Computer Vision microservice.

---

## Phase 1: The Initial CNN Architecture & Data Extraction
**The Starting Point:** We began with raw microscope images and a bulky `training.json` file containing bounding box coordinates mapping where cells and parasites were located.

**Our First Approach:** We approached this as an **Image Classification** problem. 
1. In a Jupyter Notebook, we wrote a Python script to iterate through the `training.json` and physically *crop* out the individual cells from the larger slides.
2. We sorted these cropped thumbnails into two massive folders: `processed_cells/parasite` and `processed_cells/uninfected`.
3. We built and trained a **TensorFlow/Keras Convolutional Neural Network (CNN)** on these perfectly centered 128x128 pixel crops.
4. The model achieved >94% accuracy and was exported as `malaria_cell_classifier.h5`.

---

## Phase 2: Deploying the CNN & Setting up MLOps
**The Problem:** The model was stuck on a local hard drive. There was no way to share it, run it on a server, or let a user interact with it.

**The Solution:** We transitioned out of the notebook into standard software engineering.
* **Backend:** We wrapped the `.h5` model inside a **FastAPI** web server, exposing a `/predict` endpoint.
* **Tracking:** We wrote `log_model.py` to register the model cleanly into **MLflow** for future version control.
* **Containerization:** We wrote a **Dockerfile** using `python:3.10-slim` and headless OpenCV so the app could run precisely identical anywhere in the world.
* **CI/CD:** We built **GitHub Actions** and wrote **Pytest** tests to automatically test the API whenever code was changed.

---

## Phase 3: The Architectural Problem & Hosting Limitations
**The Problem:** We wanted to deploy the API to a platform and give it a beautiful UI. However, standard Serverless structures have tight size limits (usually 250MB) which the massive TensorFlow library exceeded. Furthermore, the UI highlighted a deeper, fundamental flaw in our AI architecture:
* Our CNN required the user to upload a *pre-cropped, perfectly centered single cell*. 
* In the real world, doctors upload **massive, chaotic slide images** containing hundreds of overlapping cells. The CNN had no idea how to "find" the cells in the image.

**The Solution:**
* **Hosting Pivot:** We shifted to **Hugging Face Spaces**, which natively supports heavy Docker ML containers. We updated our Dockerfile to run on Port 7860 using an unprivileged non-root user to match Hugging Face’s strict security patterns.
* **UI Integration:** We built a stunning, dark-mode Glassmorphism UI (HTML/CSS/JS) and mounted it directly into the FastAPI server so the API and UI were packaged as one unit.

---

## Phase 4: The Ultimate Solution (YOLOv8 Object Detection)
**The Problem:** We needed the AI to scan a massive image, hunt down the cells, and draw boxes around the infected ones—a process the `.h5` classification model mathematically could not do.

**The Solution:** The complete pivot to **Object Detection**.
1. **Ditching TensorFlow:** We abandoned the CNN classifier approach entirely and embraced **Ultralytics YOLOv8**.
2. **Data Transformation:** We wrote `prepare_yolo_data.py` to computationally convert the JSON coordinates into math formats between `0.0` and `1.0` (YOLO format), creating `train` and `val` text files linking directly to the full-size images.
3. **Training YOLO:** The legacy `processed_cells` directory was deleted, and a new custom base model was trained natively.

---

## Phase 5: The Full-Stack Integration
**The Problem:** Integrating the new YOLO model (`best.pt`) with the UI.

**The Solution:** 
1. **API Overhaul:** We rewrote `app.py` to replace TensorFlow with Ultralytics. The API now returns large JSON arrays detailing every box it found: `[x1, y1, x2, y2, confidence, label]`. 
2. **Reactive Frontend:** We upgraded `script.js` to mathematically calculate bounding box logic and project glowing CSS components dynamically onto the target.

---

## Phase 6: Hardware Optimization & Deployment Bug Fixes
**The Problem:** Taking an ML Model to Production often exposes unforeseen bottlenecks in memory, rendering frameworks, and system dependencies deep inside Linux containers.

**The Solution:**
1. **Apple Silicon Unified Memory Overflows:** While chasing maximum accuracy with the massive `yolov8m` model, we hit an architectural bottleneck. The model requested 12.4GB of RAM, overflowing the Mac's physical memory boundaries. This triggered brutal SSD "Swap Memory" ping-ponging, slowing training to an unusable 78 seconds-per-iteration. We successfully engineered around this by stepping down to `yolov8s` (Small), dropping image bounds to `640`, and explicitly locking `batch=4` alongside `device=mps`. This clamped GPU demand at 3GB entirely inside physical RAM, boosting iteration speeds by 900%.
2. **Docker System Library Crashing:** Upon deploying the YOLO FastApi wrapper to Hugging Face via the Dockerfile, the cloud container crashed throwing `libGL.so.1` errors. OpenCV strictly relies on underlying C++ Video Rendering libraries which do not ship in minimalist Python slim environments. We patched the Dockerfile with an immediate `apt-get install libgl1 libglib2.0-0` execution layer, permanently bridging the graphics interface dependency.
3. **Frontend Spatial Math Anomalies:** When overlaying bounding boxes onto the web UI, the UI's `object-fit: contain` CSS caused image letterboxing and coordinate drift. We rewrote the coordinate transformation loop in `script.js` to cross-reference HTML Container Aspect Ratios against Raw Internal Image Aspect Ratios, extracting the exact horizontal/vertical offset required to perfectly nail the glowing boxes to the rendered cells regardless of user screen size.
4. **PyTorch Memory Leak Mitigations:** Long PyTorch Dataloader workloads on Apple Silicon sometimes fail to properly clear garbage collection, resulting in creeping SSD swap accumulation. We countered this exponential slowdown by strategically pausing the terminal and executing a YOLO `resume=True` flag against the current `last.pt` weights. This reliably flushed the physical RAM caches, dynamically restoring GPU performance to full capacity without dropping training progress.
5. **Windows NVIDIA VRAM vs Mac Unified Memory:** Designed cross-platform mitigation strategies for memory bounds. While Apple Silicon cleanly handled massive memory requests via slow SSD Unified Memory swaps, executing the same codebase on enterprise NVIDIA GPUs triggered volatile `CUDA Out Of Memory (OOM)` fatal crashes. We mathematically bounded the Tensor loads via precise `batch` size rationing to lock PyTorch footprints strictly within hardware VRAM ceilings, securing cross-ecosystem stability.

---

## The Final Tech Stack
* **AI Architecture:** Ultralytics YOLOv8s Object Detection (MPS Accelerated)
* **Backend:** Python, FastAPI, OpenCV
* **Frontend:** Vanilla HTML/CSS/JS with reactive scaling
* **Deployment System:** Docker mapping to Hugging Face Spaces