TumorLens

A full-stack medical SaaS platform for brain tumor detection and AI-assisted clinical reporting from MRI scans.

TumorLens lets clinicians upload a brain MRI scan, runs it through a deep-learning classifier, and generates a retrieval-augmented (RAG) clinical report - all wrapped in a multi-tenant SaaS with subscriptions, organizations, and a public API.

🎓 This project was developed as a final-year graduation project.

---

✨ Features

• AI tumor classification - EfficientNet-B0 model detects glioma, meningioma, pituitary, or no tumor from MRI scans, with a heuristic guard that rejects non-MRI images.
• RAG clinical reports - Generates PDF reports grounded in medical literature using OpenAI embeddings and a Qdrant vector database.
• Authentication & security - JWT access/refresh tokens (HTTP-only cookies), Google OAuth, TOTP-based 2FA, and password reset via email.
• Multi-tenancy - Organizations with members, roles, and audit logs for hospitals and clinics.
• Subscriptions & billing - Stripe-powered plans (FREE, DOCTOR, ORGANIZATION) with route-level plan guards.
• Patient management - Full clinical data chain: Patient → Scan → ScanResult.
• Real-time notifications - Server-Sent Events (SSE) for in-app updates.
• Async processing - Report generation queued with BullMQ + Redis.
• Cloud storage - DigitalOcean Spaces (S3-compatible) for scans and reports.
• Public API - API-key authentication for external integrations.

---

🏗️ Architecture

TumorLens is a monorepo of four independent services:

Service	Stack	Port	Description
client/	React 19 · Vite · TanStack Router/Query · Ant Design	5173	Web frontend
server/	NestJS 11 · Prisma 7 · PostgreSQL · Redis	3000	Core API & business logic
scan_model/	Python · FastAPI · PyTorch · timm	7860	Brain tumor ML inference
scan_report/	Python · FastAPI · OpenAI · Qdrant	8000	RAG-based report generation

                ┌─────────────┐
                │   client/   │  React 19 SPA (5173)
                └──────┬──────┘
                       │ HTTP / cookies
                ┌──────▼──────┐
                │   server/   │  NestJS API (3000)
                │  Prisma →   │──── PostgreSQL
                │  BullMQ  →  │──── Redis
                └──┬───────┬──┘
                   │       │
        ML_MODEL_URL│       │RAG_REPORT_URL
           ┌───────▼─┐   ┌─▼──────────┐
           │scan_model│   │scan_report │
           │ (7860)   │   │  (8000)    │
           └──────────┘   └────────────┘

---

🚀 Getting Started

Prerequisites

• Docker & Docker Compose (recommended), or
• Node.js 20+, Python 3.11+ with uv, PostgreSQL, and Redis for local development.

Run the full stack with Docker

git clone <repo-url> tumorlens
cd tumorlens

# Create the required .env files (see Environment Setup below)
docker-compose up

Services will be available at:

• Frontend → http://localhost:5173
• API → http://localhost:3000
• ML model → http://localhost:7860
• RAG reports → http://localhost:8000

---

🛠️ Local Development

Client (cd client)

npm install
npm run dev        # Vite dev server with HMR
npm run build      # tsc -b && vite build
npm run lint       # ESLint

Server (cd server)

npm install
npm run start:dev  # NestJS watch mode
npm run test       # Jest unit tests
npm run lint       # ESLint --fix

# Prisma
npx prisma migrate dev   # Apply migrations
npx prisma generate      # Regenerate client
npx prisma studio        # Visual DB browser

ML services (cd scan_model / cd scan_report)

uv sync            # Install dependencies
uv run uvicorn main:app --reload   # (scan_report)
uv run python app.py               # (scan_model)

---

⚙️ Environment Setup

server/.env

DATABASE_URL=postgresql://...
JWT_ACCESS_SECRET=...
JWT_REFRESH_SECRET=...
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
ML_MODEL_URL=http://localhost:7860
ML_MODEL_API_KEY=...
RAG_REPORT_URL=http://localhost:8000
DIGITAL_OCEAN_SPACE_KEY=...
DIGITAL_OCEAN_SPACE_SECRET=...
DIGITAL_OCEAN_SPACE_ENDPOINT=...
DIGITAL_OCEAN_SPACE_BUCKET=...
RESEND_API_KEY=...
STRIPE_SECRET_KEY=...
STRIPE_WEBHOOK_SECRET=...
REDIS_HOST=localhost
REDIS_PORT=6379
CLIENT_URL=http://localhost:5173
PORT=3000

client/.env

VITE_API_URL=http://localhost:3000

scan_report/.env

OPENAI_API_KEY=...
API_KEY=...
QDRANT_URL=...
QDRANT_API_KEY=...

---

🧬 Core Data Models

The Prisma schema lives in server/prisma/schema.prisma:

• User - roles (USER, ADMIN), plans (FREE, DOCTOR, ORGANIZATION), OTP/2FA support
• Organization → OrgMember - multi-tenant clinics with audit logs
• Patient → Scan → ScanResult - core clinical data chain
• Subscription + Payment - Stripe billing
• Session - refresh token store
• ApiKey - public API access

---

🤖 The ML Model

• Architecture: EfficientNet-B0 (via timm), 4-class classifier.
• Classes: glioma, meningioma, notumor, pituitary.
• Trained on the Brain Tumor MRI Dataset (see doc/).
• Includes a lightweight heuristic check to reject obviously non-MRI input (e.g. colored or non-scan images) before inference.

---

🔄 CI/CD

GitHub Actions (.github/workflows/) runs tests and linting (Jest + Ruff) and, on push to main, builds Docker images and deploys to a DigitalOcean Droplet. Path filters ensure only changed services are rebuilt. Images are published to GHCR.

---

📂 Repository Structure

TumorLens/
├── client/         # React 19 frontend
├── server/         # NestJS API + Prisma
├── scan_model/     # FastAPI ML inference service
├── scan_report/    # FastAPI RAG report service
├── doc/            # Documentation, dataset, diagrams
├── docker-compose.yml
└── CLAUDE.md       # Project guidance

---

⚠️ Medical Disclaimer

TumorLens is a research and educational project. It is not a certified medical device and must not be used for actual clinical diagnosis, treatment, or any real-world medical decision-making.

---

📜 License

Copyright © 2026 Osama. All Rights Reserved.

This is proprietary software developed as a final-year graduation project. No permission is granted to use, copy, modify, distribute, or otherwise exploit the code, models, or assets without the prior written consent of the author. See the LICENSE file for full terms.