# rojasantino/shoppilot-multi-agent-ai-customer-operations-platform architecture

> Architecture diagram of the GitHub repository rojasantino/shoppilot-multi-agent-ai-customer-operations-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform
- Repository: https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform

## Overview

ShopPilot is a customer-operations platform: customers chat with a supervisor that routes requests to order, returns, product, or policy specialists; replies are reviewed, and refund requests remain pending for staff approval. Staff can decide approvals and explore policy vectors through separate UI pages. The graph also shows the API, retrieval, and persistence layers. Some routes and internal wiring are represented from README documentation and the SOURCE INDEX; unsampled implementations are not inferred beyond those references.

Main entry points: [`backend/app/agents/nodes.py`](https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/agents/nodes.py) (Specialist agents), [`backend/app/agents/graph.py`](https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/agents/graph.py) (Supervisor graph), [`frontend/api_client.py`](https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/frontend/api_client.py) (API client), [`backend/app/api/routes/admin.py`](https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/api/routes/admin.py) (Admin endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interfaces"]
  node_chat_ui["Chat UI<br/>[app.py]"]
  node_approvals_ui["Approvals UI<br/>[1_Approvals.py]"]
  node_vector_ui["Vector Explorer"]
  node_api_client["API client<br/>[api_client.py]"]
end

subgraph group_api["API and access"]
  node_app["FastAPI app<br/>[main.py]"]
  node_chat_route["Chat endpoint<br/>[chat.py]"]
  node_admin_route["Admin endpoints<br/>[admin.py]"]
end

subgraph group_agents["Agent workflow"]
  node_graph["Supervisor graph<br/>[graph.py]"]
  node_intent["Intent routing<br/>[intent.py]"]
  node_specialists["Specialist agents<br/>[nodes.py]"]
  node_reviewer["Reply reviewer<br/>[reviewer.py]"]
  node_composer["Reply composer<br/>[composer.py]"]
end

subgraph group_services["Business and retrieval services"]
  node_return_policy["Return rules<br/>[return_policy.py]"]
  node_llm["LLM provider<br/>[llm.py]"]
  node_rag["Policy retrieval<br/>[rag.py]"]
  node_embedder["Embedder<br/>[embeddings.py]"]
  node_cache["Redis cache<br/>[cache.py]"]
end

subgraph group_data["Persistence"]
  node_orders["Order data access<br/>[orders.py]"]
  node_products["Product data access<br/>[products.py]"]
  node_approvals["Approval records<br/>[approvals.py]"]
  node_knowledge_repo["Knowledge access<br/>[knowledge.py]"]
  node_database[("PostgreSQL + pgvector<br/>[models.py]")]
end

node_customer(("Customer"))
node_staff(("Staff"))

node_customer -->|"sends message"| node_chat_ui
node_staff -->|"reviews requests"| node_approvals_ui
node_staff -->|"explores vectors"| node_vector_ui
node_chat_ui -->|"uses"| node_api_client
node_approvals_ui -->|"uses"| node_api_client
node_vector_ui -->|"uses"| node_api_client
node_api_client -->|"posts chat"| node_chat_route
node_api_client -->|"requests admin data"| node_admin_route
node_app -->|"registers route"| node_chat_route
node_app -->|"registers route"| node_admin_route
node_chat_route -->|"runs workflow"| node_graph
node_graph -->|"routes intent"| node_intent
node_graph -->|"dispatches"| node_specialists
node_graph -->|"reviews reply"| node_reviewer
node_graph -->|"composes reply"| node_composer
node_specialists -->|"checks eligibility"| node_return_policy
node_specialists -->|"looks up orders"| node_orders
node_specialists -->|"looks up products"| node_products
node_specialists -->|"creates pending requests"| node_approvals
node_intent -.->|"may classify with"| node_llm
node_composer -.->|"generates wording"| node_llm
node_specialists -.->|"retrieves policy"| node_rag
node_rag -->|"embeds query"| node_embedder
node_rag -->|"searches vectors"| node_knowledge_repo
node_admin_route -->|"lists and decides"| node_approvals
node_admin_route -->|"lists and searches"| node_knowledge_repo
node_orders -->|"reads"| node_database
node_products -->|"reads"| node_database
node_approvals -->|"reads and writes"| node_database
node_knowledge_repo -->|"reads and writes vectors"| node_database

click node_chat_ui "https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/frontend/app.py"
click node_approvals_ui "https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/frontend/pages/1_Approvals.py"
click node_vector_ui "https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/frontend/pages/2_Vector_Explorer.py"
click node_api_client "https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/frontend/api_client.py"
click node_app "https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/main.py"
click node_chat_route "https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/api/routes/chat.py"
click node_admin_route "https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/api/routes/admin.py"
click node_graph "https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/agents/graph.py"
click node_intent "https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/agents/intent.py"
click node_specialists "https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/agents/nodes.py"
click node_reviewer "https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/agents/reviewer.py"
click node_composer "https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/agents/composer.py"
click node_return_policy "https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/services/return_policy.py"
click node_llm "https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/services/llm.py"
click node_rag "https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/services/rag.py"
click node_embedder "https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/services/embeddings.py"
click node_cache "https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/services/cache.py"
click node_orders "https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/repositories/orders.py"
click node_products "https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/repositories/products.py"
click node_approvals "https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/repositories/approvals.py"
click node_knowledge_repo "https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/repositories/knowledge.py"
click node_database "https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/db/models.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_chat_ui,node_approvals_ui,node_vector_ui,node_api_client toneBlue
class node_app,node_chat_route,node_admin_route toneAmber
class node_graph,node_intent,node_specialists,node_reviewer,node_composer toneMint
class node_return_policy,node_llm,node_rag,node_embedder,node_cache toneRose
class node_orders,node_products,node_approvals,node_knowledge_repo,node_database,node_customer,node_staff toneIndigo
```

## Components

### User interfaces

- [Chat UI](https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/frontend/app.py): `frontend/app.py`
- [Approvals UI](https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/frontend/pages/1_Approvals.py): `frontend/pages/1_Approvals.py`
- [Vector Explorer](https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/frontend/pages/2_Vector_Explorer.py): `frontend/pages/2_Vector_Explorer.py`
- [API client](https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/frontend/api_client.py): `frontend/api_client.py`

### API and access

- [FastAPI app](https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/main.py): `backend/app/main.py`
- [Chat endpoint](https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/api/routes/chat.py): `backend/app/api/routes/chat.py`
- [Admin endpoints](https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/api/routes/admin.py): `backend/app/api/routes/admin.py`

### Agent workflow

- [Supervisor graph](https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/agents/graph.py): `backend/app/agents/graph.py`
- [Intent routing](https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/agents/intent.py): `backend/app/agents/intent.py`
- [Specialist agents](https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/agents/nodes.py): `backend/app/agents/nodes.py`
- [Reply reviewer](https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/agents/reviewer.py): `backend/app/agents/reviewer.py`
- [Reply composer](https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/agents/composer.py): `backend/app/agents/composer.py`

### Business and retrieval services

- [Return rules](https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/services/return_policy.py): `backend/app/services/return_policy.py`
- [LLM provider](https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/services/llm.py): `backend/app/services/llm.py`
- [Policy retrieval](https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/services/rag.py): `backend/app/services/rag.py`
- [Embedder](https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/services/embeddings.py): `backend/app/services/embeddings.py`
- [Redis cache](https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/services/cache.py): `backend/app/services/cache.py`

### Persistence

- [Order data access](https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/repositories/orders.py): `backend/app/repositories/orders.py`
- [Product data access](https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/repositories/products.py): `backend/app/repositories/products.py`
- [Approval records](https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/repositories/approvals.py): `backend/app/repositories/approvals.py`
- [Knowledge access](https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/repositories/knowledge.py): `backend/app/repositories/knowledge.py`
- [PostgreSQL + pgvector](https://github.com/rojasantino/shoppilot-multi-agent-ai-customer-operations-platform/blob/main/backend/app/db/models.py): `backend/app/db/models.py`

### Other components

- **Customer**
- **Staff**

## Connections

- Customer → Chat UI: sends message
- Staff → Approvals UI: reviews requests
- Staff → Vector Explorer: explores vectors
- Chat UI → API client: uses (evidence: `frontend/app.py`)
- Approvals UI → API client: uses (evidence: `frontend/pages/1_Approvals.py`)
- Vector Explorer → API client: uses (evidence: `frontend/pages/2_Vector_Explorer.py`)
- API client → Chat endpoint: posts chat (evidence: `frontend/api_client.py`)
- API client → Admin endpoints: requests admin data (evidence: `frontend/api_client.py`)
- FastAPI app → Chat endpoint: registers route (evidence: `backend/app/main.py`)
- FastAPI app → Admin endpoints: registers route (evidence: `backend/app/main.py`)
- Chat endpoint → Supervisor graph: runs workflow
- Supervisor graph → Intent routing: routes intent (evidence: `backend/app/agents/graph.py`)
- Supervisor graph → Specialist agents: dispatches (evidence: `backend/app/agents/graph.py`)
- Supervisor graph → Reply reviewer: reviews reply (evidence: `backend/app/agents/graph.py`)
- Supervisor graph → Reply composer: composes reply (evidence: `backend/app/agents/graph.py`)
- Specialist agents → Return rules: checks eligibility (evidence: `backend/app/agents/nodes.py`)
- Specialist agents → Order data access: looks up orders (evidence: `backend/app/agents/nodes.py`)
- Specialist agents → Product data access: looks up products (evidence: `backend/app/agents/nodes.py`)
- Specialist agents → Approval records: creates pending requests (evidence: `backend/app/agents/nodes.py`)
- Intent routing → LLM provider: may classify with (evidence: `backend/app/agents/intent.py`)
- Reply composer → LLM provider: generates wording (evidence: `backend/app/agents/composer.py`)
- Specialist agents → Policy retrieval: retrieves policy
- Policy retrieval → Embedder: embeds query (evidence: `backend/app/services/rag.py`)
- Policy retrieval → Knowledge access: searches vectors (evidence: `backend/app/services/rag.py`)
- Admin endpoints → Approval records: lists and decides (evidence: `backend/app/api/routes/admin.py`)
- Admin endpoints → Knowledge access: lists and searches (evidence: `backend/app/api/routes/admin.py`)
- Order data access → PostgreSQL + pgvector: reads (evidence: `backend/app/repositories/orders.py`)
- Product data access → PostgreSQL + pgvector: reads (evidence: `backend/app/repositories/products.py`)
- Approval records → PostgreSQL + pgvector: reads and writes (evidence: `backend/app/repositories/approvals.py`)
- Knowledge access → PostgreSQL + pgvector: reads and writes vectors (evidence: `backend/app/repositories/knowledge.py`)
