# ryancjc/e-commerce-ai-ml-retention-platform architecture

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

- Interactive diagram: https://gitdiagram.com/ryancjc/e-commerce-ai-ml-retention-platform
- Repository: https://github.com/ryancjc/e-commerce-ai-ml-retention-platform

## Overview

This is an e-commerce customer-retention platform: users submit an individual customer for churn scoring, risk classification, SHAP attribution, risk-routed retrieval, and a structured recommendation; they can also inspect population analytics. The frontend calls the FastAPI service, which coordinates analysis and persistence. Major documented capabilities include vector-knowledge ingestion/retrieval and historical analytics. Some subsystem connections are supported by README descriptions or SOURCE INDEX references rather than complete implementation excerpts; uncertain internal details are not expanded.

Main entry points: [`llm/llm_graph.py`](https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/llm/llm_graph.py) (Risk-routed workflow), [`api/main.py`](https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/api/main.py) (FastAPI endpoints), [`frontend/src/App.tsx`](https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/frontend/src/App.tsx) (Web application), [`rag/rag_pipeline.py`](https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/rag/rag_pipeline.py) (Knowledge retrieval pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_web_app["Web application<br/>[App.tsx]"]
  node_customer_page["Customer analysis"]
  node_dashboard_page["Analytics dashboard"]
  node_customer_client["Customer API client<br/>[customer.ts]"]
  node_analytics_client["Analytics API client<br/>[analytics.ts]"]
end

subgraph group_api["API and analytics"]
  node_api_service["FastAPI endpoints<br/>[main.py]"]
  node_analytics_service["Analytics assembly<br/>[service.py]"]
  node_analytics_queries["Analytics queries<br/>[queries.py]"]
  node_database[("Supabase database")]
end

subgraph group_analysis["Churn analysis"]
  node_workflow["Risk-routed workflow<br/>[llm_graph.py]"]
  node_predictor["Churn prediction<br/>[predictor.py]"]
  node_recommendation_schema["Recommendation schema<br/>[schemas.py]"]
end

subgraph group_knowledge["Retention knowledge"]
  node_query_builder["Retention query builder<br/>[query_builder.py]"]
  node_rag_pipeline["Knowledge retrieval pipeline<br/>[rag_pipeline.py]"]
  node_retriever["Vector search retriever"]
  node_ingestion["Knowledge ingestion<br/>[supabase_ingest.py]"]
  node_retention_docs["Retention documents"]
end

node_operator(("Platform user"))
node_gemini["Google Gemini"]

node_operator -->|"uses"| node_web_app
node_web_app -->|"renders"| node_customer_page
node_web_app -->|"renders"| node_dashboard_page
node_customer_page -->|"requests analysis"| node_customer_client
node_dashboard_page -->|"loads analytics"| node_analytics_client
node_customer_client -.->|"calls API"| node_api_service
node_analytics_client -.->|"calls API"| node_api_service
node_api_service -->|"invokes analysis"| node_workflow
node_api_service -->|"reads and writes"| node_database
node_api_service -->|"requests dashboard data"| node_analytics_service
node_analytics_service -->|"calls queries"| node_analytics_queries
node_workflow -->|"scores and explains"| node_predictor
node_workflow -->|"retrieves by risk"| node_rag_pipeline
node_rag_pipeline -->|"builds query"| node_query_builder
node_rag_pipeline -->|"searches knowledge"| node_retriever
node_retriever -->|"vector similarity search"| node_database
node_ingestion -->|"chunks and embeds"| node_retention_docs
node_ingestion -->|"stores vectors"| node_database
node_workflow -->|"generates recommendation"| node_gemini
node_workflow -->|"formats output"| node_recommendation_schema

click node_web_app "https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/frontend/src/App.tsx"
click node_customer_page "https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/frontend/src/pages/CustomerAnalysis.tsx"
click node_dashboard_page "https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/frontend/src/pages/GeneralDashboard.tsx"
click node_customer_client "https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/frontend/src/services/customer.ts"
click node_analytics_client "https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/frontend/src/services/analytics.ts"
click node_api_service "https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/api/main.py"
click node_analytics_service "https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/analytics/service.py"
click node_analytics_queries "https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/analytics/queries.py"
click node_workflow "https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/llm/llm_graph.py"
click node_predictor "https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/src/inference/predictor.py"
click node_recommendation_schema "https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/llm/schemas.py"
click node_query_builder "https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/rag/query_builder.py"
click node_rag_pipeline "https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/rag/rag_pipeline.py"
click node_retriever "https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/rag/supabase_retriever.py"
click node_ingestion "https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/rag/supabase_ingest.py"
click node_retention_docs "https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/tree/main/rag/documents"

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_web_app,node_customer_page,node_dashboard_page,node_customer_client,node_analytics_client,node_operator toneBlue
class node_api_service,node_analytics_service,node_analytics_queries,node_database toneAmber
class node_workflow,node_predictor,node_recommendation_schema toneMint
class node_query_builder,node_rag_pipeline,node_retriever,node_ingestion,node_retention_docs toneRose
class node_gemini toneIndigo
```

## Components

### User experience

- [Web application](https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Customer analysis](https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/frontend/src/pages/CustomerAnalysis.tsx): `frontend/src/pages/CustomerAnalysis.tsx`
- [Analytics dashboard](https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/frontend/src/pages/GeneralDashboard.tsx): `frontend/src/pages/GeneralDashboard.tsx`
- [Customer API client](https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/frontend/src/services/customer.ts): `frontend/src/services/customer.ts`
- [Analytics API client](https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/frontend/src/services/analytics.ts): `frontend/src/services/analytics.ts`

### API and analytics

- [FastAPI endpoints](https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/api/main.py): `api/main.py`
- [Analytics assembly](https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/analytics/service.py): `analytics/service.py`
- [Analytics queries](https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/analytics/queries.py): `analytics/queries.py`
- **Supabase database**

### Churn analysis

- [Risk-routed workflow](https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/llm/llm_graph.py): `llm/llm_graph.py`
- [Churn prediction](https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/src/inference/predictor.py): `src/inference/predictor.py`
- [Recommendation schema](https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/llm/schemas.py): `llm/schemas.py`

### Retention knowledge

- [Retention query builder](https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/rag/query_builder.py): `rag/query_builder.py`
- [Knowledge retrieval pipeline](https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/rag/rag_pipeline.py): `rag/rag_pipeline.py`
- [Vector search retriever](https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/rag/supabase_retriever.py): `rag/supabase_retriever.py`
- [Knowledge ingestion](https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/blob/main/rag/supabase_ingest.py): `rag/supabase_ingest.py`
- [Retention documents](https://github.com/ryancjc/e-commerce-ai-ml-retention-platform/tree/main/rag/documents): `rag/documents`

### Other components

- **Platform user**
- **Google Gemini**

## Connections

- Platform user → Web application: uses (evidence: `README.md`)
- Web application → Customer analysis: renders (evidence: `frontend/src/App.tsx`)
- Web application → Analytics dashboard: renders (evidence: `frontend/src/App.tsx`)
- Customer analysis → Customer API client: requests analysis (evidence: `frontend/src/pages/CustomerAnalysis.tsx`)
- Analytics dashboard → Analytics API client: loads analytics (evidence: `frontend/src/pages/GeneralDashboard.tsx`)
- Customer API client → FastAPI endpoints: calls API
- Analytics API client → FastAPI endpoints: calls API
- FastAPI endpoints → Risk-routed workflow: invokes analysis (evidence: `api/main.py`)
- FastAPI endpoints → Supabase database: reads and writes (evidence: `api/main.py`)
- FastAPI endpoints → Analytics assembly: requests dashboard data (evidence: `api/main.py`)
- Analytics assembly → Analytics queries: calls queries (evidence: `analytics/service.py`)
- Risk-routed workflow → Churn prediction: scores and explains (evidence: `llm/llm_graph.py`)
- Risk-routed workflow → Knowledge retrieval pipeline: retrieves by risk (evidence: `llm/llm_graph.py`)
- Knowledge retrieval pipeline → Retention query builder: builds query (evidence: `rag/rag_pipeline.py`)
- Knowledge retrieval pipeline → Vector search retriever: searches knowledge (evidence: `rag/rag_pipeline.py`)
- Vector search retriever → Supabase database: vector similarity search (evidence: `rag/supabase_retriever.py`)
- Knowledge ingestion → Retention documents: chunks and embeds (evidence: `README.md`)
- Knowledge ingestion → Supabase database: stores vectors (evidence: `README.md`)
- Risk-routed workflow → Google Gemini: generates recommendation (evidence: `README.md`)
- Risk-routed workflow → Recommendation schema: formats output (evidence: `llm/llm_graph.py`)
