Eye Scanner: Open Source Ophthalmic Diagnostic System 👁️

Eye Scanner is a dual-architecture, zero-infrastructure edge Progressive Web App (PWA) designed to democratize high-grade medical diagnostics.

🌍 The Mission

I built Eye Scanner with a singular goal in mind: to bring immediate, clinical-grade medical treatment to marginalized and deeply impoverished populations where hospitals do not exist.

In rural and underserved regions, the lack of immediate access to an ophthalmologist can mean the difference between sight and permanent blindness. Eye Scanner places a powerful diagnostic engine directly into the pockets of field workers, running entirely on consumer-grade mobile devices. It works entirely offline when internet connectivity is completely unavailable, ensuring that poor communities get immediate triage and intervention without relying on expensive, centralized medical infrastructure.

🧠 System Architecture

Eye Scanner utilizes a deeply optimized split-architecture system that fluidly transitions between edge-compute and cloud-compute based on network availability.

graph TD
    subgraph Client ["Client Device (Offline/Edge)"]
        A[Camera Capture] --> B[CLAHE Preprocessing]
        B --> C{Network Status?}
        C -- Offline --> D[ONNX WebEngine]
        D --> E[IndexedDB Queue]
    end

    subgraph Cloud ["Cloud Engine (Online/REST)"]
        C -- Online --> F[FastAPI Backend]
        F --> G[EfficientNet-B4 + Grad-CAM]
        G --> H[Supabase DB Sync]
    end

    E -- Automatic Sync --> F
    H --> I[Detailed PDF Report]

Loading

1. The Offline Edge Engine (Browser-Native)

When operating in remote areas with zero connectivity, Eye Scanner falls back to a locally cached MobileNetV3 neural network.

• ONNX Runtime Web: Executed completely locally using WebAssembly (.wasm) and WebGL APIs to process images natively within the device's CPU/GPU.
• IndexedDB Offline Queue: Scans taken offline are securely queued in the browser's IndexedDB. When connectivity is restored, the is_offline: true flagged records sync back to the master database.

2. The Cloud Ensemble (FastAPI + HuggingFace)

When internet is restored, the PWA seamlessly transitions to a robust, serverless backend hosted on Hugging Face Spaces.

• Pure FastAPI Inference: Stripped of UI bloat, the cloud runs a heavy-duty EfficientNet-B4 model.
• Grad-CAM Heuristics: Generates granular heatmaps using Gradient-weighted Class Activation Mapping to pinpoint the exact vascular lesions and exudates.
• Monte Carlo Dropout (MC Dropout): Runs 10 concurrent passes to generate statistical uncertainty metrics, warning clinicians of low-confidence predictions.

3. Image Preprocessing Pipeline

• CLAHE: Contrast Limited Adaptive Histogram Equalization is applied client-side to strip lighting abnormalities and clarify retinal vessels.
• EXIF Parser: Automatically reads focal length, ISO, and device manufacturer metrics to normalize inference weights.

4. Zero-Data-Leak Federated Learning

The architecture includes rudimentary hooks for Federated Learning. Rather than uploading heavy, privacy-violating patient images to centralized servers, Eye Scanner captures encrypted weight deltas which are aggregated periodically, meaning the model gets smarter globally while patient data never leaves the device locally.

🛠️ Tech Stack

• Frontend: React.js, Vite, Vanilla CSS
• Backend Inference: Python, FastAPI, TensorFlow/Keras
• Database: Supabase (PostgreSQL + RLS)
• Edge Inference: ONNX WebAssembly

---

📘 Engineering Insights

For a deep dive into the technical challenges faced during development (Camera APIs, ONNX conversion, and Backend hurdles), see the HURDLES.md document.

🚀 Quick Start Guide

Prerequisites

1. Node.js (v18+)
2. Supabase Account
3. Hugging Face Account

Installation

1. Clone the repository:

git clone https://github.com/mrQhere/eye-scanner-pwa.git
cd eye-scanner-pwa

2. Install dependencies:

npm install

3. Set up your environment variables (see .env.example):

cp .env.example .env
# Edit .env with your specific API keys

4. Run locally:

npm run dev

⚖️ License & Usage

This software is released under the Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0) license.

The mission of Eye Scanner is strictly humanitarian. You are free to fork this project, deploy it, and use it in your local communities. However, you are strictly prohibited from using any part of this software, its models, or its architectures for commercial profit or monetization.

---

Developed by mrQhere. For a world where healthcare has no borders.