# asantemaicenne/fake-job-detection-system architecture

> Architecture diagram of the GitHub repository asantemaicenne/fake-job-detection-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/asantemaicenne/fake-job-detection-system
- Repository: https://github.com/asantemaicenne/fake-job-detection-system

## Overview

This is an AI platform for detecting fraudulent job advertisements. Its principal workflow accepts and validates a posting, persists it, engineers NLP and heuristic features, produces a fraud prediction with explanations, and stores results for review and querying. Separate branches cover model training, human feedback, authentication, and Prometheus observability. The graph uses README-documented capabilities where implementation excerpts are incomplete; those links are cited to the README rather than implying unsampled code was inspected.

Main entry points: [`src/api/endpoints/analysis.py`](https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/api/endpoints/analysis.py) (Analysis API), [`src/api/main.py`](https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/api/main.py) (FastAPI Gateway), [`src/models/training/trainer.py`](https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/models/training/trainer.py) (Model Trainer), [`src/features/extractors.py`](https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/features/extractors.py) (Feature Engineering)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and Security"]
  node_gateway["FastAPI Gateway<br/>[main.py]"]
  node_analysis_api["Analysis API<br/>[analysis.py]"]
  node_auth["JWT and RBAC<br/>[auth.py]"]
end

subgraph group_analysis["Detection Pipeline"]
  node_schemas["Job Validation<br/>[models.py]"]
  node_features["Feature Engineering<br/>[extractors.py]"]
  node_safeguards["XAI and HITL<br/>[safeguards.py]"]
end

subgraph group_ml["Model Lifecycle"]
  node_inference["Fraud Inference"]
  node_training["Model Trainer<br/>[trainer.py]"]
  node_preprocessing["Training Preprocessing<br/>[preprocessing.py]"]
  node_train_script["Training Workflow<br/>[train_model.py]"]
  node_evaluation["Model Metrics<br/>[metrics.py]"]
  node_artifact["Model Artifacts"]
end

subgraph group_data["Data Management"]
  node_database_manager["Database Repository<br/>[database.py]"]
  node_mongo[("MongoDB")]
  node_raw_jobs[("Raw Postings<br/>[database.py]")]
  node_job_features[("Feature Records<br/>[database.py]")]
  node_predictions[("Prediction Records<br/>[database.py]")]
  node_feedback[("Review Feedback<br/>[database.py]")]
end

subgraph group_ops["Operations"]
  node_metrics["Metrics Middleware<br/>[metrics.py]"]
  node_prometheus["Prometheus<br/>[prometheus.yml]"]
end

node_client(("API Client"))

node_client -->|"submits requests"| node_gateway
node_gateway -->|"routes analysis"| node_analysis_api
node_gateway -->|"issues tokens"| node_auth
node_analysis_api -->|"checks roles"| node_auth
node_analysis_api -->|"validates postings"| node_schemas
node_analysis_api -->|"stores postings"| node_raw_jobs
node_analysis_api -->|"generates features"| node_features
node_features -->|"builds feature records"| node_schemas
node_features -->|"queries posting history"| node_raw_jobs
node_analysis_api -->|"stores features"| node_job_features
node_analysis_api -->|"scores features"| node_inference
node_analysis_api -->|"routes uncertain cases"| node_safeguards
node_analysis_api -->|"stores predictions"| node_predictions
node_analysis_api -->|"stores review labels"| node_feedback
node_analysis_api -->|"queries results"| node_predictions
node_train_script -->|"runs tuning"| node_training
node_train_script -->|"uses feature extraction"| node_features
node_training -->|"builds pipeline"| node_preprocessing
node_training -->|"persists model"| node_artifact
node_training -.->|"evaluates model"| node_evaluation
node_database_manager -->|"connects and indexes"| node_mongo
node_metrics -.->|"exports metrics"| node_prometheus
node_gateway -.->|"instruments requests"| node_metrics

click node_gateway "https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/api/main.py"
click node_analysis_api "https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/api/endpoints/analysis.py"
click node_auth "https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/api/middleware/auth.py"
click node_schemas "https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/data/schemas/models.py"
click node_features "https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/features/extractors.py"
click node_safeguards "https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/models/ethics/safeguards.py"
click node_inference "https://github.com/asantemaicenne/fake-job-detection-system/tree/main/src/models/inference"
click node_training "https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/models/training/trainer.py"
click node_preprocessing "https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/models/training/preprocessing.py"
click node_train_script "https://github.com/asantemaicenne/fake-job-detection-system/blob/main/scripts/train_model.py"
click node_evaluation "https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/models/evaluation/metrics.py"
click node_artifact "https://github.com/asantemaicenne/fake-job-detection-system/tree/main/src/models/artifacts"
click node_database_manager "https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/data/repositories/database.py"
click node_raw_jobs "https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/data/repositories/database.py"
click node_job_features "https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/data/repositories/database.py"
click node_predictions "https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/data/repositories/database.py"
click node_feedback "https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/data/repositories/database.py"
click node_metrics "https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/api/middleware/metrics.py"
click node_prometheus "https://github.com/asantemaicenne/fake-job-detection-system/blob/main/configs/prometheus.yml"

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_gateway,node_analysis_api,node_auth,node_client toneBlue
class node_schemas,node_features,node_safeguards toneAmber
class node_inference,node_training,node_preprocessing,node_train_script,node_evaluation,node_artifact toneMint
class node_database_manager,node_mongo,node_raw_jobs,node_job_features,node_predictions,node_feedback toneRose
class node_metrics,node_prometheus toneIndigo
```

## Components

### API and Security

- [FastAPI Gateway](https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/api/main.py): `src/api/main.py`
- [Analysis API](https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/api/endpoints/analysis.py): `src/api/endpoints/analysis.py`
- [JWT and RBAC](https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/api/middleware/auth.py): `src/api/middleware/auth.py`

### Detection Pipeline

- [Job Validation](https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/data/schemas/models.py): `src/data/schemas/models.py`
- [Feature Engineering](https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/features/extractors.py): `src/features/extractors.py`
- [XAI and HITL](https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/models/ethics/safeguards.py): `src/models/ethics/safeguards.py`

### Model Lifecycle

- [Fraud Inference](https://github.com/asantemaicenne/fake-job-detection-system/tree/main/src/models/inference): `src/models/inference`
- [Model Trainer](https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/models/training/trainer.py): `src/models/training/trainer.py`
- [Training Preprocessing](https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/models/training/preprocessing.py): `src/models/training/preprocessing.py`
- [Training Workflow](https://github.com/asantemaicenne/fake-job-detection-system/blob/main/scripts/train_model.py): `scripts/train_model.py`
- [Model Metrics](https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/models/evaluation/metrics.py): `src/models/evaluation/metrics.py`
- [Model Artifacts](https://github.com/asantemaicenne/fake-job-detection-system/tree/main/src/models/artifacts): `src/models/artifacts`

### Data Management

- [Database Repository](https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/data/repositories/database.py): `src/data/repositories/database.py`
- **MongoDB**
- [Raw Postings](https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/data/repositories/database.py): `src/data/repositories/database.py`
- [Feature Records](https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/data/repositories/database.py): `src/data/repositories/database.py`
- [Prediction Records](https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/data/repositories/database.py): `src/data/repositories/database.py`
- [Review Feedback](https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/data/repositories/database.py): `src/data/repositories/database.py`

### Operations

- [Metrics Middleware](https://github.com/asantemaicenne/fake-job-detection-system/blob/main/src/api/middleware/metrics.py): `src/api/middleware/metrics.py`
- [Prometheus](https://github.com/asantemaicenne/fake-job-detection-system/blob/main/configs/prometheus.yml): `configs/prometheus.yml`

### Other components

- **API Client**

## Connections

- API Client → FastAPI Gateway: submits requests (evidence: `README.md`)
- FastAPI Gateway → Analysis API: routes analysis (evidence: `README.md`)
- FastAPI Gateway → JWT and RBAC: issues tokens (evidence: `src/api/main.py`)
- Analysis API → JWT and RBAC: checks roles (evidence: `src/api/endpoints/analysis.py`)
- Analysis API → Job Validation: validates postings (evidence: `src/api/endpoints/analysis.py`)
- Analysis API → Raw Postings: stores postings (evidence: `src/api/endpoints/analysis.py`)
- Analysis API → Feature Engineering: generates features (evidence: `src/api/endpoints/analysis.py`)
- Feature Engineering → Job Validation: builds feature records (evidence: `src/features/extractors.py`)
- Feature Engineering → Raw Postings: queries posting history (evidence: `src/features/extractors.py`)
- Analysis API → Feature Records: stores features (evidence: `src/api/endpoints/analysis.py`)
- Analysis API → Fraud Inference: scores features (evidence: `README.md`)
- Analysis API → XAI and HITL: routes uncertain cases (evidence: `src/api/endpoints/analysis.py`)
- Analysis API → Prediction Records: stores predictions (evidence: `src/api/endpoints/analysis.py`)
- Analysis API → Review Feedback: stores review labels (evidence: `README.md`)
- Analysis API → Prediction Records: queries results (evidence: `README.md`)
- Training Workflow → Model Trainer: runs tuning (evidence: `scripts/train_model.py`)
- Training Workflow → Feature Engineering: uses feature extraction (evidence: `scripts/train_model.py`)
- Model Trainer → Training Preprocessing: builds pipeline (evidence: `src/models/training/trainer.py`)
- Model Trainer → Model Artifacts: persists model (evidence: `src/models/training/trainer.py`)
- Model Trainer → Model Metrics: evaluates model
- Database Repository → MongoDB: connects and indexes (evidence: `src/data/repositories/database.py`)
- Metrics Middleware → Prometheus: exports metrics (evidence: `README.md`)
- FastAPI Gateway → Metrics Middleware: instruments requests (evidence: `README.md`)
