# randomlyclueless/retainai architecture

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

- Interactive diagram: https://gitdiagram.com/randomlyclueless/retainai
- Repository: https://github.com/randomlyclueless/retainai

## Overview

RetainAI is a customer-retention platform: users enter or upload customer data, request churn analysis, and review risk, explanations, recommendations, and retention analytics in the dashboard. The documented analysis combines prediction, explanation, and recommendations; the backend persists customer records and exposes customer and statistics APIs. Separate capabilities include the conversational copilot and model monitoring. The README documents the broader agent architecture, but the agent API and several frontend/backend modules were not sampled, so uncertain internal dispatch links are omitted.

Main entry points: [`Frontend/my-app/src/pages/Dashboard.jsx`](https://github.com/randomlyclueless/retainai/blob/main/Frontend/my-app/src/pages/Dashboard.jsx) (Dashboard), [`agent/agent_api.py`](https://github.com/randomlyclueless/retainai/blob/main/agent/agent_api.py) (Agent API), [`backend/backend/src/main/java/com/churn/backend/service/CustomerService.java`](https://github.com/randomlyclueless/retainai/blob/main/backend/backend/src/main/java/com/churn/backend/service/CustomerService.java) (Customer operations), [`agent/workflows/retention_workflow.py`](https://github.com/randomlyclueless/retainai/blob/main/agent/workflows/retention_workflow.py) (Retention workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["React product"]
  node_app["Route application<br/>[App.js]"]
  node_dashboard["Dashboard<br/>[Dashboard.jsx]"]
  node_customer_form["Customer entry<br/>[CustomerForm.jsx]"]
  node_file_upload["CSV upload UI<br/>[FileUpload.jsx]"]
  node_analytics["Retention analytics"]
  node_insights["AI insights<br/>[AIInsights.jsx]"]
  node_explanation_card["Risk explanation"]
  node_copilot_ui["Copilot chat<br/>[AICopilot.jsx]"]
  node_customer_api["Customer API client<br/>[customerapi.js]"]
  node_analytics_service["Analytics service"]
end

subgraph group_api["Customer API"]
  node_customer_controller["Customer endpoints"]
  node_upload_controller["CSV endpoint"]
  node_customer_service["Customer operations"]
  node_customer_model["Customer record<br/>[Customer.java]"]
  node_customer_repository["Customer repository"]
end

subgraph group_agents["AI analysis"]
  node_agent_api["Agent API<br/>[agent_api.py]"]
  node_retention_workflow["Retention workflow"]
  node_prediction["Churn prediction"]
  node_explanation["SHAP explanation"]
  node_recommendation["Retention strategy"]
  node_monitoring["Model monitoring"]
  node_copilot["Copilot agent<br/>[copilot_agent.py]"]
  node_explain_tool["Explainability tool<br/>[explainability.py]"]
  node_gemini_service["Gemini service<br/>[gemini_service.py]"]
end

subgraph group_state["Conversation state"]
  node_chat_memory[("Chat memory<br/>[chat_memory.py]")]
end

node_user(("Business user"))
node_mysql[("MySQL database")]
node_gemini{{"Google Gemini"}}

node_user -->|"uses"| node_app
node_app -->|"routes"| node_dashboard
node_dashboard -->|"presents"| node_customer_form
node_dashboard -->|"presents"| node_file_upload
node_dashboard -->|"presents"| node_analytics
node_dashboard -->|"presents"| node_insights
node_dashboard -->|"presents"| node_explanation_card
node_dashboard -->|"presents"| node_copilot_ui
node_customer_form -->|"requests"| node_customer_api
node_file_upload -->|"uploads CSV"| node_upload_controller
node_analytics -->|"requests metrics"| node_analytics_service
node_insights -->|"requests"| node_customer_api
node_explanation_card -->|"requests"| node_customer_api
node_copilot_ui -->|"asks questions"| node_agent_api
node_customer_api -->|"calls REST"| node_customer_controller
node_customer_controller -->|"delegates"| node_customer_service
node_customer_service -->|"reads and saves"| node_customer_repository
node_customer_repository -->|"persists records"| node_mysql
node_customer_service -->|"updates fields"| node_customer_model
node_customer_service -->|"posts analysis"| node_agent_api
node_agent_api -->|"runs analysis"| node_retention_workflow
node_retention_workflow -->|"coordinates"| node_prediction
node_retention_workflow -->|"coordinates"| node_explanation
node_retention_workflow -->|"coordinates"| node_recommendation
node_monitoring -.->|"provides monitoring"| node_agent_api
node_explanation -->|"uses SHAP"| node_explain_tool
node_copilot_ui -->|"sends prompts"| node_agent_api
node_agent_api -->|"handles copilot"| node_copilot
node_copilot -->|"saves and reads"| node_chat_memory
node_copilot -->|"requests response"| node_gemini_service
node_gemini_service -->|"generates content"| node_gemini

click node_app "https://github.com/randomlyclueless/retainai/blob/main/Frontend/my-app/src/App.js"
click node_dashboard "https://github.com/randomlyclueless/retainai/blob/main/Frontend/my-app/src/pages/Dashboard.jsx"
click node_customer_form "https://github.com/randomlyclueless/retainai/blob/main/Frontend/my-app/src/components/CustomerForm.jsx"
click node_file_upload "https://github.com/randomlyclueless/retainai/blob/main/Frontend/my-app/src/components/FileUpload.jsx"
click node_analytics "https://github.com/randomlyclueless/retainai/blob/main/Frontend/my-app/src/components/AnalyticsCharts.jsx"
click node_insights "https://github.com/randomlyclueless/retainai/blob/main/Frontend/my-app/src/components/AIInsights.jsx"
click node_explanation_card "https://github.com/randomlyclueless/retainai/blob/main/Frontend/my-app/src/components/AIExplanationCard.jsx"
click node_copilot_ui "https://github.com/randomlyclueless/retainai/blob/main/Frontend/my-app/src/components/AICopilot.jsx"
click node_customer_api "https://github.com/randomlyclueless/retainai/blob/main/Frontend/my-app/src/api/customerapi.js"
click node_analytics_service "https://github.com/randomlyclueless/retainai/blob/main/Frontend/my-app/src/services/analyticsService.js"
click node_customer_controller "https://github.com/randomlyclueless/retainai/blob/main/backend/backend/src/main/java/com/churn/backend/controller/CustomerController.java"
click node_upload_controller "https://github.com/randomlyclueless/retainai/blob/main/backend/backend/src/main/java/com/churn/backend/controller/FileUploadController.java"
click node_customer_service "https://github.com/randomlyclueless/retainai/blob/main/backend/backend/src/main/java/com/churn/backend/service/CustomerService.java"
click node_customer_model "https://github.com/randomlyclueless/retainai/blob/main/backend/backend/src/main/java/com/churn/backend/model/Customer.java"
click node_customer_repository "https://github.com/randomlyclueless/retainai/blob/main/backend/backend/src/main/java/com/churn/backend/repository/CustomerRepository.java"
click node_agent_api "https://github.com/randomlyclueless/retainai/blob/main/agent/agent_api.py"
click node_retention_workflow "https://github.com/randomlyclueless/retainai/blob/main/agent/workflows/retention_workflow.py"
click node_prediction "https://github.com/randomlyclueless/retainai/blob/main/agent/agents/prediction_agent.py"
click node_explanation "https://github.com/randomlyclueless/retainai/blob/main/agent/agents/explanation_agent.py"
click node_recommendation "https://github.com/randomlyclueless/retainai/blob/main/agent/agents/recommendation_agent.py"
click node_monitoring "https://github.com/randomlyclueless/retainai/blob/main/agent/agents/monitoring_agent.py"
click node_copilot "https://github.com/randomlyclueless/retainai/blob/main/agent/agents/copilot_agent.py"
click node_explain_tool "https://github.com/randomlyclueless/retainai/blob/main/agent/tools/explainability.py"
click node_gemini_service "https://github.com/randomlyclueless/retainai/blob/main/agent/services/gemini_service.py"
click node_chat_memory "https://github.com/randomlyclueless/retainai/blob/main/agent/memory/chat_memory.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_dashboard,node_customer_form,node_file_upload,node_analytics,node_insights,node_explanation_card,node_copilot_ui,node_customer_api,node_analytics_service,node_user toneBlue
class node_customer_controller,node_upload_controller,node_customer_service,node_customer_model,node_customer_repository,node_mysql toneAmber
class node_agent_api,node_retention_workflow,node_prediction,node_explanation,node_recommendation,node_monitoring,node_copilot,node_explain_tool,node_gemini_service toneMint
class node_chat_memory toneRose
class node_gemini toneIndigo
```

## Components

### React product

- [Route application](https://github.com/randomlyclueless/retainai/blob/main/Frontend/my-app/src/App.js): `Frontend/my-app/src/App.js`
- [Dashboard](https://github.com/randomlyclueless/retainai/blob/main/Frontend/my-app/src/pages/Dashboard.jsx): `Frontend/my-app/src/pages/Dashboard.jsx`
- [Customer entry](https://github.com/randomlyclueless/retainai/blob/main/Frontend/my-app/src/components/CustomerForm.jsx): `Frontend/my-app/src/components/CustomerForm.jsx`
- [CSV upload UI](https://github.com/randomlyclueless/retainai/blob/main/Frontend/my-app/src/components/FileUpload.jsx): `Frontend/my-app/src/components/FileUpload.jsx`
- [Retention analytics](https://github.com/randomlyclueless/retainai/blob/main/Frontend/my-app/src/components/AnalyticsCharts.jsx): `Frontend/my-app/src/components/AnalyticsCharts.jsx`
- [AI insights](https://github.com/randomlyclueless/retainai/blob/main/Frontend/my-app/src/components/AIInsights.jsx): `Frontend/my-app/src/components/AIInsights.jsx`
- [Risk explanation](https://github.com/randomlyclueless/retainai/blob/main/Frontend/my-app/src/components/AIExplanationCard.jsx): `Frontend/my-app/src/components/AIExplanationCard.jsx`
- [Copilot chat](https://github.com/randomlyclueless/retainai/blob/main/Frontend/my-app/src/components/AICopilot.jsx): `Frontend/my-app/src/components/AICopilot.jsx`
- [Customer API client](https://github.com/randomlyclueless/retainai/blob/main/Frontend/my-app/src/api/customerapi.js): `Frontend/my-app/src/api/customerapi.js`
- [Analytics service](https://github.com/randomlyclueless/retainai/blob/main/Frontend/my-app/src/services/analyticsService.js): `Frontend/my-app/src/services/analyticsService.js`

### Customer API

- [Customer endpoints](https://github.com/randomlyclueless/retainai/blob/main/backend/backend/src/main/java/com/churn/backend/controller/CustomerController.java): `backend/backend/src/main/java/com/churn/backend/controller/CustomerController.java`
- [CSV endpoint](https://github.com/randomlyclueless/retainai/blob/main/backend/backend/src/main/java/com/churn/backend/controller/FileUploadController.java): `backend/backend/src/main/java/com/churn/backend/controller/FileUploadController.java`
- [Customer operations](https://github.com/randomlyclueless/retainai/blob/main/backend/backend/src/main/java/com/churn/backend/service/CustomerService.java): `backend/backend/src/main/java/com/churn/backend/service/CustomerService.java`
- [Customer record](https://github.com/randomlyclueless/retainai/blob/main/backend/backend/src/main/java/com/churn/backend/model/Customer.java): `backend/backend/src/main/java/com/churn/backend/model/Customer.java`
- [Customer repository](https://github.com/randomlyclueless/retainai/blob/main/backend/backend/src/main/java/com/churn/backend/repository/CustomerRepository.java): `backend/backend/src/main/java/com/churn/backend/repository/CustomerRepository.java`

### AI analysis

- [Agent API](https://github.com/randomlyclueless/retainai/blob/main/agent/agent_api.py): `agent/agent_api.py`
- [Retention workflow](https://github.com/randomlyclueless/retainai/blob/main/agent/workflows/retention_workflow.py): `agent/workflows/retention_workflow.py`
- [Churn prediction](https://github.com/randomlyclueless/retainai/blob/main/agent/agents/prediction_agent.py): `agent/agents/prediction_agent.py`
- [SHAP explanation](https://github.com/randomlyclueless/retainai/blob/main/agent/agents/explanation_agent.py): `agent/agents/explanation_agent.py`
- [Retention strategy](https://github.com/randomlyclueless/retainai/blob/main/agent/agents/recommendation_agent.py): `agent/agents/recommendation_agent.py`
- [Model monitoring](https://github.com/randomlyclueless/retainai/blob/main/agent/agents/monitoring_agent.py): `agent/agents/monitoring_agent.py`
- [Copilot agent](https://github.com/randomlyclueless/retainai/blob/main/agent/agents/copilot_agent.py): `agent/agents/copilot_agent.py`
- [Explainability tool](https://github.com/randomlyclueless/retainai/blob/main/agent/tools/explainability.py): `agent/tools/explainability.py`
- [Gemini service](https://github.com/randomlyclueless/retainai/blob/main/agent/services/gemini_service.py): `agent/services/gemini_service.py`

### Conversation state

- [Chat memory](https://github.com/randomlyclueless/retainai/blob/main/agent/memory/chat_memory.py): `agent/memory/chat_memory.py`

### Other components

- **Business user**
- **MySQL database**
- **Google Gemini**

## Connections

- Business user → Route application: uses
- Route application → Dashboard: routes
- Dashboard → Customer entry: presents
- Dashboard → CSV upload UI: presents
- Dashboard → Retention analytics: presents
- Dashboard → AI insights: presents
- Dashboard → Risk explanation: presents
- Dashboard → Copilot chat: presents
- Customer entry → Customer API client: requests
- CSV upload UI → CSV endpoint: uploads CSV
- Retention analytics → Analytics service: requests metrics
- AI insights → Customer API client: requests
- Risk explanation → Customer API client: requests
- Copilot chat → Agent API: asks questions
- Customer API client → Customer endpoints: calls REST
- Customer endpoints → Customer operations: delegates
- Customer operations → Customer repository: reads and saves
- Customer repository → MySQL database: persists records
- Customer operations → Customer record: updates fields
- Customer operations → Agent API: posts analysis
- Agent API → Retention workflow: runs analysis
- Retention workflow → Churn prediction: coordinates
- Retention workflow → SHAP explanation: coordinates
- Retention workflow → Retention strategy: coordinates
- Model monitoring → Agent API: provides monitoring
- SHAP explanation → Explainability tool: uses SHAP
- Copilot chat → Agent API: sends prompts
- Agent API → Copilot agent: handles copilot
- Copilot agent → Chat memory: saves and reads
- Copilot agent → Gemini service: requests response
- Gemini service → Google Gemini: generates content