MedClassify API

A production-grade microservices platform for medical image classification, demonstrating multi-service Kubernetes architecture, multi-cloud IaC, and full CI/CD automation.

Client
  │
  ▼
Gateway (FastAPI :8000)          ← single public entry-point
  ├─▶ Ingest Service (:8001)     ← validates + persists images
  └─▶ Classify Service (:8002)   ← CNN classifier (TF 2.16)
          │
    /models volume               ← weights mounted at runtime

Deployed via Helm to AWS EKS and Azure AKS, provisioned with Terraform, monitored with Prometheus + Grafana, and delivered via GitHub Actions and Azure DevOps Pipelines.

---

What's in this repo

Path	Purpose
services/gateway/	API gateway — orchestrates ingest + classify
services/ingest/	Validates and stores incoming scan images
services/classify/	CNN classification service (demo mode without model)
helm/medclassify/	Helm chart — deployments, services, HPA, ingress
terraform/aws/	EKS cluster + VPC (Spot GPU nodes)
terraform/azure/	AKS cluster + ACR + Spot inference node pool
.github/workflows/	CI/CD: lint → test → build × 3 → Helm deploy
azure-pipelines/	Azure DevOps mirror pipeline
monitoring/	Prometheus scrape config + Grafana (docker-compose)

Run locally

# Start all services + monitoring
docker compose up --build

# Gateway:    http://localhost:8000/docs
# Ingest:     http://localhost:8001/docs
# Classify:   http://localhost:8002/docs
# Prometheus: http://localhost:9090
# Grafana:    http://localhost:3000

Call the API

curl -X POST \
  "http://localhost:8000/scan?modality=MRI&body_part=brain" \
  -F "file=@brain_scan.raw"

Without model weights the classify service runs in demo mode and returns deterministic mock scores — fully functional for integration testing.

Run tests (no model needed)

pip install fastapi uvicorn httpx prometheus-fastapi-instrumentator python-multipart numpy pytest

# Each service independently
PYTHONPATH=services/gateway/app  pytest services/gateway/tests/  -v
PYTHONPATH=services/ingest/app   pytest services/ingest/tests/   -v
PYTHONPATH=services/classify/app pytest services/classify/tests/ -v

Infrastructure

AWS (EKS)

cd terraform/aws
terraform init && terraform apply

Provisions: VPC (2 AZs), EKS 1.30, Spot GPU node group (g4dn.xlarge), API node group (t3.medium).

Azure (AKS)

cd terraform/azure
terraform init && terraform apply

Provisions: Resource group, VNet, AKS 1.30, Spot inference node pool (NC4as_T4_v3), ACR with AcrPull role assignment.

Deploy with Helm

helm upgrade --install medclassify helm/medclassify/ \
  --set imageTag=<sha> \
  --atomic --timeout 5m

Key design decisions

Decision	Rationale
3 independent microservices	Each scales independently; classify is GPU-heavy, ingest is I/O-bound
Helm chart	Single source of truth for K8s config; parameterised for dev/prod
Multi-cloud Terraform	AWS EKS for existing workloads; Azure AKS for Azure DevOps integration
Spot instances	~65–70 % cost reduction for GPU inference nodes
Demo mode in classify	Runs deterministic mock scores without weights — CI and local dev need no GPU
Model weights never baked in	Mounted at runtime via K8s PVC; updates without image rebuild
Non-root containers	Security baseline for medical data
HPA on gateway + classify	Auto-scales 2 → 20 on CPU utilisation