Revise README for improved clarity and structure

Refactor README for clarity and consistency, updating sections and formatting.

Author: msaad-dot

README.md

@@ -1,28 +1,22 @@
 # Fraud Detection API — FastAPI Inference Service
 
-This project provides a **production-style machine learning inference API**
-for detecting fraudulent credit card transactions.
+A production-style machine learning inference API for detecting fraudulent credit card transactions.
+The API serves a trained XGBoost fraud detection model via FastAPI, containerized with Docker and automatically deployed via a GitHub Actions CI/CD pipeline.
 
-The API serves a trained **XGBoost fraud detection model** via **FastAPI**,
-with strict input validation, feature alignment, and safe inference handling.
-
-The goal of this project is to demonstrate how a trained ML model is
-**exposed, validated, and consumed** in a real-world system — not just trained.
+---
 
 ## Problem Context
 
-Credit card fraud detection is a **highly imbalanced classification problem**,
-where missing a fraudulent transaction is often more costly than flagging
-a legitimate one.
+Credit card fraud detection is a highly imbalanced classification problem, where missing a fraudulent transaction is often more costly than flagging a legitimate one.
 
-In real production systems, models are rarely used directly.
-They must be:
+In real production systems, models are rarely used directly. They must be:
 - Validated
 - Properly preprocessed
 - Safely deployed behind an API
 
 This project focuses on the **serving and inference layer** of a fraud detection system.
 
+---
 
 ## Key Features
 
@@ -34,47 +28,49 @@ This project focuses on the **serving and inference layer** of a fraud detection
 - Clear error handling with meaningful HTTP responses
 - Model metadata endpoint for observability
 - JSON-safe prediction outputs
+- Dockerized for consistent deployment anywhere
+- CI/CD pipeline via GitHub Actions → auto-builds and pushes to Docker Hub on every push
 
+---
 
 ## Project Structure
 
-```text
+```
 fraud-detection-api/
 ├── app/
 │   ├── main.py        # API endpoints
 │   ├── schemas.py     # Request validation schemas
-│   ├── inference.py  # Model inference logic
-│   ├── config.py     # Centralized configuration
+│   ├── inference.py   # Model inference logic
+│   ├── config.py      # Centralized configuration
 │   └── __init__.py
 ├── models/
 │   └── xgboost.pkl
 ├── artifacts/
 │   └── standard_scaler.pkl
+├── .github/
+│   └── workflows/
+│       └── deploy.yml  # CI/CD pipeline
+├── Dockerfile
 └── .gitignore
 ```
 
 ---
 
-## 📌 API Endpoints
+## API Endpoints
 
-```markdown
-### Health Check :
+### `GET /health`
 Returns API health status.
 
-### Model Information :
-Returns model metadata such as:
-- Model name
-- Version
-- Threshold
+### `GET /model-info`
+Returns model metadata:
+- Model name and version
+- Decision threshold
 - Number of features
 
-### Fraud Prediction
-Accepts a full feature vector (Time, Amount, V1–V28) and returns
-a fraud probability and decision.
-```
-
-## Example Prediction Request
+### `POST /predict`
+Accepts a full feature vector (Time, Amount, V1–V28) and returns a fraud probability and decision.
 
+**Example Request:**
 ```json
 {
   "Time": 50000,
@@ -109,30 +105,72 @@ a fraud probability and decision.
   "V28": -0.04
 }
 ```
+
+---
+
+## Running with Docker
+
+Pull and run directly from Docker Hub — no setup required:
+
+```bash
+docker pull saaddot/fraud-detection-api
+docker run -p 8000:8000 saaddot/fraud-detection-api
+```
+
+Then open: `http://localhost:8000/health`
+
+Or build locally:
+```bash
+docker build -t fraud-detection-api .
+docker run -p 8000:8000 fraud-detection-api
+```
+
 ---
 
-## 📌 Design Decisions
+## CI/CD Pipeline
+
+Every push to `main` triggers a GitHub Actions workflow that:
+
+1. Checks out the code on a fresh Ubuntu runner
+2. Logs into Docker Hub using repository secrets
+3. Builds the Docker image
+4. Pushes it to Docker Hub as `saaddot/fraud-detection-api:latest`
 
-```markdown
-- The API expects the **same feature schema used during training**
-  to avoid inference drift.
-- PCA features (V1–V28) are assumed to be computed upstream.
-- Only Time and Amount are scaled during inference.
-- Feature order is explicitly enforced before prediction.
-- Inference logic is separated from API routing and configuration.
 ```
+Push to main
+     ↓
+GitHub Actions (Ubuntu)
+     ↓
+Build Docker image
+     ↓
+Push to Docker Hub ← anyone can pull and run
+```
+
+---
+
+## Design Decisions
+
+- The API expects the **same feature schema used during training** to avoid inference drift
+- PCA features (V1–V28) are assumed to be computed upstream
+- Only Time and Amount are scaled during inference
+- Feature order is explicitly enforced before prediction
+- Inference logic is separated from API routing and configuration
+
+---
 
 ## Tech Stack
 
-- Python
-- FastAPI
-- Pydantic
-- XGBoost
-- Scikit-learn
-- Pandas
+Python · FastAPI · Pydantic · XGBoost · Scikit-learn · Docker · GitHub Actions
+
+---
+
+## Related Projects
+
+- [fraud-detection-ml](https://github.com/msaad-dot/fraud-detection-ml) — Model training pipeline
+- [drift-monitoring](https://github.com/msaad-dot/drift-monitoring) — Data drift monitoring
 
 ---
 
 ## Author
 
-**Mohamed Saad**
+Mohamed Saad — [GitHub](https://github.com/msaad-dot)