Chest X-Ray AI Analysis

Chest X-Ray AI Analysis is a two-service web application for educational and research use. It runs a PyTorch chest X-ray model, returns prediction scores for supported findings, and generates Grad-CAM visual explanations for findings that pass the configured probability threshold.

The project includes:

• a FastAPI backend for inference and heatmap generation
• a React + Vite frontend for upload, review, and legal pages
• separate container definitions for frontend and backend
• Cloud Run deployment guidance for public demo hosting

Highlights

• Chest X-ray inference with TorchXRayVision DenseNet121
• Grad-CAM heatmaps for eligible findings
• Strict upload validation for type, size, and image dimensions
• No intentional image retention after processing
• Minimal logging and demo-oriented rate limiting
• Separate frontend and backend deployment targets

Architecture

• frontend/: React application served as a static site
• src/api/: FastAPI app and request handling
• src/inference/: prediction pipeline
• src/model/: model loading
• src/visualization/: Grad-CAM generation and overlays
• deploy/: deployment configuration files

Local Development

1. Create and activate a Python environment

Windows PowerShell:

py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1

If PowerShell blocks activation, use:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\.venv\Scripts\Activate.ps1

2. Install backend dependencies

pip install -r requirements.txt

3. Run the backend

uvicorn src.api.main:app --reload --host 127.0.0.1 --port 8000

4. Run the frontend

cd frontend
npm install
npm run dev

The frontend runs on http://localhost:5173 by default and expects the backend at http://127.0.0.1:8000 unless VITE_API_BASE_URL is set.

Configuration

Example backend environment variables are provided in .env.example.

Important settings:

• MODEL_NAME
• DEVICE
• CORS_ORIGINS_RAW
• GRADCAM_MIN_PROBABILITY
• UPLOAD_MAX_SIZE_MB
• MAX_IMAGE_PIXELS
• ALLOWED_CONTENT_TYPES_RAW
• RATE_LIMIT_REQUESTS_PER_MINUTE

Frontend:

• VITE_API_BASE_URL: backend base URL used by the React app

API

POST /predict

Accepts a chest X-ray image and returns:

• top predicted finding
• probability scores for all supported findings
• default Grad-CAM result for the top finding when available

POST /predict/heatmap?class_idx=<n>

Generates a Grad-CAM heatmap for a selected class when its probability is at least the configured threshold.

Deployment

The app is designed to run as two separate services:

• backend on Cloud Run
• frontend on Cloud Run

Deployment references:

• DEPLOY_CLOUD_RUN.md
• cloudbuild-api.yaml
• frontend/cloudbuild.yaml
• Dockerfile.api
• frontend/Dockerfile

Security Notes

This repository is configured for a public educational demo, not a clinical system.

Implemented controls include:

• strict CORS support
• upload size and MIME restrictions
• image dimension checks
• no persistent storage of uploaded images
• minimal logs
• response no-store headers

Additional deployment notes are documented in SECURITY_NOTES.md.

Responsible Use

This project is for education, research, and technical demonstration only. It is not a medical device and must not be used for diagnosis, treatment, or clinical decision-making.

License

This project is released under the license in LICENSE.