# thevj0000/supportpilot-ai architecture

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

- Interactive diagram: https://gitdiagram.com/thevj0000/supportpilot-ai
- Repository: https://github.com/thevj0000/supportpilot-ai

## Overview

SupportPilot is a multi-tenant customer-support platform: business users manage workspaces and knowledge, while customers ask questions through the hosted chat or an embedded widget. Knowledge is uploaded, processed and indexed; chat retrieves workspace-scoped evidence, generates a grounded response, rebuilds trusted citations and persists the conversation. Separate operations support feedback, human handoff, escalation triage and admin lifecycle controls. The graph emphasizes these product paths and the retrieval/generation layer. Relationships are based on the README, excerpts and SOURCE INDEX references; unsampled implementations and integrations are not treated as inspected.

Main entry points: [`backend/app/main.py`](https://github.com/thevj0000/supportpilot-ai/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/chat/service.py`](https://github.com/thevj0000/supportpilot-ai/blob/main/backend/app/chat/service.py) (Customer chat service), [`backend/app/rag/service.py`](https://github.com/thevj0000/supportpilot-ai/blob/main/backend/app/rag/service.py) (Knowledge retrieval), [`backend/app/rag/answering.py`](https://github.com/thevj0000/supportpilot-ai/blob/main/backend/app/rag/answering.py) (Grounded answering)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experiences"]
  node_business_ui["Business console<br/>[App.tsx]"]
  node_customer_chat_ui["Customer chat"]
  node_widget["Embeddable widget"]
  node_knowledge_ui["Knowledge manager"]
  node_admin_ui["Operations dashboard"]
end

subgraph group_domain["Support workflows"]
  node_knowledge_processing["Knowledge processing<br/>[service.py]"]
  node_chat_service["Customer chat service<br/>[service.py]"]
  node_escalations["Escalation triage<br/>[service.py]"]
  node_notifications["Notifications<br/>[service.py]"]
  node_admin_ops["Admin operations<br/>[gateway.py]"]
end

subgraph group_intelligence["AI and retrieval"]
  node_retrieval["Knowledge retrieval<br/>[service.py]"]
  node_answering["Grounded answering<br/>[answering.py]"]
  node_embeddings["Embedding provider<br/>[base.py]"]
  node_generation["Structured generation<br/>[base.py]"]
  node_rag_eval["RAG evaluation<br/>[deterministic.py]"]
end

subgraph group_platform["Platform services"]
  node_api["FastAPI application<br/>[main.py]"]
  node_auth["Workspace authorization<br/>[dependencies.py]"]
  node_knowledge_store[("Knowledge storage<br/>[gateway.py]")]
  node_chat_store[("Conversation storage<br/>[gateway.py]")]
  node_retrieval_store[("Vector retrieval gateway<br/>[gateway.py]")]
end

node_browser(("Customer / admin"))
node_gemini{{"Google Gemini"}}
node_supabase[("Supabase platform")]

node_browser -->|"uses"| node_business_ui
node_browser -->|"asks support"| node_customer_chat_ui
node_widget -->|"embeds chat"| node_customer_chat_ui
node_business_ui -->|"manages knowledge"| node_knowledge_ui
node_business_ui -->|"opens operations"| node_admin_ui
node_customer_chat_ui -->|"sends chat requests"| node_api
node_knowledge_ui -->|"manages sources"| node_api
node_admin_ui -->|"loads operations"| node_api
node_api -->|"routes protected access"| node_auth
node_api -.->|"routes chat"| node_chat_service
node_api -.->|"routes processing"| node_knowledge_processing
node_api -.->|"routes admin"| node_admin_ops
node_knowledge_processing -->|"reads and writes"| node_knowledge_store
node_chat_service -->|"persists turns"| node_chat_store
node_chat_service -->|"requests evidence"| node_retrieval
node_chat_service -->|"grounds response"| node_answering
node_retrieval -->|"embeds query"| node_embeddings
node_retrieval -->|"searches vectors"| node_retrieval_store
node_answering -->|"retrieves evidence"| node_retrieval
node_answering -->|"generates decision"| node_generation
node_generation -.->|"calls provider"| node_gemini
node_embeddings -.->|"calls provider"| node_gemini
node_chat_service -.->|"requests handoff"| node_escalations
node_escalations -.->|"notifies teams"| node_notifications
node_escalations -.->|"triages conversation"| node_gemini
node_admin_ops -.->|"manages records"| node_supabase
node_knowledge_store -.->|"stores knowledge"| node_supabase
node_chat_store -.->|"stores conversations"| node_supabase
node_retrieval_store -.->|"queries pgvector"| node_supabase
node_rag_eval -->|"evaluates retrieval"| node_retrieval
node_rag_eval -->|"measures answers"| node_answering

click node_business_ui "https://github.com/thevj0000/supportpilot-ai/blob/main/frontend/src/App.tsx"
click node_customer_chat_ui "https://github.com/thevj0000/supportpilot-ai/blob/main/frontend/src/pages/CustomerChatPage.tsx"
click node_widget "https://github.com/thevj0000/supportpilot-ai/blob/main/frontend/public/supportpilot-widget.js"
click node_knowledge_ui "https://github.com/thevj0000/supportpilot-ai/blob/main/frontend/src/knowledge/useKnowledgeSources.ts"
click node_admin_ui "https://github.com/thevj0000/supportpilot-ai/tree/main/frontend/src/admin"
click node_api "https://github.com/thevj0000/supportpilot-ai/blob/main/backend/app/main.py"
click node_auth "https://github.com/thevj0000/supportpilot-ai/blob/main/backend/app/auth/dependencies.py"
click node_knowledge_processing "https://github.com/thevj0000/supportpilot-ai/blob/main/backend/app/knowledge/service.py"
click node_knowledge_store "https://github.com/thevj0000/supportpilot-ai/blob/main/backend/app/knowledge/gateway.py"
click node_chat_service "https://github.com/thevj0000/supportpilot-ai/blob/main/backend/app/chat/service.py"
click node_chat_store "https://github.com/thevj0000/supportpilot-ai/blob/main/backend/app/chat/gateway.py"
click node_retrieval "https://github.com/thevj0000/supportpilot-ai/blob/main/backend/app/rag/service.py"
click node_retrieval_store "https://github.com/thevj0000/supportpilot-ai/blob/main/backend/app/rag/gateway.py"
click node_answering "https://github.com/thevj0000/supportpilot-ai/blob/main/backend/app/rag/answering.py"
click node_embeddings "https://github.com/thevj0000/supportpilot-ai/blob/main/backend/app/ai/embeddings/base.py"
click node_generation "https://github.com/thevj0000/supportpilot-ai/blob/main/backend/app/ai/generation/base.py"
click node_escalations "https://github.com/thevj0000/supportpilot-ai/blob/main/backend/app/escalations/service.py"
click node_notifications "https://github.com/thevj0000/supportpilot-ai/blob/main/backend/app/notifications/service.py"
click node_admin_ops "https://github.com/thevj0000/supportpilot-ai/blob/main/backend/app/admin/gateway.py"
click node_rag_eval "https://github.com/thevj0000/supportpilot-ai/blob/main/backend/evals/rag/deterministic.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_business_ui,node_customer_chat_ui,node_widget,node_knowledge_ui,node_admin_ui toneBlue
class node_knowledge_processing,node_chat_service,node_escalations,node_notifications,node_admin_ops,node_supabase toneAmber
class node_retrieval,node_answering,node_embeddings,node_generation,node_rag_eval toneMint
class node_api,node_auth,node_knowledge_store,node_chat_store,node_retrieval_store toneRose
class node_browser,node_gemini toneIndigo
```

## Components

### Web experiences

- [Business console](https://github.com/thevj0000/supportpilot-ai/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Customer chat](https://github.com/thevj0000/supportpilot-ai/blob/main/frontend/src/pages/CustomerChatPage.tsx): `frontend/src/pages/CustomerChatPage.tsx`
- [Embeddable widget](https://github.com/thevj0000/supportpilot-ai/blob/main/frontend/public/supportpilot-widget.js): `frontend/public/supportpilot-widget.js`
- [Knowledge manager](https://github.com/thevj0000/supportpilot-ai/blob/main/frontend/src/knowledge/useKnowledgeSources.ts): `frontend/src/knowledge/useKnowledgeSources.ts`
- [Operations dashboard](https://github.com/thevj0000/supportpilot-ai/tree/main/frontend/src/admin): `frontend/src/admin`

### Support workflows

- [Knowledge processing](https://github.com/thevj0000/supportpilot-ai/blob/main/backend/app/knowledge/service.py): `backend/app/knowledge/service.py`
- [Customer chat service](https://github.com/thevj0000/supportpilot-ai/blob/main/backend/app/chat/service.py): `backend/app/chat/service.py`
- [Escalation triage](https://github.com/thevj0000/supportpilot-ai/blob/main/backend/app/escalations/service.py): `backend/app/escalations/service.py`
- [Notifications](https://github.com/thevj0000/supportpilot-ai/blob/main/backend/app/notifications/service.py): `backend/app/notifications/service.py`
- [Admin operations](https://github.com/thevj0000/supportpilot-ai/blob/main/backend/app/admin/gateway.py): `backend/app/admin/gateway.py`

### AI and retrieval

- [Knowledge retrieval](https://github.com/thevj0000/supportpilot-ai/blob/main/backend/app/rag/service.py): `backend/app/rag/service.py`
- [Grounded answering](https://github.com/thevj0000/supportpilot-ai/blob/main/backend/app/rag/answering.py): `backend/app/rag/answering.py`
- [Embedding provider](https://github.com/thevj0000/supportpilot-ai/blob/main/backend/app/ai/embeddings/base.py): `backend/app/ai/embeddings/base.py`
- [Structured generation](https://github.com/thevj0000/supportpilot-ai/blob/main/backend/app/ai/generation/base.py): `backend/app/ai/generation/base.py`
- [RAG evaluation](https://github.com/thevj0000/supportpilot-ai/blob/main/backend/evals/rag/deterministic.py): `backend/evals/rag/deterministic.py`

### Platform services

- [FastAPI application](https://github.com/thevj0000/supportpilot-ai/blob/main/backend/app/main.py): `backend/app/main.py`
- [Workspace authorization](https://github.com/thevj0000/supportpilot-ai/blob/main/backend/app/auth/dependencies.py): `backend/app/auth/dependencies.py`
- [Knowledge storage](https://github.com/thevj0000/supportpilot-ai/blob/main/backend/app/knowledge/gateway.py): `backend/app/knowledge/gateway.py`
- [Conversation storage](https://github.com/thevj0000/supportpilot-ai/blob/main/backend/app/chat/gateway.py): `backend/app/chat/gateway.py`
- [Vector retrieval gateway](https://github.com/thevj0000/supportpilot-ai/blob/main/backend/app/rag/gateway.py): `backend/app/rag/gateway.py`

### Other components

- **Customer / admin**
- **Google Gemini**
- **Supabase platform**

## Connections

- Customer / admin → Business console: uses (evidence: `README.md`)
- Customer / admin → Customer chat: asks support (evidence: `README.md`)
- Embeddable widget → Customer chat: embeds chat (evidence: `README.md`)
- Business console → Knowledge manager: manages knowledge (evidence: `frontend/src/App.tsx`)
- Business console → Operations dashboard: opens operations (evidence: `frontend/src/App.tsx`)
- Customer chat → FastAPI application: sends chat requests (evidence: `README.md`)
- Knowledge manager → FastAPI application: manages sources (evidence: `README.md`)
- Operations dashboard → FastAPI application: loads operations (evidence: `README.md`)
- FastAPI application → Workspace authorization: routes protected access
- FastAPI application → Customer chat service: routes chat
- FastAPI application → Knowledge processing: routes processing
- FastAPI application → Admin operations: routes admin
- Knowledge processing → Knowledge storage: reads and writes (evidence: `backend/app/knowledge/service.py`)
- Customer chat service → Conversation storage: persists turns (evidence: `backend/app/chat/service.py`)
- Customer chat service → Knowledge retrieval: requests evidence (evidence: `backend/app/chat/service.py`)
- Customer chat service → Grounded answering: grounds response (evidence: `backend/app/chat/service.py`)
- Knowledge retrieval → Embedding provider: embeds query (evidence: `backend/app/rag/service.py`)
- Knowledge retrieval → Vector retrieval gateway: searches vectors (evidence: `backend/app/rag/service.py`)
- Grounded answering → Knowledge retrieval: retrieves evidence (evidence: `backend/app/rag/answering.py`)
- Grounded answering → Structured generation: generates decision (evidence: `backend/app/rag/answering.py`)
- Structured generation → Google Gemini: calls provider (evidence: `README.md`)
- Embedding provider → Google Gemini: calls provider (evidence: `README.md`)
- Customer chat service → Escalation triage: requests handoff (evidence: `README.md`)
- Escalation triage → Notifications: notifies teams
- Escalation triage → Google Gemini: triages conversation (evidence: `README.md`)
- Admin operations → Supabase platform: manages records (evidence: `README.md`)
- Knowledge storage → Supabase platform: stores knowledge (evidence: `README.md`)
- Conversation storage → Supabase platform: stores conversations (evidence: `README.md`)
- Vector retrieval gateway → Supabase platform: queries pgvector (evidence: `README.md`)
- RAG evaluation → Knowledge retrieval: evaluates retrieval (evidence: `backend/evals/rag/hosted.py`)
- RAG evaluation → Grounded answering: measures answers
