# moubarak1ezzyani/retention-ai-api architecture

> Architecture diagram of the GitHub repository moubarak1ezzyani/retention-ai-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/moubarak1ezzyani/retention-ai-api
- Repository: https://github.com/moubarak1ezzyani/retention-ai-api

## Overview

Retention AI is a FastAPI HR decision-support backend: HR users authenticate, submit employee features for churn scoring, and can request a risk-based retention plan. The README also documents prediction-history and health endpoints; utilities are included as a product branch. Source excerpts confirm prediction persistence, while the retention handler's history write is commented out. Unsampled utilities are represented at their exact file path, with relationships limited to indexed references.

Main entry points: [`app/main.py`](https://github.com/moubarak1ezzyani/retention-ai-api/blob/main/app/main.py) (FastAPI app), [`app/api/routers/auth.py`](https://github.com/moubarak1ezzyani/retention-ai-api/blob/main/app/api/routers/auth.py) (Authentication), [`app/api/routers/predict.py`](https://github.com/moubarak1ezzyani/retention-ai-api/blob/main/app/api/routers/predict.py) (Churn prediction), [`app/api/routers/retention.py`](https://github.com/moubarak1ezzyani/retention-ai-api/blob/main/app/api/routers/retention.py) (Plan endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API workflows"]
  node_app["FastAPI app<br/>[main.py]"]
  node_schemas["Request schemas<br/>[schemas.py]"]
  node_utils["Health and history<br/>[utils.py]"]
end

subgraph group_identity["Identity and access"]
  node_auth["Authentication<br/>[auth.py]"]
  node_security["JWT security<br/>[security.py]"]
  node_access["Access dependencies<br/>[dependencies.py]"]
end

subgraph group_decision["Retention decisions"]
  node_predict["Churn prediction<br/>[predict.py]"]
  node_retention["Plan endpoint<br/>[retention.py]"]
  node_ml["ML inference<br/>[ml_service.py]"]
  node_llm["Plan generation<br/>[llm_service.py]"]
end

subgraph group_data["Persistence"]
  node_crud["Database queries<br/>[crud.py]"]
  node_models["Database models<br/>[models.py]"]
  node_database["DB session setup<br/>[database.py]"]
end

node_hr(("HR client"))
node_postgres[("PostgreSQL")]
node_huggingface["Hugging Face API"]

node_hr -->|"sends requests"| node_app
node_app -->|"registers router"| node_auth
node_app -->|"registers router"| node_predict
node_app -->|"registers router"| node_retention
node_app -->|"registers router"| node_utils
node_auth -->|"reads and creates users"| node_crud
node_auth -->|"hashes and verifies"| node_security
node_auth -->|"opens DB session"| node_access
node_access -->|"creates session"| node_database
node_access -->|"loads user"| node_models
node_predict -->|"scores features"| node_ml
node_predict -->|"records prediction"| node_crud
node_predict -->|"requires user and DB"| node_access
node_retention -->|"scores features"| node_ml
node_retention -->|"requests plan"| node_llm
node_retention -->|"requires user and DB"| node_access
node_llm -->|"generates plan"| node_huggingface
node_utils -->|"uses history queries"| node_crud
node_crud -->|"queries records"| node_models
node_models -->|"uses ORM base"| node_database
node_database -->|"connects"| node_postgres
node_app -->|"creates tables"| node_database
node_predict -->|"accepts and returns"| node_schemas
node_retention -->|"accepts and returns"| node_schemas
node_auth -->|"accepts and returns"| node_schemas

click node_app "https://github.com/moubarak1ezzyani/retention-ai-api/blob/main/app/main.py"
click node_auth "https://github.com/moubarak1ezzyani/retention-ai-api/blob/main/app/api/routers/auth.py"
click node_security "https://github.com/moubarak1ezzyani/retention-ai-api/blob/main/app/core/security.py"
click node_access "https://github.com/moubarak1ezzyani/retention-ai-api/blob/main/app/api/dependencies.py"
click node_predict "https://github.com/moubarak1ezzyani/retention-ai-api/blob/main/app/api/routers/predict.py"
click node_retention "https://github.com/moubarak1ezzyani/retention-ai-api/blob/main/app/api/routers/retention.py"
click node_ml "https://github.com/moubarak1ezzyani/retention-ai-api/blob/main/app/services/ml_service.py"
click node_llm "https://github.com/moubarak1ezzyani/retention-ai-api/blob/main/app/services/llm_service.py"
click node_schemas "https://github.com/moubarak1ezzyani/retention-ai-api/blob/main/app/db/schemas.py"
click node_utils "https://github.com/moubarak1ezzyani/retention-ai-api/blob/main/app/api/routers/utils.py"
click node_crud "https://github.com/moubarak1ezzyani/retention-ai-api/blob/main/app/db/crud.py"
click node_models "https://github.com/moubarak1ezzyani/retention-ai-api/blob/main/app/db/models.py"
click node_database "https://github.com/moubarak1ezzyani/retention-ai-api/blob/main/app/db/database.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_app,node_schemas,node_utils,node_hr toneBlue
class node_auth,node_security,node_access,node_postgres toneAmber
class node_predict,node_retention,node_ml,node_llm,node_huggingface toneMint
class node_crud,node_models,node_database toneRose
```

## Components

### API workflows

- [FastAPI app](https://github.com/moubarak1ezzyani/retention-ai-api/blob/main/app/main.py): `app/main.py`
- [Request schemas](https://github.com/moubarak1ezzyani/retention-ai-api/blob/main/app/db/schemas.py): `app/db/schemas.py`
- [Health and history](https://github.com/moubarak1ezzyani/retention-ai-api/blob/main/app/api/routers/utils.py): `app/api/routers/utils.py`

### Identity and access

- [Authentication](https://github.com/moubarak1ezzyani/retention-ai-api/blob/main/app/api/routers/auth.py): `app/api/routers/auth.py`
- [JWT security](https://github.com/moubarak1ezzyani/retention-ai-api/blob/main/app/core/security.py): `app/core/security.py`
- [Access dependencies](https://github.com/moubarak1ezzyani/retention-ai-api/blob/main/app/api/dependencies.py): `app/api/dependencies.py`

### Retention decisions

- [Churn prediction](https://github.com/moubarak1ezzyani/retention-ai-api/blob/main/app/api/routers/predict.py): `app/api/routers/predict.py`
- [Plan endpoint](https://github.com/moubarak1ezzyani/retention-ai-api/blob/main/app/api/routers/retention.py): `app/api/routers/retention.py`
- [ML inference](https://github.com/moubarak1ezzyani/retention-ai-api/blob/main/app/services/ml_service.py): `app/services/ml_service.py`
- [Plan generation](https://github.com/moubarak1ezzyani/retention-ai-api/blob/main/app/services/llm_service.py): `app/services/llm_service.py`

### Persistence

- [Database queries](https://github.com/moubarak1ezzyani/retention-ai-api/blob/main/app/db/crud.py): `app/db/crud.py`
- [Database models](https://github.com/moubarak1ezzyani/retention-ai-api/blob/main/app/db/models.py): `app/db/models.py`
- [DB session setup](https://github.com/moubarak1ezzyani/retention-ai-api/blob/main/app/db/database.py): `app/db/database.py`

### Other components

- **HR client**
- **PostgreSQL**
- **Hugging Face API**

## Connections

- HR client → FastAPI app: sends requests (evidence: `README.md`)
- FastAPI app → Authentication: registers router (evidence: `app/main.py`)
- FastAPI app → Churn prediction: registers router (evidence: `app/main.py`)
- FastAPI app → Plan endpoint: registers router (evidence: `app/main.py`)
- FastAPI app → Health and history: registers router (evidence: `app/main.py`)
- Authentication → Database queries: reads and creates users (evidence: `app/api/routers/auth.py`)
- Authentication → JWT security: hashes and verifies (evidence: `app/api/routers/auth.py`)
- Authentication → Access dependencies: opens DB session (evidence: `app/api/routers/auth.py`)
- Access dependencies → DB session setup: creates session (evidence: `app/api/dependencies.py`)
- Access dependencies → Database models: loads user (evidence: `app/api/dependencies.py`)
- Churn prediction → ML inference: scores features (evidence: `app/api/routers/predict.py`)
- Churn prediction → Database queries: records prediction (evidence: `app/api/routers/predict.py`)
- Churn prediction → Access dependencies: requires user and DB (evidence: `app/api/routers/predict.py`)
- Plan endpoint → ML inference: scores features (evidence: `app/api/routers/retention.py`)
- Plan endpoint → Plan generation: requests plan (evidence: `app/api/routers/retention.py`)
- Plan endpoint → Access dependencies: requires user and DB (evidence: `app/api/routers/retention.py`)
- Plan generation → Hugging Face API: generates plan (evidence: `app/services/llm_service.py`)
- Health and history → Database queries: uses history queries (evidence: `app/api/routers/utils.py`)
- Database queries → Database models: queries records (evidence: `app/db/crud.py`)
- Database models → DB session setup: uses ORM base (evidence: `app/db/models.py`)
- DB session setup → PostgreSQL: connects (evidence: `app/db/database.py`)
- FastAPI app → DB session setup: creates tables (evidence: `app/main.py`)
- Churn prediction → Request schemas: accepts and returns (evidence: `app/api/routers/predict.py`)
- Plan endpoint → Request schemas: accepts and returns (evidence: `app/api/routers/retention.py`)
- Authentication → Request schemas: accepts and returns (evidence: `app/api/routers/auth.py`)