# harishchand83077/ml-insight-platform architecture

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

- Interactive diagram: https://gitdiagram.com/harishchand83077/ml-insight-platform
- Repository: https://github.com/harishchand83077/ml-insight-platform

## Overview

ML Insight Platform serves synthetic telecom churn predictions through an authenticated API and React chat assistant. The main user flow is browser authentication, then chat or prediction requests; the agent can invoke prediction, explanation, what-if, retention, customer-query, and document-retrieval tools. Supporting product stages include event ingestion, feature construction, model training and serving, feedback, and drift monitoring. The serving route and internal calls are evidenced by excerpts or README statements; local MLOps and several unsampled feature links are documented in the README, so those edges cite it.

Main entry points: [`src/serving/api.py`](https://github.com/harishchand83077/ml-insight-platform/blob/main/src/serving/api.py) (FastAPI routes), [`src/agent/tools.py`](https://github.com/harishchand83077/ml-insight-platform/blob/main/src/agent/tools.py) (Agent tools), [`src/serving/prediction.py`](https://github.com/harishchand83077/ml-insight-platform/blob/main/src/serving/prediction.py) (Churn prediction), [`src/models/train_baseline.py`](https://github.com/harishchand83077/ml-insight-platform/blob/main/src/models/train_baseline.py) (Model training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Chat client"]
  node_ui["React chat UI<br/>[App.jsx]"]
  node_client_api["HTTP client<br/>[api.js]"]
  node_auth_ui["Login and signup<br/>[AuthScreen.jsx]"]
end

subgraph group_serve["Serving"]
  node_api["FastAPI routes<br/>[api.py]"]
  node_auth["JWT authentication<br/>[auth.py]"]
  node_prediction["Churn prediction<br/>[prediction.py]"]
  node_explain["Risk explanation<br/>[explain.py]"]
  node_feedback["Feedback storage<br/>[feedback.py]"]
end

subgraph group_assistant["Agent and retrieval"]
  node_agent["LangGraph agent<br/>[agent.py]"]
  node_tools["Agent tools<br/>[tools.py]"]
  node_retriever["Hybrid document retrieval"]
  node_kb_builder["Knowledge index builder"]
  node_semantic_cache["Semantic response cache<br/>[semantic_cache.py]"]
end

subgraph group_shared["Shared services"]
  node_feature_cache["Feature cache<br/>[feature_cache.py]"]
  node_embedder["Shared embedder<br/>[embedding_model.py]"]
  node_model["Production model loader"]
  node_inference["Feature preparation<br/>[inference.py]"]
  node_postgres[("PostgreSQL")]
  node_redis[("Redis")]
end

subgraph group_mlops["Local MLOps"]
  node_event_generator["Synthetic event generator<br/>[generate_events.py]"]
  node_broker["RabbitMQ queues"]
  node_event_consumer["Event consumer<br/>[event_consumer.py]"]
  node_feature_pipeline["Feature construction<br/>[build_features.py]"]
  node_training["Model training<br/>[train_baseline.py]"]
  node_drift["Drift monitoring<br/>[monitor_drift.py]"]
  node_retrain_trigger["Retraining trigger<br/>[trigger_retrain.py]"]
  node_retrain_task["Retraining task<br/>[retrain_task.py]"]
end

node_browser(("Browser user"))

node_browser -->|"uses"| node_ui
node_ui -->|"renders"| node_auth_ui
node_auth_ui -->|"authenticates via"| node_client_api
node_ui -->|"requests"| node_client_api
node_client_api -->|"calls HTTPS"| node_api
node_api -->|"authenticates"| node_auth
node_auth -->|"reads and writes"| node_postgres
node_api -->|"predicts"| node_prediction
node_api -->|"invokes chat"| node_agent
node_api -->|"checks and stores"| node_semantic_cache
node_api -->|"stores feedback"| node_feedback
node_feedback -->|"writes"| node_postgres
node_api -->|"audits requests"| node_auth
node_agent -->|"dispatches tools"| node_tools
node_tools -->|"calls directly"| node_prediction
node_tools -->|"calls"| node_explain
node_prediction -->|"looks up features"| node_feature_cache
node_prediction -->|"prepares inputs"| node_inference
node_prediction -->|"scores customers"| node_model
node_explain -->|"explains scores"| node_model
node_feature_cache -->|"cache-aside"| node_redis
node_feature_cache -->|"falls back to"| node_postgres
node_semantic_cache -->|"reads and writes"| node_redis
node_semantic_cache -->|"embeds queries"| node_embedder
node_tools -->|"embeds documents"| node_embedder
node_tools -.->|"retrieves documents"| node_retriever
node_retriever -->|"uses index"| node_kb_builder
node_tools -->|"queries customer data"| node_postgres
node_event_generator -->|"publishes events"| node_broker
node_broker -->|"delivers events"| node_event_consumer
node_event_consumer -->|"commits batches"| node_postgres
node_feature_pipeline -->|"builds features"| node_postgres
node_training -->|"loads training data"| node_postgres
node_training -->|"shares feature columns"| node_inference
node_drift -->|"compares distributions"| node_training
node_retrain_trigger -->|"dispatches"| node_retrain_task
node_retrain_task -->|"retrains model"| node_training

click node_ui "https://github.com/harishchand83077/ml-insight-platform/blob/main/frontend/src/App.jsx"
click node_client_api "https://github.com/harishchand83077/ml-insight-platform/blob/main/frontend/src/api.js"
click node_auth_ui "https://github.com/harishchand83077/ml-insight-platform/blob/main/frontend/src/components/AuthScreen.jsx"
click node_api "https://github.com/harishchand83077/ml-insight-platform/blob/main/src/serving/api.py"
click node_auth "https://github.com/harishchand83077/ml-insight-platform/blob/main/src/serving/auth.py"
click node_prediction "https://github.com/harishchand83077/ml-insight-platform/blob/main/src/serving/prediction.py"
click node_explain "https://github.com/harishchand83077/ml-insight-platform/blob/main/src/serving/explain.py"
click node_feedback "https://github.com/harishchand83077/ml-insight-platform/blob/main/src/serving/feedback.py"
click node_agent "https://github.com/harishchand83077/ml-insight-platform/blob/main/src/agent/agent.py"
click node_tools "https://github.com/harishchand83077/ml-insight-platform/blob/main/src/agent/tools.py"
click node_retriever "https://github.com/harishchand83077/ml-insight-platform/blob/main/src/agent/hybrid_retriever.py"
click node_kb_builder "https://github.com/harishchand83077/ml-insight-platform/blob/main/src/agent/build_knowledge_base.py"
click node_semantic_cache "https://github.com/harishchand83077/ml-insight-platform/blob/main/src/agent/semantic_cache.py"
click node_feature_cache "https://github.com/harishchand83077/ml-insight-platform/blob/main/src/serving/feature_cache.py"
click node_embedder "https://github.com/harishchand83077/ml-insight-platform/blob/main/src/common/embedding_model.py"
click node_model "https://github.com/harishchand83077/ml-insight-platform/blob/main/src/common/production_model.py"
click node_inference "https://github.com/harishchand83077/ml-insight-platform/blob/main/src/models/inference.py"
click node_event_generator "https://github.com/harishchand83077/ml-insight-platform/blob/main/src/data_gen/generate_events.py"
click node_event_consumer "https://github.com/harishchand83077/ml-insight-platform/blob/main/src/ingestion/event_consumer.py"
click node_feature_pipeline "https://github.com/harishchand83077/ml-insight-platform/blob/main/src/pipelines/build_features.py"
click node_training "https://github.com/harishchand83077/ml-insight-platform/blob/main/src/models/train_baseline.py"
click node_drift "https://github.com/harishchand83077/ml-insight-platform/blob/main/src/models/monitor_drift.py"
click node_retrain_trigger "https://github.com/harishchand83077/ml-insight-platform/blob/main/src/pipelines/trigger_retrain.py"
click node_retrain_task "https://github.com/harishchand83077/ml-insight-platform/blob/main/src/pipelines/retrain_task.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_ui,node_client_api,node_auth_ui,node_browser toneBlue
class node_api,node_auth,node_prediction,node_explain,node_feedback toneAmber
class node_agent,node_tools,node_retriever,node_kb_builder,node_semantic_cache toneMint
class node_feature_cache,node_embedder,node_model,node_inference,node_postgres,node_redis toneRose
class node_event_generator,node_broker,node_event_consumer,node_feature_pipeline,node_training,node_drift,node_retrain_trigger,node_retrain_task toneIndigo
```

## Components

### Chat client

- [React chat UI](https://github.com/harishchand83077/ml-insight-platform/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [HTTP client](https://github.com/harishchand83077/ml-insight-platform/blob/main/frontend/src/api.js): `frontend/src/api.js`
- [Login and signup](https://github.com/harishchand83077/ml-insight-platform/blob/main/frontend/src/components/AuthScreen.jsx): `frontend/src/components/AuthScreen.jsx`

### Serving

- [FastAPI routes](https://github.com/harishchand83077/ml-insight-platform/blob/main/src/serving/api.py): `src/serving/api.py`
- [JWT authentication](https://github.com/harishchand83077/ml-insight-platform/blob/main/src/serving/auth.py): `src/serving/auth.py`
- [Churn prediction](https://github.com/harishchand83077/ml-insight-platform/blob/main/src/serving/prediction.py): `src/serving/prediction.py`
- [Risk explanation](https://github.com/harishchand83077/ml-insight-platform/blob/main/src/serving/explain.py): `src/serving/explain.py`
- [Feedback storage](https://github.com/harishchand83077/ml-insight-platform/blob/main/src/serving/feedback.py): `src/serving/feedback.py`

### Agent and retrieval

- [LangGraph agent](https://github.com/harishchand83077/ml-insight-platform/blob/main/src/agent/agent.py): `src/agent/agent.py`
- [Agent tools](https://github.com/harishchand83077/ml-insight-platform/blob/main/src/agent/tools.py): `src/agent/tools.py`
- [Hybrid document retrieval](https://github.com/harishchand83077/ml-insight-platform/blob/main/src/agent/hybrid_retriever.py): `src/agent/hybrid_retriever.py`
- [Knowledge index builder](https://github.com/harishchand83077/ml-insight-platform/blob/main/src/agent/build_knowledge_base.py): `src/agent/build_knowledge_base.py`
- [Semantic response cache](https://github.com/harishchand83077/ml-insight-platform/blob/main/src/agent/semantic_cache.py): `src/agent/semantic_cache.py`

### Shared services

- [Feature cache](https://github.com/harishchand83077/ml-insight-platform/blob/main/src/serving/feature_cache.py): `src/serving/feature_cache.py`
- [Shared embedder](https://github.com/harishchand83077/ml-insight-platform/blob/main/src/common/embedding_model.py): `src/common/embedding_model.py`
- [Production model loader](https://github.com/harishchand83077/ml-insight-platform/blob/main/src/common/production_model.py): `src/common/production_model.py`
- [Feature preparation](https://github.com/harishchand83077/ml-insight-platform/blob/main/src/models/inference.py): `src/models/inference.py`
- **PostgreSQL**
- **Redis**

### Local MLOps

- [Synthetic event generator](https://github.com/harishchand83077/ml-insight-platform/blob/main/src/data_gen/generate_events.py): `src/data_gen/generate_events.py`
- **RabbitMQ queues**
- [Event consumer](https://github.com/harishchand83077/ml-insight-platform/blob/main/src/ingestion/event_consumer.py): `src/ingestion/event_consumer.py`
- [Feature construction](https://github.com/harishchand83077/ml-insight-platform/blob/main/src/pipelines/build_features.py): `src/pipelines/build_features.py`
- [Model training](https://github.com/harishchand83077/ml-insight-platform/blob/main/src/models/train_baseline.py): `src/models/train_baseline.py`
- [Drift monitoring](https://github.com/harishchand83077/ml-insight-platform/blob/main/src/models/monitor_drift.py): `src/models/monitor_drift.py`
- [Retraining trigger](https://github.com/harishchand83077/ml-insight-platform/blob/main/src/pipelines/trigger_retrain.py): `src/pipelines/trigger_retrain.py`
- [Retraining task](https://github.com/harishchand83077/ml-insight-platform/blob/main/src/pipelines/retrain_task.py): `src/pipelines/retrain_task.py`

### Other components

- **Browser user**

## Connections

- Browser user → React chat UI: uses (evidence: `README.md`)
- React chat UI → Login and signup: renders (evidence: `frontend/src/App.jsx`)
- Login and signup → HTTP client: authenticates via (evidence: `frontend/src/components/AuthScreen.jsx`)
- React chat UI → HTTP client: requests (evidence: `frontend/src/App.jsx`)
- HTTP client → FastAPI routes: calls HTTPS (evidence: `README.md`)
- FastAPI routes → JWT authentication: authenticates (evidence: `src/serving/api.py`)
- JWT authentication → PostgreSQL: reads and writes (evidence: `src/serving/auth.py`)
- FastAPI routes → Churn prediction: predicts (evidence: `README.md`)
- FastAPI routes → LangGraph agent: invokes chat (evidence: `src/serving/api.py`)
- FastAPI routes → Semantic response cache: checks and stores (evidence: `src/serving/api.py`)
- FastAPI routes → Feedback storage: stores feedback (evidence: `README.md`)
- Feedback storage → PostgreSQL: writes (evidence: `README.md`)
- FastAPI routes → JWT authentication: audits requests (evidence: `README.md`)
- LangGraph agent → Agent tools: dispatches tools (evidence: `src/agent/agent.py`)
- Agent tools → Churn prediction: calls directly (evidence: `src/agent/tools.py`)
- Agent tools → Risk explanation: calls (evidence: `src/agent/tools.py`)
- Churn prediction → Feature cache: looks up features (evidence: `src/serving/prediction.py`)
- Churn prediction → Feature preparation: prepares inputs (evidence: `src/models/inference.py`)
- Churn prediction → Production model loader: scores customers (evidence: `src/serving/prediction.py`)
- Risk explanation → Production model loader: explains scores (evidence: `src/serving/explain.py`)
- Feature cache → Redis: cache-aside (evidence: `README.md`)
- Feature cache → PostgreSQL: falls back to (evidence: `README.md`)
- Semantic response cache → Redis: reads and writes (evidence: `README.md`)
- Semantic response cache → Shared embedder: embeds queries (evidence: `src/agent/semantic_cache.py`)
- Agent tools → Shared embedder: embeds documents (evidence: `src/common/embedding_model.py`)
- Agent tools → Hybrid document retrieval: retrieves documents
- Hybrid document retrieval → Knowledge index builder: uses index (evidence: `src/agent/hybrid_retriever.py`)
- Agent tools → PostgreSQL: queries customer data (evidence: `src/agent/tools.py`)
- Synthetic event generator → RabbitMQ queues: publishes events (evidence: `README.md`)
- RabbitMQ queues → Event consumer: delivers events (evidence: `README.md`)
- Event consumer → PostgreSQL: commits batches (evidence: `README.md`)
- Feature construction → PostgreSQL: builds features (evidence: `README.md`)
- Model training → PostgreSQL: loads training data (evidence: `README.md`)
- Model training → Feature preparation: shares feature columns (evidence: `src/models/inference.py`)
- Drift monitoring → Model training: compares distributions (evidence: `README.md`)
- Retraining trigger → Retraining task: dispatches (evidence: `src/pipelines/trigger_retrain.py`)
- Retraining task → Model training: retrains model (evidence: `src/pipelines/retrain_task.py`)
