Fraud Detection Transaction Platform

This project is a natural progression from a standard payment microservice: it accepts transaction requests, enriches them with real-time behavioral features, scores fraud risk in an isolated ML service, and stores the final decision before the transfer is committed.

The repository is now configured to reuse existing Dockerized infrastructure for Postgres and Redis instead of creating new database or cache containers.

For a full beginner-to-advanced explanation of how the project works, see DOCUMENTATION.md. For a phased implementation plan and upgrade path, see ROADMAP.md. For a beginner-friendly explanation of the trained model pipeline, see ML_MODEL_GUIDE.md.

Architecture

• api/: Go API gateway and transaction decision service
• ml-service/: Python FastAPI inference service
• ml-service/training/: model training pipeline
• ml-service/models/: saved trained model artifacts
• infra/postgres/init.sql: Postgres schema bootstrap
• docker-compose.yml: local stack for the API and ML service, configured to talk to your existing Postgres and Redis containers

Request flow:

1. The Go API receives a transaction request.
2. Redis is queried for recent transaction count, average transfer amount, and recent location history.
3. The compiled feature payload is sent to the ML inference service.
4. Fraud probability is mapped to APPROVED, FLAGGED_FOR_REVIEW, or DENIED.
5. Postgres stores the transaction, features, score, and final status.
6. A decision event is emitted through a publisher abstraction that can later target Kafka, NATS, or SQS.

Selling Points

• Low-latency API design with Redis-backed feature reads
• Cross-service communication via REST between Go and FastAPI
• Event-driven ready design through a pluggable decision publisher
• Model-serving separation that makes it easy to swap heuristic scoring for a trained classifier
• Includes a real trained RandomForestClassifier artifact for demo and learning use

Local Run

Before starting this project, make sure your existing containers are already running:

• Postgres container: go_crud_postgres
• Redis container: redis-server

Then start only the API and ML service:

docker compose up --build

Services started by this repo:

• API: http://localhost:8080
• ML service: http://localhost:8000

External containers reused by this repo:

• Postgres: localhost:5432
• Redis: localhost:6379

The API container connects to those existing services through host.docker.internal, so this assumes your Postgres and Redis containers publish ports 5432 and 6379 to the host.

Example Request

curl -X POST http://localhost:8080/v1/transactions ^
  -H "Content-Type: application/json" ^
  -d "{\"user_id\":\"user-123\",\"source_account\":\"acct-a\",\"destination_account\":\"acct-b\",\"amount\":4200,\"currency\":\"USD\",\"location\":\"IN-BLR\",\"ip_address\":\"203.0.113.7\",\"device_id\":\"device-77\"}"

Example response:

{
  "transaction_id": "4fd7f445-c147-4d0c-9ab3-a4c4a2e51927",
  "status": "FLAGGED_FOR_REVIEW",
  "fraud_score": 0.71,
  "reason": "model score exceeds manual review threshold"
}

Redis Feature Keys

The API expects the following user-scoped keys:

• user:{user_id}:txn_count -> integer recent transaction count
• user:{user_id}:avg_transfer_amount -> float average transfer amount
• user:{user_id}:locations -> list of recent locations

If a key is missing, the service falls back to safe defaults so the platform remains operable in local development.

Existing Infrastructure Assumptions

• Your Postgres container go_crud_postgres is running and exposes 5432
• Your Redis container redis-server is running and exposes 6379
• The appdb database exists in Postgres
• The schema in infra/postgres/init.sql has already been applied, or you will apply it once against the existing database

Environment Variables

API

• PORT default 8080
• DATABASE_URL default postgres://app:app@localhost:5432/appdb?sslmode=disable
• REDIS_ADDR default localhost:6379
• REDIS_PASSWORD default empty
• ML_SERVICE_URL default http://localhost:8000
• DENY_THRESHOLD default 0.85
• REVIEW_THRESHOLD default 0.60

ML Service

• PORT default 8000
• MODEL_PATH path to a serialized sklearn-compatible model with predict_proba

Real ML Model

The repository now includes a real trained RandomForestClassifier pipeline for the ML service.

• training script: ml-service/training/train_model.py
• saved model artifact: fraud_model.joblib
• beginner guide: ML_MODEL_GUIDE.md

The training flow is:

1. Generate synthetic fraud-like transaction examples.
2. Train a RandomForestClassifier on the same feature shape used by the live API.
3. Save the trained model artifact.
4. Load that artifact in the FastAPI service through MODEL_PATH.
5. Use predict_proba(...) during live transaction scoring.

To retrain the model locally:

cd .\ml-service
python .\training\train_model.py

If MODEL_PATH is missing or the file cannot be loaded, the service safely falls back to heuristic scoring.

Important note:

• this is a real ML pipeline and real model inference
• the current dataset is synthetic, so it is suitable for learning, demos, and portfolio use rather than production banking use

API Endpoints

• GET /healthz
• POST /v1/transactions
• GET /v1/transactions/{id}

Next Steps

• Apply infra/postgres/init.sql to your existing go_crud_postgres database if the transactions table does not exist yet
• Replace the heuristic inference fallback with a real Random Forest or XGBoost artifact
• Publish decision events to Kafka or NATS for audit and downstream review queues
• Add gRPC between the API and ML service if you want stricter contracts and lower serialization overhead
• Backfill Redis feature keys from a streaming pipeline or CDC consumer