# vinayak251104/fraud_guard_api architecture

> Architecture diagram of the GitHub repository vinayak251104/fraud_guard_api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vinayak251104/fraud_guard_api
- Repository: https://github.com/vinayak251104/fraud_guard_api

## Overview

1. **System shape**
   - This repo is a two-service architecture: a **Node.js/Express REST API** acts as the public entrypoint, and a separate **Python/FastAPI ML service** performs fraud inference.
   - The services communicate over **HTTP**. The Node app is the only component exposed for CRUD and client-facing API actions; the Python service is the internal scoring engine.

2. **Request/response flow**
   - A client sends transaction features to **Express `POST /predict`**.
   - Express forwards the payload to **FastAPI `POST /predict`** using the `ML_URL` environment variable.
   - FastAPI loads the serialized model, computes a **risk score / decision**, and returns that to Express.
   - Express then persists a prediction log to MongoDB and returns the final response to the client.

3. **Express application boundary**
   - `server.js` is the Node process entrypoint: it connects to MongoDB and starts the Express server.
   - `app.js` appears to configure the Express app and middleware.
   - `routers/userRouter.js` defines the API routes, and `controllers/userController.js` holds the business logic for prediction requests and log CRUD.
   - Despite the `user*` naming, the service is actually centered on **fraud prediction logging**, not user management.

4. **Persistence layer**
   - `models/userModel.js` is a **Mongoose schema/model** for storing prediction logs.
   - MongoDB is used as the system of record for prediction history, including create/read/update/delete operations exposed through the Express API.
   - The README indicates **MongoDB Atlas** as the runtime database, so persistence is externalized from the app containers.

5. **ML inference service**
   - `api.py` is the FastAPI app that receives transaction features and runs model inference.
   - It loads `model_credit_card.joblib`, which is the serialized **Random Forest** model used in production.
   - This service is stateless aside from loading the model into memory; it does not appear to own persistence responsibilities.

6. **Model artifact boundary**
   - `model_credit_card.joblib` is the handoff artifact between offline training and online inference.
   - The model is trained offline, then packaged into the repo for deployment so the FastAPI service can serve predictions without retraining.

7. **Training pipeline**
   - `train_model.py` is an offline ML workflow for experimentation and model selection.
   - The README says it evaluates multiple models and selected **Random Forest** as the final model due to class imbalance handling and recall/precision tradeoff.
   - This script is separate from the serving path; it produces the serialized model consumed by FastAPI.

8. **Key technical stack boundaries**
   - **Node.js/Express**: public API, routing, controller orchestration, DB logging.
   - **Python/FastAPI + Uvicorn**: ML inference service.
   - **scikit-learn / joblib**: model training and serialization.
   - **Mongoose / MongoDB Atlas**: log persistence.
   - The architecture intentionally splits API concerns from ML concerns, which keeps the serving layers independently deployable.

9. **Operational/deployment model**
   - The README describes **two Render services**: one for the FastAPI ML service and one for the Express API.
   - Environment variables are important architecture inputs: `ML_URL` connects Express to the ML service, and `DATABASE`/`DATABASE_PASSWORD` connect Express to MongoDB.
   - This means the public API depends on both the database and the ML service at runtime.

10. **Architecture diagram cues**
   - Draw the client hitting **Express** first, not FastAPI.
   - Show **Express → FastAPI → joblib model** for scoring.
   - Show **Express → MongoDB Atlas** for logging and CRUD on prediction records.
   - Keep the training script and model artifact as a separate offline lane feeding the inference service, not part of the online request path.

Main entry points: [`server.js`](https://github.com/vinayak251104/fraud_guard_api/blob/main/server.js) (server.js), [`controllers/userController.js`](https://github.com/vinayak251104/fraud_guard_api/blob/main/controllers/userController.js) (Controller), [`api.py`](https://github.com/vinayak251104/fraud_guard_api/blob/main/api.py) (api.py), [`app.js`](https://github.com/vinayak251104/fraud_guard_api/blob/main/app.js) (app.js)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_api["Express API"]
  node_server_js["server.js<br/>node entrypoint<br/>[server.js]"]
  node_app_js["app.js<br/>express app<br/>[app.js]"]
  node_router["Routes<br/>[userRouter.js]"]
  node_controller["Controller<br/>request logic<br/>[userController.js]"]
  node_ml_url["ML_URL<br/>env config"]
  node_db_env["DB env<br/>env config"]
end

subgraph group_g_ml["ML Service"]
  node_fastapi["api.py<br/>fastapi service<br/>[api.py]"]
  node_model_artifact["joblib model<br/>serialized RF model"]
end

subgraph group_g_offline["Offline Training"]
  node_train_model["train_model.py<br/>training pipeline<br/>[train_model.py]"]
end

subgraph group_g_data["Persistence"]
  node_mongo_model[("Prediction log<br/>mongoose model<br/>[userModel.js]")]
  node_mongo[("MongoDB Atlas<br/>database")]
end

node_client(("Client<br/>external actor"))

node_client -->|"POST /predict"| node_server_js
node_server_js -->|"boot"| node_app_js
node_app_js -->|"mounts"| node_router
node_router -->|"dispatches"| node_controller
node_controller -->|"HTTP predict"| node_fastapi
node_fastapi -->|"loads"| node_model_artifact
node_controller -->|"logs"| node_mongo_model
node_mongo_model -->|"stores"| node_mongo
node_server_js -->|"connects"| node_mongo
node_train_model -.->|"produces"| node_model_artifact
node_fastapi -->|"score response"| node_client
node_controller -.->|"uses"| node_ml_url
node_server_js -.->|"uses"| node_db_env

click node_server_js "https://github.com/vinayak251104/fraud_guard_api/blob/main/server.js"
click node_app_js "https://github.com/vinayak251104/fraud_guard_api/blob/main/app.js"
click node_router "https://github.com/vinayak251104/fraud_guard_api/blob/main/routers/userRouter.js"
click node_controller "https://github.com/vinayak251104/fraud_guard_api/blob/main/controllers/userController.js"
click node_mongo_model "https://github.com/vinayak251104/fraud_guard_api/blob/main/models/userModel.js"
click node_fastapi "https://github.com/vinayak251104/fraud_guard_api/blob/main/api.py"
click node_model_artifact "https://github.com/vinayak251104/fraud_guard_api/blob/main/model_credit_card.joblib"
click node_train_model "https://github.com/vinayak251104/fraud_guard_api/blob/main/train_model.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server_js,node_app_js,node_router,node_controller,node_ml_url,node_db_env toneBlue
class node_fastapi,node_model_artifact toneAmber
class node_train_model toneMint
class node_mongo_model,node_mongo toneRose
class node_client toneNeutral
```

## Components

### Express API

Public Node.js entrypoint for prediction requests and log CRUD

- [server.js](https://github.com/vinayak251104/fraud_guard_api/blob/main/server.js): node entrypoint · Starts the Express server and connects persistence · `server.js`
- [app.js](https://github.com/vinayak251104/fraud_guard_api/blob/main/app.js): express app · Configures middleware and application wiring · `app.js`
- [Routes](https://github.com/vinayak251104/fraud_guard_api/blob/main/routers/userRouter.js): HTTP routes · Defines API endpoints for prediction and logs · `routers/userRouter.js`
- [Controller](https://github.com/vinayak251104/fraud_guard_api/blob/main/controllers/userController.js): request logic · Orchestrates prediction forwarding and CRUD actions · `controllers/userController.js`
- **ML_URL**: env config · Connects Express to the FastAPI scoring service
- **DB env**: env config · Database connection settings for Express

### ML Service

FastAPI scoring service and serialized model

- [api.py](https://github.com/vinayak251104/fraud_guard_api/blob/main/api.py): fastapi service · Receives features and returns fraud scores · `api.py`
- [joblib model](https://github.com/vinayak251104/fraud_guard_api/blob/main/model_credit_card.joblib): serialized RF model · Offline-trained model loaded into memory for inference · `model_credit_card.joblib`

### Offline Training

Model selection and artifact creation pipeline

- [train_model.py](https://github.com/vinayak251104/fraud_guard_api/blob/main/train_model.py): training pipeline · Offline model evaluation and selection workflow · `train_model.py`

### Persistence

MongoDB-backed prediction history

- [Prediction log](https://github.com/vinayak251104/fraud_guard_api/blob/main/models/userModel.js): mongoose model · Schema and model for stored prediction records · `models/userModel.js`
- **MongoDB Atlas**: database · System of record for prediction history

### Other components

- **Client**: external actor · Sends transactions to the public API

## Connections

- Client → server.js: POST /predict · Client submits transaction features to the public API
- server.js → app.js: boot · Entry point initializes the Express app
- app.js → Routes: mounts · Application wires in HTTP routes
- Routes → Controller: dispatches · Routes hand requests to controller logic
- Controller → api.py: HTTP predict · Forwards prediction payload to the ML service via ML_URL
- api.py → joblib model: loads · Inference service loads the serialized model into memory
- Controller → Prediction log: logs · Persists prediction records through the Mongoose model
- Prediction log → MongoDB Atlas: stores · Writes prediction history to MongoDB Atlas
- server.js → MongoDB Atlas: connects · Node process establishes the database connection
- train_model.py → joblib model: produces · Offline training workflow creates the deployable model artifact
- api.py → Client: score response · Returns risk score or decision back through the API chain
- Controller → ML_URL: uses · Controller reads endpoint configuration from environment
- server.js → DB env: uses · Server reads database connection settings from environment
