# rohit-dhade/pre-delinquency-intervention-engine architecture

> Architecture diagram of the GitHub repository rohit-dhade/pre-delinquency-intervention-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rohit-dhade/pre-delinquency-intervention-engine
- Repository: https://github.com/rohit-dhade/pre-delinquency-intervention-engine

## Overview

1. **Repository split**
   - This repo is a two-service system: a Python **Delinquency_Engine** for scoring risk, and a Node.js **Intervention_Engine** for deciding and sending customer outreach.
   - They communicate over HTTP, while both rely on the same PostgreSQL-backed operational data.

2. **Delinquency Engine boundary**
   - The FastAPI service is the ML inference layer.
   - Its job is to fetch features, run the XGBoost classifier, generate SHAP-based explanations, and optionally trigger intervention downstream.

3. **Prediction data flow**
   - Customer data originates in PostgreSQL tables such as `customers`, `transactions`, and `payment_events`.
   - Daily feature SQL produces engineered features, which are materialized into a Feast online store.
   - The FastAPI endpoint `/predict/{customer_id}` reads from Feast, scores delinquency probability, and returns the prediction plus explanations.

4. **Modeling and explainability**
   - The trained artifacts are packaged directly in the backend: `xgb_model_latest.joblib`, `shap_explainer.joblib`, and `model_feature_names.joblib`.
   - SHAP identifies the main drivers of risk, and those top reasons are converted into human-readable text via Mistral-backed explanation generation.

5. **Feature store subsystem**
   - Feast is the feature-serving boundary between raw transactional data and model inference.
   - The offline source is a Parquet snapshot under `feast_repo/data/`, while the online store is a local SQLite DB used for low-latency point lookups by `customer_id`.
   - The Feast repo also defines the entity and feature views that keep training and serving aligned.

6. **Feature pipeline and orchestration**
   - The `scripts/` directory contains the data and ML pipeline: synthetic data generation, SQL feature computation, Feast materialization, traffic simulation, and weekly retraining.
   - Airflow runs the daily feature pipeline DAG, while `weekly_retrain.py` handles retraining gates and model hot-reload.

7. **Intervention Engine boundary**
   - The Node.js service is the business-action layer.
   - It receives a delinquency signal, applies policy rules, chooses an offer, generates messaging, sends email, and logs the outcome.

8. **Intervention decision pipeline**
   - `tierRouter` converts probability into risk tiers like stable, watch, moderate, and critical.
   - `offerEngine` maps the tier plus customer context to a relief product.
   - `channelRouter` determines urgency and routing, and `messageGenerator` produces the customer-facing message.

9. **Messaging and delivery**
   - Intervention emails are generated with Mistral AI, then wrapped in branded HTML and delivered through Nodemailer using Gmail SMTP.
   - If AI generation fails, the service falls back to predefined templates, so email delivery is not dependent on the model being available.

10. **Shared persistence**
   - PostgreSQL is the system’s state backbone.
   - The Delinquency Engine owns the source and feature tables plus retraining audit logs.
   - The Intervention Engine writes to `intervention_log` and `outcome_log`, which track outreach actions and customer responses.

11. **Service-to-service coupling**
   - The coupling is intentionally narrow: FastAPI calls the Intervention Engine only when the delinquency probability crosses the trigger threshold.
   - FastAPI also exposes proxy routes for intervention stats, history, and health, so the prediction API acts as the primary integration point for the platform.

12. **External dependencies that matter architecturally**
   - Mistral AI is used in both services, but for different concerns: explainability in the prediction service and message generation in the intervention service.
   - Gmail SMTP is the actual outbound delivery channel, and Docker is used for PostgreSQL and the Python deployment path.
   - The whole system is designed around batch feature computation plus low-latency online scoring and automated outbound intervention.

Main entry points: [`Delinquency_Engine/FastApi_Backend/main.py`](https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Delinquency_Engine/FastApi_Backend/main.py) (FastAPI API), [`Intervention_Engine/src/services/messageGenerator.js`](https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Intervention_Engine/src/services/messageGenerator.js) (Message Generator), [`Intervention_Engine/src/routes/intervention.js`](https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Intervention_Engine/src/routes/intervention.js) (Intervention Route), [`Delinquency_Engine/feast_repo/feature_store.yaml`](https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Delinquency_Engine/feast_repo/feature_store.yaml) (Feature Store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_delinquency["Delinquency Engine"]
  node_node_main_api["FastAPI API<br/>python service<br/>[main.py]"]
  node_node_feature_store[("Feature Store<br/>feast serving<br/>[feature_store.yaml]")]
  node_node_feast_features["Entity Views<br/>feast definitions<br/>[features.py]"]
  node_node_feature_scripts["Feature Pipeline<br/>sql+python pipeline<br/>[feature_sql.sql]"]
  node_node_airflow_dag["Airflow DAG<br/>orchestration"]
  node_node_xgb_model["XGBoost Model<br/>trained artifact"]
  node_node_shap_explainer["SHAP Explainer<br/>explainability artifact"]
  node_node_llm_response["Explanation LLM<br/>llm adapter<br/>[llm_response.py]"]
end

subgraph group_group_intervention["Intervention Engine"]
  node_node_intervention_route["Intervention Route<br/>express route<br/>[intervention.js]"]
  node_node_tier_router["Tier Router<br/>decisioning<br/>[tierRouter.js]"]
  node_node_offer_engine["Offer Engine<br/>policy engine<br/>[offerEngine.js]"]
  node_node_channel_router["Channel Router<br/>routing<br/>[channelRouter.js]"]
  node_node_message_generator["Message Generator<br/>messaging"]
  node_node_mailer["Mailer<br/>email delivery<br/>[mailer.js]"]
  node_node_templates["Templates<br/>fallback content<br/>[templates.js]"]
  node_node_html_wrapper["HTML Wrapper<br/>email formatting<br/>[htmlWrapper.js]"]
end

subgraph group_group_external["Shared Systems"]
  node_node_postgres[("PostgreSQL<br/>operational store")]
  node_node_mistral(("Mistral AI<br/>external llm"))
  node_node_gmail(("Gmail SMTP<br/>delivery service"))
end

node_node_postgres -->|"raw data"| node_node_feature_scripts
node_node_feature_scripts -->|"scheduled by"| node_node_airflow_dag
node_node_airflow_dag -->|"materializes"| node_node_feature_store
node_node_feast_features -->|"defines"| node_node_feature_store
node_node_feature_store -->|"serves features"| node_node_main_api
node_node_xgb_model -->|"scores"| node_node_main_api
node_node_shap_explainer -->|"explains"| node_node_main_api
node_node_llm_response -->|"uses"| node_node_mistral
node_node_main_api -->|"summarizes risk"| node_node_llm_response
node_node_main_api -->|"triggers"| node_node_intervention_route
node_node_main_api -->|"reads/writes"| node_node_postgres
node_node_intervention_route -->|"routes by risk"| node_node_tier_router
node_node_tier_router -->|"selects offer"| node_node_offer_engine
node_node_offer_engine -->|"prepares outreach"| node_node_channel_router
node_node_channel_router -->|"requests message"| node_node_message_generator
node_node_message_generator -->|"drafts with"| node_node_mistral
node_node_message_generator -->|"fallbacks to"| node_node_templates
node_node_message_generator -->|"formats"| node_node_html_wrapper
node_node_html_wrapper -->|"delivers"| node_node_mailer
node_node_mailer -->|"sends via"| node_node_gmail
node_node_intervention_route -->|"logs"| node_node_postgres

click node_node_main_api "https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Delinquency_Engine/FastApi_Backend/main.py"
click node_node_feature_store "https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Delinquency_Engine/feast_repo/feature_store.yaml"
click node_node_feast_features "https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Delinquency_Engine/feast_repo/features.py"
click node_node_feature_scripts "https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Delinquency_Engine/scripts/feature_sql.sql"
click node_node_airflow_dag "https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Delinquency_Engine/airflow/dags/delinquency_feature_pipeline.py"
click node_node_xgb_model "https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Delinquency_Engine/FastApi_Backend/xgb_model_latest.joblib"
click node_node_shap_explainer "https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Delinquency_Engine/FastApi_Backend/shap_explainer.joblib"
click node_node_llm_response "https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Delinquency_Engine/FastApi_Backend/app/llm_response.py"
click node_node_intervention_route "https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Intervention_Engine/src/routes/intervention.js"
click node_node_tier_router "https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Intervention_Engine/src/services/tierRouter.js"
click node_node_offer_engine "https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Intervention_Engine/src/services/offerEngine.js"
click node_node_channel_router "https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Intervention_Engine/src/services/channelRouter.js"
click node_node_message_generator "https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Intervention_Engine/src/services/messageGenerator.js"
click node_node_mailer "https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Intervention_Engine/src/email/mailer.js"
click node_node_templates "https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Intervention_Engine/src/email/templates.js"
click node_node_html_wrapper "https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Intervention_Engine/src/email/htmlWrapper.js"

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_node_main_api,node_node_feature_store,node_node_feast_features,node_node_feature_scripts,node_node_airflow_dag,node_node_xgb_model,node_node_shap_explainer,node_node_llm_response toneBlue
class node_node_intervention_route,node_node_tier_router,node_node_offer_engine,node_node_channel_router,node_node_message_generator,node_node_mailer,node_node_templates,node_node_html_wrapper toneAmber
class node_node_postgres,node_node_mistral,node_node_gmail toneMint
```

## Components

### Delinquency Engine

Python scoring service, feature pipeline, and model artifacts.

- [FastAPI API](https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Delinquency_Engine/FastApi_Backend/main.py): python service · Prediction endpoint and service boundary for delinquency scoring. · `Delinquency_Engine/FastApi_Backend/main.py`
- [Feature Store](https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Delinquency_Engine/feast_repo/feature_store.yaml): feast serving · Online/offline feature access layer for customer scoring. · `Delinquency_Engine/feast_repo/feature_store.yaml`
- [Entity Views](https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Delinquency_Engine/feast_repo/features.py): feast definitions · Feature entities and views that align training and serving. · `Delinquency_Engine/feast_repo/features.py`
- [Feature Pipeline](https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Delinquency_Engine/scripts/feature_sql.sql): sql+python pipeline · Daily feature SQL, materialization, synthetic data, and retraining scripts. · `Delinquency_Engine/scripts/feature_sql.sql`
- [Airflow DAG](https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Delinquency_Engine/airflow/dags/delinquency_feature_pipeline.py): orchestration · Scheduled daily feature pipeline execution. · `Delinquency_Engine/airflow/dags/delinquency_feature_pipeline.py`
- [XGBoost Model](https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Delinquency_Engine/FastApi_Backend/xgb_model_latest.joblib): trained artifact · Latest delinquency classifier used for online inference. · `Delinquency_Engine/FastApi_Backend/xgb_model_latest.joblib`
- [SHAP Explainer](https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Delinquency_Engine/FastApi_Backend/shap_explainer.joblib): explainability artifact · Produces feature attributions for risk explanations. · `Delinquency_Engine/FastApi_Backend/shap_explainer.joblib`
- [Explanation LLM](https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Delinquency_Engine/FastApi_Backend/app/llm_response.py): llm adapter · Turns SHAP drivers into human-readable delinquency explanations. · `Delinquency_Engine/FastApi_Backend/app/llm_response.py`

### Intervention Engine

Node.js outreach service, decisioning, and email delivery.

- [Intervention Route](https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Intervention_Engine/src/routes/intervention.js): express route · HTTP boundary for delinquency-triggered outreach actions. · `Intervention_Engine/src/routes/intervention.js`
- [Tier Router](https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Intervention_Engine/src/services/tierRouter.js): decisioning · Maps delinquency probability to risk tiers. · `Intervention_Engine/src/services/tierRouter.js`
- [Offer Engine](https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Intervention_Engine/src/services/offerEngine.js): policy engine · Selects the relief product based on tier and customer context. · `Intervention_Engine/src/services/offerEngine.js`
- [Channel Router](https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Intervention_Engine/src/services/channelRouter.js): routing · Determines urgency and outreach routing. · `Intervention_Engine/src/services/channelRouter.js`
- [Message Generator](https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Intervention_Engine/src/services/messageGenerator.js): messaging · Creates customer-facing outreach copy with AI fallback. · `Intervention_Engine/src/services/messageGenerator.js`
- [Mailer](https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Intervention_Engine/src/email/mailer.js): email delivery · Wraps messages and sends email via SMTP. · `Intervention_Engine/src/email/mailer.js`
- [Templates](https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Intervention_Engine/src/email/templates.js): fallback content · Predefined email copy used when AI generation fails. · `Intervention_Engine/src/email/templates.js`
- [HTML Wrapper](https://github.com/rohit-dhade/pre-delinquency-intervention-engine/blob/main/Intervention_Engine/src/email/htmlWrapper.js): email formatting · Applies branded HTML around generated outreach content. · `Intervention_Engine/src/email/htmlWrapper.js`

### Shared Systems

Operational datastore and third-party services used by both engines.

- **PostgreSQL**: operational store · Shared source-of-truth database for customer, feature, and intervention state.
- **Mistral AI**: external llm · Used for explanation generation and outreach message drafting.
- **Gmail SMTP**: delivery service · Outbound email transport for intervention delivery.

## Connections

- PostgreSQL → Feature Pipeline: raw data · Customer, transaction, and payment data feed feature SQL.
- Feature Pipeline → Airflow DAG: scheduled by · Daily pipeline is orchestrated through Airflow.
- Airflow DAG → Feature Store: materializes · Computed features are loaded into Feast online serving storage.
- Entity Views → Feature Store: defines · Entity and feature views keep serving aligned.
- Feature Store → FastAPI API: serves features · FastAPI reads online features by customer_id.
- XGBoost Model → FastAPI API: scores · Model artifact powers delinquency probability prediction.
- SHAP Explainer → FastAPI API: explains · SHAP attributions are generated during prediction.
- Explanation LLM → Mistral AI: uses · LLM-backed explanation text generation.
- FastAPI API → Explanation LLM: summarizes risk · Top SHAP drivers are converted to readable reasons.
- FastAPI API → Intervention Route: triggers · High-risk predictions can invoke intervention downstream.
- FastAPI API → PostgreSQL: reads/writes · Uses operational data and may persist scoring-related state.
- Intervention Route → Tier Router: routes by risk · Incoming probability is mapped to a tier.
- Tier Router → Offer Engine: selects offer · Tier and customer context determine the relief product.
- Offer Engine → Channel Router: prepares outreach · Offer choice informs urgency and channel routing.
- Channel Router → Message Generator: requests message · Routing decision passes into content generation.
- Message Generator → Mistral AI: drafts with · AI generates outreach copy when available.
- Message Generator → Templates: fallbacks to · Predefined templates are used if AI generation fails.
- Message Generator → HTML Wrapper: formats · Generated content is wrapped for branded email.
- HTML Wrapper → Mailer: delivers · Wrapped email is sent through the mailer.
- Mailer → Gmail SMTP: sends via · Nodemailer uses Gmail SMTP for delivery.
- Intervention Route → PostgreSQL: logs · Intervention and outcome records are persisted.