An end-to-end ML image classification web app deployed on AWS — 100% Free Tier ($0/month)
Upload any image and our AI will tell you whether it's a cat 🐱 or a dog 🐶 — complete with confidence probabilities!
| Service | URL |
|---|---|
| Frontend | cat-vs-dog-frontend-235899055608.s3-website.eu-west-2.amazonaws.com |
| API Health | af9aiibt3m.execute-api.eu-west-2.amazonaws.com/health |
┌─────────────┐ ┌──────────────┐ ┌─────────────┐ ┌───────────┐
│ Browser │──────▶│ S3 Static │ │ API Gateway │──────▶│ Lambda │
│ (Frontend) │ │ Website │──────▶│ (HTTP API) │ │ (Docker) │
└─────────────┘ └──────────────┘ └──────────────┘ └─────┬─────┘
│
┌──────────────┐ ┌──────────────┐ │
│ CloudWatch │◀──────│ ECR │◀───────────┘
│ Alarms │ │ (Container) │
└──────┬───────┘ └──────────────┘
│
┌──────▼───────┐
│ SNS Email │
│ Alerts │
└──────────────┘
Frontend → Static HTML/CSS/JS hosted on S3 (drag-and-drop image upload with light/dark mode)
Backend → Lambda (container image from ECR) behind API Gateway, running ONNX inference
Monitoring → CloudWatch alarms → SNS email alerts + AWS Budget guard
CI/CD → GitHub Actions builds Docker, pushes to ECR, deploys frontend to S3
- Image Preprocessing — Smart resize (128×128), CLAHE contrast enhancement, bilateral filtering
- Feature Extraction — 10,221 handcrafted features from 8 families:
- HOG (Histogram of Oriented Gradients) — fine + coarse
- LBP (Local Binary Patterns) — multi-scale
- Color Histograms (HSV + LAB)
- Color Moments (mean, std, skew)
- Haralick Texture Features (GLCM)
- Hu Moments (shape descriptors)
- Edge Features (Canny, Sobel, orientation histograms)
- Gabor Filter Responses (multi-frequency, multi-orientation)
- StandardScaler — Normalizes features to match training distribution
- XGBoost (ONNX) — Gradient-boosted tree ensemble for binary classification
- Probability Output — Returns per-class probabilities (cat % vs dog %)
- OOD Detection — If neither class exceeds 51% confidence, the image is flagged as "unknown"
| Metric | Score |
|---|---|
| Accuracy | >80% |
| F1 Score | >80% |
| Model Size | 2.03 MB (ONNX) |
| Inference Time | ~3-5s (Lambda cold start: ~30s first request) |
image_processing/
├── api/ # Backend API
│ ├── main.py # FastAPI app with /health and /predict endpoints
│ ├── lambda_handler.py # AWS Lambda entry point
│ ├── ml.py # ML pipeline (ONNX model + StandardScaler)
│ ├── feature_extractor.py # Image preprocessing & 10,221-feature extraction
│ ├── schemas.py # Pydantic response models
│ └── dependencies.py # Singleton model loader
├── frontend/ # Static frontend (hosted on S3)
│ ├── index.html # Main UI with drag-and-drop upload
│ ├── index.css # Styles with light/dark mode
│ └── app.js # Upload logic, probability bars, theme toggle
├── model/ # Trained model artifacts
│ ├── xgboost_champion.onnx # XGBoost model in ONNX format (2.03 MB)
│ └── scaler.joblib # Fitted StandardScaler (240 KB)
├── infra/ # Terraform Infrastructure as Code
│ ├── main.tf # ECR, S3, Lambda, API Gateway, IAM
│ ├── outputs.tf # Deployment URLs
│ └── monitoring.tf # CloudWatch alarms, SNS, Budget guard
├── .github/workflows/
│ └── deploy.yml # CI/CD: build → ECR → Lambda → S3
├── Dockerfile # Lambda Python 3.11 container
├── requirements.txt # Pinned Python dependencies
├── .dockerignore # Excludes data/notebooks from Docker build
└── .gitignore # Excludes secrets, data, terraform state
- Python 3.11+
- Docker Desktop
- AWS CLI (configured with
aws configure) - Terraform 1.x+
# 1. Clone the repository
git clone https://github.com/Nduka99/image_processing_deployment.git
cd image_processing_deployment
# 2. Install dependencies
pip install -r requirements.txt
# 3. Start the API server
uvicorn api.main:app --host 127.0.0.1 --port 8000
# 4. Open the frontend
# Navigate to http://127.0.0.1:3000 (via a local HTTP server)
# Or open frontend/index.html directly# 1. Initialize and apply Terraform
cd infra
terraform init
terraform apply -auto-approve
# 2. Build and push Docker image
aws ecr get-login-password --region eu-west-2 | docker login --username AWS --password-stdin <ACCOUNT_ID>.dkr.ecr.eu-west-2.amazonaws.com
docker build -t <ECR_URL>:latest ..
docker push <ECR_URL>:latest
# 3. Upload frontend to S3 (with API URL injected)
# The GitHub Actions workflow handles this automatically on push to main| # | Service | Resource | Free Tier Limit |
|---|---|---|---|
| 1-2 | ECR | Container registry + lifecycle policy | 500 MB/month |
| 3-6 | S3 | Bucket + website config + public access + policy | 5 GB, 20K GET/month |
| 7-8 | IAM | Lambda execution role + policy | Always free |
| 9 | Lambda | Container function (1024 MB, 60s) | 1M requests, 400K GB-s/month |
| 10-13 | API Gateway | HTTP API + integration + routes + stage | 1M calls/month |
| 14-15 | SNS | Alert topic + email subscription | 1M publishes/month |
| 16-19 | CloudWatch | 4 alarms (errors, duration, throttles, 5XX) | 10 alarms free |
| 20 | Budgets | Cost guard ($1/month threshold) | Always free |
GitHub Actions (.github/workflows/deploy.yml) triggers on every push to main:
- ✅ Checkout code
- ✅ Authenticate with AWS
- ✅ Build Docker image → Push to ECR
- ✅ Update Lambda function code
- ✅ Inject API Gateway URL into frontend → Sync to S3
Setup: Add AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY as GitHub Secrets in your repository settings.
| Alarm | Triggers When | Action |
|---|---|---|
| Lambda Errors | Any invocation error | Email via SNS |
| Lambda Duration | Average > 50s (timeout = 60s) | Email via SNS |
| Lambda Throttles | Any throttled invocations | Email via SNS |
| API 5XX Errors | 5+ server errors in 5 minutes | Email via SNS |
| Budget Guard | Monthly cost exceeds $1 | Email notification |
| Layer | Technology |
|---|---|
| ML Model | XGBoost (ONNX Runtime) |
| Feature Extraction | OpenCV, scikit-image, mahotas, scipy |
| Backend | FastAPI + AWS Lambda |
| Frontend | Vanilla HTML/CSS/JS |
| Infrastructure | Terraform (IaC) |
| Containerization | Docker (Lambda Python 3.11 base) |
| CI/CD | GitHub Actions |
| Monitoring | CloudWatch + SNS |
| Cloud | AWS (S3, ECR, Lambda, API Gateway) |
This project was developed as part of an Applied AI assessment.
Built with ❤️ using an agentic AI deployment pipeline