# bi8bo-bubblegum/ai-customer architecture

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

- Interactive diagram: https://gitdiagram.com/bi8bo-bubblegum/ai-customer
- Repository: https://github.com/bi8bo-bubblegum/ai-customer

## Overview

AI-Customer is a road-passenger AI customer-service application with a web client and FastAPI backend. Users authenticate, chat with a streamed multi-agent assistant, and can consult ticket, service, complaint, or general-intent handling; administrators also manage knowledge and work orders. The sampled chat service builds the agent graph, persists conversation messages, and emits model and tool events. The README provides no further capability details, and the graph, routers, and most agents were not sampled, so some subsystem wiring is intentionally left unspecified.

Main entry points: [`backend/app/main.py`](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/main.py) (FastAPI entry), [`backend/app/agents/graph.py`](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/agents/graph.py) (Agent graph), [`frontend/src/App.tsx`](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/frontend/src/App.tsx) (Web application), [`frontend/src/api/client.ts`](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/frontend/src/api/client.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web client"]
  node_app["Web application<br/>[App.tsx]"]
  node_chat_page["Chat page<br/>[Chat.tsx]"]
  node_knowledge_page["Knowledge page<br/>[Knowledge.tsx]"]
  node_orders_page["Work orders page<br/>[WorkOrders.tsx]"]
  node_auth_page["Login page<br/>[Login.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
  node_auth_api["Auth API<br/>[auth.ts]"]
  node_chat_api["Chat API<br/>[chat.ts]"]
  node_knowledge_api["Knowledge API<br/>[knowledge.ts]"]
  node_workorder_api["Work-order API<br/>[workorder.ts]"]
end

subgraph group_api["API and services"]
  node_fastapi["FastAPI entry<br/>[main.py]"]
  node_auth_service["Authentication<br/>[auth_service.py]"]
  node_chat_service["Chat orchestration<br/>[chat_service.py]"]
  node_knowledge_service["Knowledge service"]
  node_workorder_service["Work-order service"]
end

subgraph group_agents["Agent workflow"]
  node_agent_graph["Agent graph<br/>[graph.py]"]
  node_router_agent["Intent router<br/>[router_agent.py]"]
  node_ticket_agent["Ticket agent<br/>[ticket_agent.py]"]
  node_service_agent["Service agent<br/>[service_agent.py]"]
  node_complaint_agent["Complaint agent<br/>[complaint_agent.py]"]
  node_general_agent["General agent<br/>[general_agent.py]"]
  node_knowledge_tool["Knowledge search"]
  node_bus_tool["Bus query<br/>[bus_query.py]"]
  node_workorder_tool["Create work order"]
end

subgraph group_domain["Domain data"]
  node_user_repo["User repository<br/>[user_repo.py]"]
  node_message_repo["Message repository<br/>[message_repo.py]"]
  node_knowledge_repo["Knowledge repository<br/>[knowledge_repo.py]"]
  node_workorder_repo["Work-order repository<br/>[work_order_repo.py]"]
  node_route_repo["Bus route repository<br/>[bus_route_repo.py]"]
  node_database[("Application database<br/>[database.py]")]
end

subgraph group_integrations["External systems"]
  node_checkpoint[("Conversation checkpoints<br/>[main.py]")]
  node_llm{{"Language model"}}
end

node_customer(("Customer / admin"))

node_customer -->|"uses"| node_app
node_app -->|"routes"| node_auth_page
node_app -->|"routes"| node_chat_page
node_app -->|"routes"| node_knowledge_page
node_app -->|"routes"| node_orders_page
node_auth_page -->|"requests"| node_auth_api
node_chat_page -->|"requests"| node_chat_api
node_knowledge_page -->|"requests"| node_knowledge_api
node_orders_page -->|"requests"| node_workorder_api
node_auth_api -->|"uses"| node_api_client
node_chat_api -->|"uses"| node_api_client
node_knowledge_api -->|"uses"| node_api_client
node_workorder_api -->|"uses"| node_api_client
node_api_client -->|"HTTP requests"| node_fastapi
node_fastapi -->|"routes to"| node_auth_service
node_fastapi -->|"routes to"| node_chat_service
node_fastapi -->|"routes to"| node_knowledge_service
node_fastapi -->|"routes to"| node_workorder_service
node_auth_service -->|"reads / writes"| node_user_repo
node_chat_service -->|"builds and streams"| node_agent_graph
node_chat_service -->|"reads / writes"| node_message_repo
node_chat_service -->|"clears checkpoints"| node_checkpoint
node_agent_graph -->|"dispatches"| node_router_agent
node_agent_graph -->|"dispatches"| node_ticket_agent
node_agent_graph -->|"dispatches"| node_service_agent
node_agent_graph -->|"dispatches"| node_complaint_agent
node_agent_graph -->|"dispatches"| node_general_agent
node_router_agent -->|"classifies intent"| node_llm
node_service_agent -->|"calls"| node_knowledge_tool
node_service_agent -->|"prompts"| node_llm
node_ticket_agent -.->|"calls"| node_bus_tool
node_ticket_agent -.->|"prompts"| node_llm
node_complaint_agent -.->|"calls"| node_workorder_tool
node_general_agent -.->|"prompts"| node_llm
node_knowledge_tool -->|"searches"| node_knowledge_repo
node_bus_tool -->|"queries"| node_route_repo
node_workorder_tool -.->|"creates order"| node_workorder_service
node_knowledge_service -->|"reads / writes"| node_knowledge_repo
node_workorder_service -->|"reads / writes"| node_workorder_repo
node_user_repo -->|"persists users"| node_database
node_message_repo -->|"persists messages"| node_database
node_knowledge_repo -->|"persists knowledge"| node_database
node_workorder_repo -->|"persists orders"| node_database
node_route_repo -->|"reads routes"| node_database
node_fastapi -->|"initializes"| node_checkpoint

click node_app "https://github.com/bi8bo-bubblegum/ai-customer/blob/main/frontend/src/App.tsx"
click node_chat_page "https://github.com/bi8bo-bubblegum/ai-customer/blob/main/frontend/src/pages/Chat.tsx"
click node_knowledge_page "https://github.com/bi8bo-bubblegum/ai-customer/blob/main/frontend/src/pages/Knowledge.tsx"
click node_orders_page "https://github.com/bi8bo-bubblegum/ai-customer/blob/main/frontend/src/pages/WorkOrders.tsx"
click node_auth_page "https://github.com/bi8bo-bubblegum/ai-customer/blob/main/frontend/src/pages/Login.tsx"
click node_api_client "https://github.com/bi8bo-bubblegum/ai-customer/blob/main/frontend/src/api/client.ts"
click node_auth_api "https://github.com/bi8bo-bubblegum/ai-customer/blob/main/frontend/src/api/auth.ts"
click node_chat_api "https://github.com/bi8bo-bubblegum/ai-customer/blob/main/frontend/src/api/chat.ts"
click node_knowledge_api "https://github.com/bi8bo-bubblegum/ai-customer/blob/main/frontend/src/api/knowledge.ts"
click node_workorder_api "https://github.com/bi8bo-bubblegum/ai-customer/blob/main/frontend/src/api/workorder.ts"
click node_fastapi "https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/main.py"
click node_auth_service "https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/services/auth_service.py"
click node_chat_service "https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/services/chat_service.py"
click node_knowledge_service "https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/services/knowledge_service.py"
click node_workorder_service "https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/services/work_order_service.py"
click node_agent_graph "https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/agents/graph.py"
click node_router_agent "https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/agents/router_agent.py"
click node_ticket_agent "https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/agents/ticket_agent.py"
click node_service_agent "https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/agents/service_agent.py"
click node_complaint_agent "https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/agents/complaint_agent.py"
click node_general_agent "https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/agents/general_agent.py"
click node_knowledge_tool "https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/agents/tools/knowledge_search.py"
click node_bus_tool "https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/agents/tools/bus_query.py"
click node_workorder_tool "https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/agents/tools/create_work_order.py"
click node_user_repo "https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/repositories/user_repo.py"
click node_message_repo "https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/repositories/message_repo.py"
click node_knowledge_repo "https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/repositories/knowledge_repo.py"
click node_workorder_repo "https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/repositories/work_order_repo.py"
click node_route_repo "https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/repositories/bus_route_repo.py"
click node_database "https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/database.py"
click node_checkpoint "https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/main.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_chat_page,node_knowledge_page,node_orders_page,node_auth_page,node_api_client,node_auth_api,node_chat_api,node_knowledge_api,node_workorder_api toneBlue
class node_fastapi,node_auth_service,node_chat_service,node_knowledge_service,node_workorder_service toneAmber
class node_agent_graph,node_router_agent,node_ticket_agent,node_service_agent,node_complaint_agent,node_general_agent,node_knowledge_tool,node_bus_tool,node_workorder_tool toneMint
class node_user_repo,node_message_repo,node_knowledge_repo,node_workorder_repo,node_route_repo,node_database toneRose
class node_checkpoint,node_llm,node_customer toneIndigo
```

## Components

### Web client

- [Web application](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Chat page](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/frontend/src/pages/Chat.tsx): `frontend/src/pages/Chat.tsx`
- [Knowledge page](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/frontend/src/pages/Knowledge.tsx): `frontend/src/pages/Knowledge.tsx`
- [Work orders page](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/frontend/src/pages/WorkOrders.tsx): `frontend/src/pages/WorkOrders.tsx`
- [Login page](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/frontend/src/pages/Login.tsx): `frontend/src/pages/Login.tsx`
- [API client](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Auth API](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/frontend/src/api/auth.ts): `frontend/src/api/auth.ts`
- [Chat API](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/frontend/src/api/chat.ts): `frontend/src/api/chat.ts`
- [Knowledge API](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/frontend/src/api/knowledge.ts): `frontend/src/api/knowledge.ts`
- [Work-order API](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/frontend/src/api/workorder.ts): `frontend/src/api/workorder.ts`

### API and services

- [FastAPI entry](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/services/auth_service.py): `backend/app/services/auth_service.py`
- [Chat orchestration](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/services/chat_service.py): `backend/app/services/chat_service.py`
- [Knowledge service](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/services/knowledge_service.py): `backend/app/services/knowledge_service.py`
- [Work-order service](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/services/work_order_service.py): `backend/app/services/work_order_service.py`

### Agent workflow

- [Agent graph](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/agents/graph.py): `backend/app/agents/graph.py`
- [Intent router](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/agents/router_agent.py): `backend/app/agents/router_agent.py`
- [Ticket agent](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/agents/ticket_agent.py): `backend/app/agents/ticket_agent.py`
- [Service agent](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/agents/service_agent.py): `backend/app/agents/service_agent.py`
- [Complaint agent](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/agents/complaint_agent.py): `backend/app/agents/complaint_agent.py`
- [General agent](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/agents/general_agent.py): `backend/app/agents/general_agent.py`
- [Knowledge search](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/agents/tools/knowledge_search.py): `backend/app/agents/tools/knowledge_search.py`
- [Bus query](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/agents/tools/bus_query.py): `backend/app/agents/tools/bus_query.py`
- [Create work order](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/agents/tools/create_work_order.py): `backend/app/agents/tools/create_work_order.py`

### Domain data

- [User repository](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/repositories/user_repo.py): `backend/app/repositories/user_repo.py`
- [Message repository](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/repositories/message_repo.py): `backend/app/repositories/message_repo.py`
- [Knowledge repository](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/repositories/knowledge_repo.py): `backend/app/repositories/knowledge_repo.py`
- [Work-order repository](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/repositories/work_order_repo.py): `backend/app/repositories/work_order_repo.py`
- [Bus route repository](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/repositories/bus_route_repo.py): `backend/app/repositories/bus_route_repo.py`
- [Application database](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/database.py): `backend/app/database.py`

### External systems

- [Conversation checkpoints](https://github.com/bi8bo-bubblegum/ai-customer/blob/main/backend/app/main.py): `backend/app/main.py`
- **Language model**

### Other components

- **Customer / admin**

## Connections

- Customer / admin → Web application: uses
- Web application → Login page: routes
- Web application → Chat page: routes
- Web application → Knowledge page: routes
- Web application → Work orders page: routes
- Login page → Auth API: requests
- Chat page → Chat API: requests
- Knowledge page → Knowledge API: requests
- Work orders page → Work-order API: requests
- Auth API → API client: uses
- Chat API → API client: uses
- Knowledge API → API client: uses
- Work-order API → API client: uses
- API client → FastAPI entry: HTTP requests
- FastAPI entry → Authentication: routes to
- FastAPI entry → Chat orchestration: routes to
- FastAPI entry → Knowledge service: routes to
- FastAPI entry → Work-order service: routes to
- Authentication → User repository: reads / writes
- Chat orchestration → Agent graph: builds and streams
- Chat orchestration → Message repository: reads / writes
- Chat orchestration → Conversation checkpoints: clears checkpoints
- Agent graph → Intent router: dispatches
- Agent graph → Ticket agent: dispatches
- Agent graph → Service agent: dispatches
- Agent graph → Complaint agent: dispatches
- Agent graph → General agent: dispatches
- Intent router → Language model: classifies intent
- Service agent → Knowledge search: calls
- Service agent → Language model: prompts
- Ticket agent → Bus query: calls
- Ticket agent → Language model: prompts
- Complaint agent → Create work order: calls
- General agent → Language model: prompts
- Knowledge search → Knowledge repository: searches
- Bus query → Bus route repository: queries
- Create work order → Work-order service: creates order
- Knowledge service → Knowledge repository: reads / writes
- Work-order service → Work-order repository: reads / writes
- User repository → Application database: persists users
- Message repository → Application database: persists messages
- Knowledge repository → Application database: persists knowledge
- Work-order repository → Application database: persists orders
- Bus route repository → Application database: reads routes
- FastAPI entry → Conversation checkpoints: initializes