# noruiz-04/churn-prediction-engine- architecture

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

- Interactive diagram: https://gitdiagram.com/noruiz-04/churn-prediction-engine-
- Repository: https://github.com/noruiz-04/churn-prediction-engine-

## Overview

This is a full-stack customer churn decision-intelligence platform. Analysts bring in customer data, which is profiled, transformed, validated, stored, and scored; the platform then supports churn and time-to-churn risk, uplift-based retention decisions, explanations, budget allocation, executive insights, and governance. The React dashboard exposes these capabilities through a FastAPI backend. The graph shows the ingestion and decision paths where source excerpts establish ownership; other README-described capabilities remain represented, but their internal links are omitted where implementation wiring was not shown.

Main entry points: [`backend/ingestion/pipeline.py`](https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/ingestion/pipeline.py) (Ingestion pipeline), [`backend/services/decision_engine.py`](https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/services/decision_engine.py) (Decision engine), [`backend/app.py`](https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/app.py) (FastAPI app), [`backend/scoring/orchestrator.py`](https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/scoring/orchestrator.py) (Scoring orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data ingestion"]
  node_ingest_service["File ingestion<br/>[service.py]"]
  node_ingest_pipeline["Ingestion pipeline<br/>[pipeline.py]"]
  node_schema_profile["Schema profiling<br/>[schema_profiler.py]"]
  node_schema_map["Schema mapping<br/>[schema_mapper.py]"]
  node_feature_engineering["Feature engineering"]
  node_dataset_store[("Dataset registry")]
end

subgraph group_intelligence["Scoring &amp; intelligence"]
  node_scoring["Scoring orchestration<br/>[orchestrator.py]"]
  node_scoring_insights["Scoring insights<br/>[insights_engine.py]"]
  node_executive["Executive intelligence"]
  node_predictor["Churn prediction<br/>[predictor.py]"]
  node_uplift_model["Uplift modeling<br/>[uplift_model.py]"]
  node_survival_model["Time-to-churn<br/>[survival_model.py]"]
  node_result_store[("Scoring results<br/>[results_store.py]")]
end

subgraph group_decision["Retention decisions"]
  node_decision_engine["Decision engine<br/>[decision_engine.py]"]
  node_explainer["Model explanations<br/>[explainer.py]"]
  node_llm_explainer["LLM explanations<br/>[llm_explainer.py]"]
  node_budget_optimizer["Budget optimization"]
end

subgraph group_experience["Dashboard &amp; API"]
  node_data_ui["Data upload<br/>[DataSource.jsx]"]
  node_web_app["Dashboard routes<br/>[App.jsx]"]
  node_api_app["FastAPI app<br/>[app.py]"]
  node_ingest_api["Ingestion endpoints"]
  node_source_api["Source connectors API<br/>[data_sources.py]"]
  node_uplift_routes["Uplift API<br/>[uplift_router.py]"]
  node_governance["Model governance<br/>[governance.py]"]
  node_reporting["Executive reporting"]
end

node_analyst(("Analyst"))

node_analyst -->|"uploads data"| node_data_ui
node_data_ui -.->|"requests ingestion"| node_ingest_api
node_web_app -->|"routes to"| node_data_ui
node_api_app -->|"registers routes"| node_ingest_api
node_api_app -->|"registers routes"| node_source_api
node_ingest_api -->|"calls"| node_ingest_service
node_source_api -->|"invokes"| node_ingest_pipeline
node_ingest_service -->|"runs"| node_ingest_pipeline
node_ingest_pipeline -->|"profiles"| node_schema_profile
node_ingest_pipeline -->|"maps schema"| node_schema_map
node_ingest_pipeline -->|"engineers features"| node_feature_engineering
node_ingest_pipeline -->|"stores dataset"| node_dataset_store
node_ingest_pipeline -->|"starts scoring"| node_scoring
node_scoring -->|"generates"| node_scoring_insights
node_scoring -->|"stores results"| node_result_store
node_executive -->|"builds decisions"| node_decision_engine
node_decision_engine -->|"predicts churn"| node_predictor
node_decision_engine -->|"predicts uplift"| node_uplift_model
node_decision_engine -->|"estimates timing"| node_survival_model
node_decision_engine -->|"explains drivers"| node_explainer
node_decision_engine -->|"computes value"| node_budget_optimizer
node_api_app -->|"registers routes"| node_uplift_routes
node_uplift_routes -->|"trains and scores"| node_uplift_model
node_uplift_routes -->|"explains decisions"| node_llm_explainer
node_api_app -->|"registers routes"| node_governance
node_api_app -->|"registers report routes"| node_reporting
node_executive -.->|"returns insights"| node_analyst

click node_data_ui "https://github.com/noruiz-04/churn-prediction-engine-/blob/main/churn-dashboard/src/pages/DataSource.jsx"
click node_web_app "https://github.com/noruiz-04/churn-prediction-engine-/blob/main/churn-dashboard/src/App.jsx"
click node_api_app "https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/app.py"
click node_ingest_api "https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/api/ingestion_routers.py"
click node_source_api "https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/api/data_sources.py"
click node_ingest_service "https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/ingestion/service.py"
click node_ingest_pipeline "https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/ingestion/pipeline.py"
click node_schema_profile "https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/ingestion/profiling/schema_profiler.py"
click node_schema_map "https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/ingestion/mapping/schema_mapper.py"
click node_feature_engineering "https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/ingestion/processing/feature_engineering.py"
click node_dataset_store "https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/ingestion/storage/dataset_registry.py"
click node_scoring "https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/scoring/orchestrator.py"
click node_scoring_insights "https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/scoring/insights_engine.py"
click node_executive "https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/insights/executive_engine.py"
click node_decision_engine "https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/services/decision_engine.py"
click node_predictor "https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/services/predictor.py"
click node_uplift_model "https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/services/uplift_model.py"
click node_survival_model "https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/services/survival_model.py"
click node_explainer "https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/services/explainer.py"
click node_llm_explainer "https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/services/llm_explainer.py"
click node_budget_optimizer "https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/optimizer/budget_optimizer.py"
click node_uplift_routes "https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/routers/uplift_router.py"
click node_governance "https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/routers/governance.py"
click node_reporting "https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/services/report_generator.py"
click node_result_store "https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/storage/results_store.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_ingest_service,node_ingest_pipeline,node_schema_profile,node_schema_map,node_feature_engineering,node_dataset_store toneBlue
class node_scoring,node_scoring_insights,node_executive,node_predictor,node_uplift_model,node_survival_model,node_result_store toneAmber
class node_decision_engine,node_explainer,node_llm_explainer,node_budget_optimizer toneMint
class node_data_ui,node_web_app,node_api_app,node_ingest_api,node_source_api,node_uplift_routes,node_governance,node_reporting toneRose
class node_analyst toneIndigo
```

## Components

### Data ingestion

- [File ingestion](https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/ingestion/service.py): `backend/ingestion/service.py`
- [Ingestion pipeline](https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/ingestion/pipeline.py): `backend/ingestion/pipeline.py`
- [Schema profiling](https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/ingestion/profiling/schema_profiler.py): `backend/ingestion/profiling/schema_profiler.py`
- [Schema mapping](https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/ingestion/mapping/schema_mapper.py): `backend/ingestion/mapping/schema_mapper.py`
- [Feature engineering](https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/ingestion/processing/feature_engineering.py): `backend/ingestion/processing/feature_engineering.py`
- [Dataset registry](https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/ingestion/storage/dataset_registry.py): `backend/ingestion/storage/dataset_registry.py`

### Scoring & intelligence

- [Scoring orchestration](https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/scoring/orchestrator.py): `backend/scoring/orchestrator.py`
- [Scoring insights](https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/scoring/insights_engine.py): `backend/scoring/insights_engine.py`
- [Executive intelligence](https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/insights/executive_engine.py): `backend/insights/executive_engine.py`
- [Churn prediction](https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/services/predictor.py): `backend/services/predictor.py`
- [Uplift modeling](https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/services/uplift_model.py): `backend/services/uplift_model.py`
- [Time-to-churn](https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/services/survival_model.py): `backend/services/survival_model.py`
- [Scoring results](https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/storage/results_store.py): `backend/storage/results_store.py`

### Retention decisions

- [Decision engine](https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/services/decision_engine.py): `backend/services/decision_engine.py`
- [Model explanations](https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/services/explainer.py): `backend/services/explainer.py`
- [LLM explanations](https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/services/llm_explainer.py): `backend/services/llm_explainer.py`
- [Budget optimization](https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/optimizer/budget_optimizer.py): `backend/optimizer/budget_optimizer.py`

### Dashboard & API

- [Data upload](https://github.com/noruiz-04/churn-prediction-engine-/blob/main/churn-dashboard/src/pages/DataSource.jsx): `churn-dashboard/src/pages/DataSource.jsx`
- [Dashboard routes](https://github.com/noruiz-04/churn-prediction-engine-/blob/main/churn-dashboard/src/App.jsx): `churn-dashboard/src/App.jsx`
- [FastAPI app](https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/app.py): `backend/app.py`
- [Ingestion endpoints](https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/api/ingestion_routers.py): `backend/api/ingestion_routers.py`
- [Source connectors API](https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/api/data_sources.py): `backend/api/data_sources.py`
- [Uplift API](https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/routers/uplift_router.py): `backend/routers/uplift_router.py`
- [Model governance](https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/routers/governance.py): `backend/routers/governance.py`
- [Executive reporting](https://github.com/noruiz-04/churn-prediction-engine-/blob/main/backend/services/report_generator.py): `backend/services/report_generator.py`

### Other components

- **Analyst**

## Connections

- Analyst → Data upload: uploads data (evidence: `README.md`)
- Data upload → Ingestion endpoints: requests ingestion
- Dashboard routes → Data upload: routes to (evidence: `churn-dashboard/src/App.jsx`)
- FastAPI app → Ingestion endpoints: registers routes (evidence: `backend/app.py`)
- FastAPI app → Source connectors API: registers routes (evidence: `backend/app.py`)
- Ingestion endpoints → File ingestion: calls (evidence: `backend/api/ingestion_routers.py`)
- Source connectors API → Ingestion pipeline: invokes (evidence: `backend/api/data_sources.py`)
- File ingestion → Ingestion pipeline: runs (evidence: `backend/ingestion/service.py`)
- Ingestion pipeline → Schema profiling: profiles (evidence: `backend/ingestion/pipeline.py`)
- Ingestion pipeline → Schema mapping: maps schema (evidence: `backend/ingestion/pipeline.py`)
- Ingestion pipeline → Feature engineering: engineers features (evidence: `backend/ingestion/pipeline.py`)
- Ingestion pipeline → Dataset registry: stores dataset (evidence: `backend/ingestion/pipeline.py`)
- Ingestion pipeline → Scoring orchestration: starts scoring (evidence: `backend/ingestion/pipeline.py`)
- Scoring orchestration → Scoring insights: generates (evidence: `backend/scoring/orchestrator.py`)
- Scoring orchestration → Scoring results: stores results (evidence: `backend/scoring/orchestrator.py`)
- Executive intelligence → Decision engine: builds decisions (evidence: `backend/insights/executive_engine.py`)
- Decision engine → Churn prediction: predicts churn (evidence: `backend/services/decision_engine.py`)
- Decision engine → Uplift modeling: predicts uplift (evidence: `backend/services/decision_engine.py`)
- Decision engine → Time-to-churn: estimates timing (evidence: `backend/services/decision_engine.py`)
- Decision engine → Model explanations: explains drivers (evidence: `backend/services/decision_engine.py`)
- Decision engine → Budget optimization: computes value (evidence: `backend/services/decision_engine.py`)
- FastAPI app → Uplift API: registers routes (evidence: `backend/app.py`)
- Uplift API → Uplift modeling: trains and scores (evidence: `backend/routers/uplift_router.py`)
- Uplift API → LLM explanations: explains decisions
- FastAPI app → Model governance: registers routes (evidence: `backend/app.py`)
- FastAPI app → Executive reporting: registers report routes (evidence: `backend/app.py`)
- Executive intelligence → Analyst: returns insights (evidence: `README.md`)
