Project Guide | Retina Scan AI

Live Demo

• Open the public Cloudflare Pages demo
• Scope: credential-free, synthetic-data demo for industrial validation discovery and model-governance evaluators.

Non-clinical retinal-image classification research sandbox using ResNet18 transfer learning with Grad-CAM interpretability. It classifies synthetic or explicitly approved fundus-style images into 5 demonstration categories: Normal, Diabetic Retinopathy, Glaucoma, Cataract, and Age-related Macular Degeneration (AMD).

Validation review pack: `docs/architecture-pack.md`

System Overview

A non-clinical vision validation workflow that demonstrates model-governance review patterns while clearly staying outside diagnostic, medical-device, and production-readiness claims.

Evaluation Path

• Start here: Read the model card and risk notes before looking at predictions.
• Local demo: Start the API with uvicorn api.main:app --host 0.0.0.0 --port 8000, then test /predict or /gradcam.
• Checks: Run pytest -v; training and serving paths are intentionally separated from clinical claims.

Architecture Notes

• Architecture guide summarizes the system scope, first files to inspect, runtime commands, and known boundaries.
• Quality notes lists the local checks, CI surface, and release expectations for this repository.
• Enterprise readiness notes outlines security, data, operations, integration, and handoff expectations.

Architecture

Input Image (224x224)
    │
    ▼
┌──────────────────────┐
│  ResNet18 Backbone    │  ← ImageNet pretrained weights
│  (Feature Extractor)  │
└──────────┬───────────┘
           │ 512-dim features
           ▼
┌──────────────────────┐
│  Classification Head  │
│  Dropout(0.3) →       │
│  Linear(512→256) →    │
│  ReLU → Dropout(0.2)  │
│  → Linear(256→5)      │
└──────────┬───────────┘
           │
           ▼
    5-class prediction

Key Features

• Transfer Learning: ResNet18 pretrained on ImageNet, fine-tuned for retinal classification
• Data Augmentation: Random flip, rotation, color jitter, affine transforms
• Training Pipeline: Early stopping, LR scheduling, checkpointing, metric logging
• Evaluation: Confusion matrix, per-class precision/recall/F1, ROC-AUC curves
• Grad-CAM: Visual explanations showing which retinal regions drive each prediction
• Inference API: FastAPI REST endpoint for real-time classification
• Docker: Containerized training and serving

Project Structure

retina-scan-ai/
├── src/
│   ├── config.py        # Hyperparameters and class labels
│   ├── dataset.py       # Custom dataset with augmentation pipeline
│   ├── model.py         # ResNet18 transfer learning architecture
│   ├── train.py         # Training loop with early stopping
│   ├── evaluate.py      # Confusion matrix, ROC curves, classification report
│   ├── gradcam.py       # Grad-CAM visualization for interpretability
│   └── inference.py     # Single-image prediction wrapper
├── api/
│   ├── main.py          # FastAPI inference server
│   └── schemas.py       # Request/response models
├── tests/
│   ├── test_model.py    # Model architecture tests
│   ├── test_dataset.py  # Dataset and transform tests
│   ├── test_train.py    # Training component tests
│   └── test_api.py      # API endpoint tests
├── scripts/
│   └── download_data.py # Dataset preparation utility
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
└── requirements.txt

Setup

pip install -r requirements.txt

Prepare Dataset

## Option 1: Use ODIR-5K dataset from Kaggle
python scripts/download_data.py <csv_path> <images_dir>


## Option 2: Generate synthetic data for pipeline testing
python scripts/download_data.py --synthetic 100

Expected directory structure:

data/retina/
├── Normal/
├── Diabetic_Retinopathy/
├── Glaucoma/
├── Cataract/
└── AMD/

Train

python -m src.train

Outputs:

• checkpoints/best_model.pth — Best model weights
• outputs/training_history.json — Epoch-level metrics

Evaluate

python -m src.evaluate checkpoints/best_model.pth

Outputs:

• outputs/confusion_matrix.png — Confusion matrix heatmap
• outputs/roc_curves.png — Per-class ROC curves with AUC
• outputs/evaluation_results.json — Full metrics report

Grad-CAM Visualization

python -m src.gradcam <image_path> checkpoints/best_model.pth

Inference API

uvicorn api.main:app --host 0.0.0.0 --port 8000


## Predict
curl -X POST http://localhost:8000/predict -F "file=@retina_image.jpg"


## Grad-CAM
curl -X POST http://localhost:8000/gradcam -F "file=@retina_image.jpg" -o gradcam.png

HTTP image uploads are capped at 16 MiB and 50 million decoded pixels by default. Expensive prediction and Grad-CAM work is limited to one in-flight operation per process, and Grad-CAM artifacts use request-scoped temporary directories that are removed after the response is sent. Deployments can tune these safeguards with RETINA_MAX_UPLOAD_BYTES, RETINA_MAX_IMAGE_PIXELS, and RETINA_MAX_CONCURRENT_INFERENCES.

Docker

## Inference server
docker compose up api


## Training
docker compose --profile training run train

Tests

pytest -v

Dataset

Designed for the ODIR-5K (Ocular Disease Intelligent Recognition) dataset containing 5,000 retinal fundus photographs across 8 disease categories, filtered to 5 primary classes.

Tech Stack

Not a Medical Device

This repository is research code. It has not been FDA-cleared, CE-marked, or approved by any regulatory body for clinical use. Any deployment for clinical care requires regulatory clearance, IRB review, and integration with a quality management system. See compliance/fda-samd-considerations.md and risk/known-limitations.md for details.

Compliance & Governance

This service includes compliance and governance artifacts that align with typical healthcare-AI deployment requirements. Refer to the relevant directory for details.

Deferred Clinical Artifacts

docs/clinical/ contains planning artifacts for reviewers who need to understand what would be required before any clinical workflow discussion. These files are not evidence of clinical deployment, diagnostic performance, regulatory clearance, or production readiness:

• deployment-architecture.md — DMZ placement, OIDC federation, DICOM routing.
• dicom-integration.md — PACS C-STORE SCP, anonymization, GSPS overlays.
• clinician-in-the-loop.md — Second-reader / triage UX; disagreement handling.
• change-control.md — Model retraining governance.
• drift-monitoring.md — Input distribution, calibration, population drift.
• incident-response.md — Clinical workflow fallback, recall procedure.

dicom/ has the DICOM integration code (C-STORE SCP listener, anonymizer, GSPS generator, audit logger).

access/ has the RBAC + OIDC reference layer with example reviewer roles.

audit/ has the HIPAA-aligned hash-chained audit logger and compliance officer search tooling.

clinical_ui/ has a static HTML mockup for human-review discussion, not clinical use.

Validation

validation/ contains templates for planning a validation study. They are discovery artifacts, not active clinical-study results:

• study-protocol.md — Protocol following CONSORT-AI / SPIRIT-AI standards.
• sample-size-calculation.py — Runnable sample size calculator.
• case-report-form.md — Per-subject CRF template.
• results-template.json — JSON schema of the validation-study output.

Risk Management

risk/ follows ISO 14971:2019:

• fmea.md — Failure Mode and Effects Analysis (20 items).
• iso14971-mapping.md — Clause-by-clause coverage of ISO 14971.
• known-limitations.md — Cataloged constraints and edge cases.

Related Projects

Cloud + AI Architecture

• Cloud + AI architecture blueprint
• Machine-readable architecture manifest
• Validation command: python3 scripts/validate_architecture_blueprint.py

Enterprise Productization

• Product operating model defines the product scope, trust boundary, operating checks, and service path for this repository.

System Architecture

• System architecture maps the runtime boundary, data/control flow, cloud or local deployment surface, and operating assumptions for this repository.

Service Architecture

• Service architecture defines the cloud resources, account information, cost controls, and production guardrails needed to turn this repo into a scoped service without publishing public financial assumptions.

Search And Service Surface

• Public entry: free synthetic-data research demo with non-diagnostic framing
• Paid boundary: private industrial validation discovery for data suitability, baseline evaluation, model-card drafting, and human-review acceptance criteria
• Canonical URL: https://retina-scan-ai.pages.dev/
• Lead capture: https://kim3310-doeon-kim-portfolio.pages.dev/?offer=retina-scan-ai&inquiry=industrial-validation-discovery#private-inquiry
• Resource route: https://kim3310-doeon-kim-portfolio.pages.dev/resources/retina-scan-ai/
• Commercial route: https://kim3310-doeon-kim-portfolio.pages.dev/?offer=retina-scan-ai#service-offers
• CTA: Request private industrial validation discovery through the central inquiry URL
• Machine-readable offer: docs/service-offer.json
• Search growth implementation: docs/search-growth-implementation.md
• Revenue architecture: docs/revenue-architecture.md