# basteprince2/pdad-ml-service architecture

> Architecture diagram of the GitHub repository basteprince2/pdad-ml-service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/basteprince2/pdad-ml-service
- Repository: https://github.com/basteprince2/pdad-ml-service

## Overview

This repository is a FastAPI ML service consumed by the Laravel PDAD application. The principal workflows accept a profile, validate the request, then either predict an employment type or rank supplied jobs; the recommender applies employment-type and disability-compatibility filtering before TF-IDF similarity ranking. Model artifacts are loaded at startup. README-documented rate limiting, timeout handling, and structured logging are included, though their implementation details are only partially visible in the sampled source.

Main entry points: [`main.py`](https://github.com/basteprince2/pdad-ml-service/blob/main/main.py) (FastAPI endpoints), [`models/recommender.py`](https://github.com/basteprince2/pdad-ml-service/blob/main/models/recommender.py) (Recommendation engine), [`models/predictor.py`](https://github.com/basteprince2/pdad-ml-service/blob/main/models/predictor.py) (Random Forest predictor), [`schemas.py`](https://github.com/basteprince2/pdad-ml-service/blob/main/schemas.py) (Prediction or recommendations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP service"]
  node_api["FastAPI endpoints<br/>[main.py]"]
  node_schemas["Request schemas<br/>[schemas.py]"]
  node_health["Health status<br/>[main.py]"]
  node_response["Prediction or recommendations<br/>[schemas.py]"]
end

subgraph group_prediction["Employment prediction"]
  node_validator["Vocabulary validation<br/>[validator.py]"]
  node_predictor["Random Forest predictor<br/>[predictor.py]"]
  node_model_artifacts["Model artifacts"]
end

subgraph group_recommendation["Job recommendation"]
  node_recommender["Recommendation engine<br/>[recommender.py]"]
  node_type_filter["Employment-type filter<br/>[recommender.py]"]
  node_compatibility["Disability compatibility<br/>[recommender.py]"]
  node_tfidf["TF-IDF ranking<br/>[recommender.py]"]
end

subgraph group_operations["Runtime operations"]
  node_limiter["IP rate limiter<br/>[main.py]"]
  node_logging["Structured logging<br/>[main.py]"]
  node_config["Service configuration<br/>[config.py]"]
end

node_laravel(("Laravel application"))

node_laravel -->|"sends profile/jobs"| node_api
node_api -->|"validates payload"| node_schemas
node_api -->|"checks request"| node_limiter
node_api -->|"validates vocabulary"| node_validator
node_api -->|"requests prediction"| node_predictor
node_predictor -->|"loads model data"| node_model_artifacts
node_api -->|"requests ranking"| node_recommender
node_recommender -->|"filters employment type"| node_type_filter
node_recommender -->|"checks compatibility"| node_compatibility
node_recommender -->|"ranks remaining jobs"| node_tfidf
node_api -->|"serves status"| node_health
node_api -->|"writes request logs"| node_logging
node_config -->|"configures service"| node_api
node_predictor -->|"returns prediction"| node_response
node_recommender -->|"returns recommendations"| node_response
node_api -->|"returns HTTP result"| node_laravel

click node_api "https://github.com/basteprince2/pdad-ml-service/blob/main/main.py"
click node_schemas "https://github.com/basteprince2/pdad-ml-service/blob/main/schemas.py"
click node_health "https://github.com/basteprince2/pdad-ml-service/blob/main/main.py"
click node_limiter "https://github.com/basteprince2/pdad-ml-service/blob/main/main.py"
click node_logging "https://github.com/basteprince2/pdad-ml-service/blob/main/main.py"
click node_config "https://github.com/basteprince2/pdad-ml-service/blob/main/config.py"
click node_validator "https://github.com/basteprince2/pdad-ml-service/blob/main/models/validator.py"
click node_predictor "https://github.com/basteprince2/pdad-ml-service/blob/main/models/predictor.py"
click node_model_artifacts "https://github.com/basteprince2/pdad-ml-service/tree/main/artifacts"
click node_recommender "https://github.com/basteprince2/pdad-ml-service/blob/main/models/recommender.py"
click node_type_filter "https://github.com/basteprince2/pdad-ml-service/blob/main/models/recommender.py"
click node_compatibility "https://github.com/basteprince2/pdad-ml-service/blob/main/models/recommender.py"
click node_tfidf "https://github.com/basteprince2/pdad-ml-service/blob/main/models/recommender.py"
click node_response "https://github.com/basteprince2/pdad-ml-service/blob/main/schemas.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_api,node_schemas,node_health,node_response toneBlue
class node_validator,node_predictor,node_model_artifacts toneAmber
class node_recommender,node_type_filter,node_compatibility,node_tfidf toneMint
class node_limiter,node_logging,node_config toneRose
class node_laravel toneIndigo
```

## Components

### HTTP service

- [FastAPI endpoints](https://github.com/basteprince2/pdad-ml-service/blob/main/main.py): `main.py`
- [Request schemas](https://github.com/basteprince2/pdad-ml-service/blob/main/schemas.py): `schemas.py`
- [Health status](https://github.com/basteprince2/pdad-ml-service/blob/main/main.py): `main.py`
- [Prediction or recommendations](https://github.com/basteprince2/pdad-ml-service/blob/main/schemas.py): `schemas.py`

### Employment prediction

- [Vocabulary validation](https://github.com/basteprince2/pdad-ml-service/blob/main/models/validator.py): `models/validator.py`
- [Random Forest predictor](https://github.com/basteprince2/pdad-ml-service/blob/main/models/predictor.py): `models/predictor.py`
- [Model artifacts](https://github.com/basteprince2/pdad-ml-service/tree/main/artifacts): `artifacts`

### Job recommendation

- [Recommendation engine](https://github.com/basteprince2/pdad-ml-service/blob/main/models/recommender.py): `models/recommender.py`
- [Employment-type filter](https://github.com/basteprince2/pdad-ml-service/blob/main/models/recommender.py): `models/recommender.py`
- [Disability compatibility](https://github.com/basteprince2/pdad-ml-service/blob/main/models/recommender.py): `models/recommender.py`
- [TF-IDF ranking](https://github.com/basteprince2/pdad-ml-service/blob/main/models/recommender.py): `models/recommender.py`

### Runtime operations

- [IP rate limiter](https://github.com/basteprince2/pdad-ml-service/blob/main/main.py): `main.py`
- [Structured logging](https://github.com/basteprince2/pdad-ml-service/blob/main/main.py): `main.py`
- [Service configuration](https://github.com/basteprince2/pdad-ml-service/blob/main/config.py): `config.py`

### Other components

- **Laravel application**

## Connections

- Laravel application → FastAPI endpoints: sends profile/jobs
- FastAPI endpoints → Request schemas: validates payload
- FastAPI endpoints → IP rate limiter: checks request
- FastAPI endpoints → Vocabulary validation: validates vocabulary
- FastAPI endpoints → Random Forest predictor: requests prediction
- Random Forest predictor → Model artifacts: loads model data
- FastAPI endpoints → Recommendation engine: requests ranking
- Recommendation engine → Employment-type filter: filters employment type
- Recommendation engine → Disability compatibility: checks compatibility
- Recommendation engine → TF-IDF ranking: ranks remaining jobs
- FastAPI endpoints → Health status: serves status
- FastAPI endpoints → Structured logging: writes request logs
- Service configuration → FastAPI endpoints: configures service
- Random Forest predictor → Prediction or recommendations: returns prediction
- Recommendation engine → Prediction or recommendations: returns recommendations
- FastAPI endpoints → Laravel application: returns HTTP result