# kcjiang/friendly-ai-explorer architecture

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

- Interactive diagram: https://gitdiagram.com/kcjiang/friendly-ai-explorer
- Repository: https://github.com/kcjiang/friendly-ai-explorer

## Overview

Friendly AI Explorer is a support-team workspace spanning ticket management, a searchable knowledge base, AI assistance, email-to-ticket review, dashboards, and device-debug tools. The principal user flow enters through the Next.js application and FastAPI API; users can manage tickets or documents, while published knowledge is embedded for retrieval-augmented answers. Email sync imports messages for analysis and lets users approve generated pre-tickets into real tickets. The graph preserves README capabilities, but several frontend-to-endpoint and unsampled service links are intentionally omitted where sampled source does not establish the exact wiring.

Main entry points: [`backend/app/main.py`](https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/main.py) (FastAPI entry), [`backend/app/database.py`](https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/database.py) (PostgreSQL / pgvector), [`backend/app/ai/rag_engine.py`](https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/ai/rag_engine.py) (RAG retrieval), [`frontend/src/app/(app)`](https://github.com/kcjiang/friendly-ai-explorer/tree/main/frontend/src/app/(app)) (Workspace pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_web["Workspace pages"]
  node_authjs["Web sign-in<br/>[auth.ts]"]
  node_api_client["API client<br/>[api.ts]"]
  node_debug["Device debug<br/>[adb-webusb.ts]"]
end

subgraph group_api["API and workflows"]
  node_api_entry["FastAPI entry<br/>[main.py]"]
  node_auth_routes["Auth routes<br/>[auth.py]"]
  node_ticket_routes["Ticket routes<br/>[tickets.py]"]
  node_knowledge_routes["Knowledge routes<br/>[knowledge.py]"]
  node_ai_routes["AI routes<br/>[ai.py]"]
  node_email_routes["Email routes<br/>[email_router.py]"]
  node_debug_routes["Debug routes<br/>[preset_router.py]"]
  node_auth_service["Auth service<br/>[auth_service.py]"]
  node_email_service["Email workflow<br/>[email_service.py]"]
  node_ticket_service["Ticket service<br/>[ticket_service.py]"]
end

subgraph group_ai["AI and knowledge"]
  node_knowledge_service["Knowledge service"]
  node_ai_service["AI service<br/>[ai_service.py]"]
  node_rag["RAG retrieval<br/>[rag_engine.py]"]
  node_embeddings["Text embeddings<br/>[embeddings.py]"]
  node_email_analyzer["Email analyzer<br/>[email_analyzer.py]"]
  node_gemini["Gemini models<br/>[gemini_client.py]"]
end

subgraph group_state["State and integrations"]
  node_database[("PostgreSQL / pgvector<br/>[database.py]")]
  node_imap["IMAP mailbox"]
  node_webusb["WebUSB device"]
end

node_user(("Support user"))

node_user -->|"uses"| node_web
node_web -->|"requests data"| node_api_client
node_web -->|"signs in"| node_authjs
node_user -->|"debugs device"| node_debug
node_debug -->|"connects"| node_webusb
node_authjs -->|"posts credentials"| node_auth_routes
node_api_client -->|"calls API"| node_api_entry
node_api_entry -->|"dispatches"| node_auth_routes
node_api_entry -->|"dispatches"| node_ticket_routes
node_api_entry -->|"dispatches"| node_knowledge_routes
node_api_entry -->|"dispatches"| node_ai_routes
node_api_entry -->|"dispatches"| node_email_routes
node_api_entry -->|"dispatches"| node_debug_routes
node_auth_routes -->|"calls"| node_auth_service
node_email_routes -->|"calls"| node_email_service
node_ticket_routes -->|"calls"| node_ticket_service
node_knowledge_routes -->|"calls"| node_knowledge_service
node_ai_routes -->|"calls"| node_ai_service
node_email_service -->|"fetches mail"| node_imap
node_knowledge_service -->|"creates vectors"| node_embeddings
node_rag -->|"embeds query"| node_embeddings
node_rag -->|"searches vectors"| node_database
node_knowledge_service -->|"stores documents"| node_database
node_auth_service -->|"reads users"| node_database
node_email_service -->|"stores mail and tickets"| node_database
node_ticket_service -->|"manages tickets"| node_database
node_email_analyzer -.->|"uses model"| node_gemini
node_rag -.->|"generates answers"| node_gemini

click node_web "https://github.com/kcjiang/friendly-ai-explorer/tree/main/frontend/src/app/(app)"
click node_authjs "https://github.com/kcjiang/friendly-ai-explorer/blob/main/frontend/auth.ts"
click node_api_client "https://github.com/kcjiang/friendly-ai-explorer/blob/main/frontend/src/lib/api.ts"
click node_debug "https://github.com/kcjiang/friendly-ai-explorer/blob/main/frontend/src/lib/adb-webusb.ts"
click node_api_entry "https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/main.py"
click node_auth_routes "https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/routers/auth.py"
click node_ticket_routes "https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/routers/tickets.py"
click node_knowledge_routes "https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/routers/knowledge.py"
click node_ai_routes "https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/routers/ai.py"
click node_email_routes "https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/routers/email_router.py"
click node_debug_routes "https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/routers/preset_router.py"
click node_auth_service "https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/services/auth_service.py"
click node_email_service "https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/services/email_service.py"
click node_ticket_service "https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/services/ticket_service.py"
click node_knowledge_service "https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/services/knowledge_service.py"
click node_ai_service "https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/services/ai_service.py"
click node_rag "https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/ai/rag_engine.py"
click node_embeddings "https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/ai/embeddings.py"
click node_email_analyzer "https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/ai/tasks/email_analyzer.py"
click node_gemini "https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/ai/gemini_client.py"
click node_database "https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/database.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_web,node_authjs,node_api_client,node_debug,node_user toneBlue
class node_api_entry,node_auth_routes,node_ticket_routes,node_knowledge_routes,node_ai_routes,node_email_routes,node_debug_routes,node_auth_service,node_email_service,node_ticket_service toneAmber
class node_knowledge_service,node_ai_service,node_rag,node_embeddings,node_email_analyzer,node_gemini toneMint
class node_database,node_imap,node_webusb toneRose
```

## Components

### Web application

- [Workspace pages](https://github.com/kcjiang/friendly-ai-explorer/tree/main/frontend/src/app/(app)): `frontend/src/app/(app)`
- [Web sign-in](https://github.com/kcjiang/friendly-ai-explorer/blob/main/frontend/auth.ts): `frontend/auth.ts`
- [API client](https://github.com/kcjiang/friendly-ai-explorer/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Device debug](https://github.com/kcjiang/friendly-ai-explorer/blob/main/frontend/src/lib/adb-webusb.ts): `frontend/src/lib/adb-webusb.ts`

### API and workflows

- [FastAPI entry](https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/main.py): `backend/app/main.py`
- [Auth routes](https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Ticket routes](https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/routers/tickets.py): `backend/app/routers/tickets.py`
- [Knowledge routes](https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/routers/knowledge.py): `backend/app/routers/knowledge.py`
- [AI routes](https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/routers/ai.py): `backend/app/routers/ai.py`
- [Email routes](https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/routers/email_router.py): `backend/app/routers/email_router.py`
- [Debug routes](https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/routers/preset_router.py): `backend/app/routers/preset_router.py`
- [Auth service](https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/services/auth_service.py): `backend/app/services/auth_service.py`
- [Email workflow](https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/services/email_service.py): `backend/app/services/email_service.py`
- [Ticket service](https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/services/ticket_service.py): `backend/app/services/ticket_service.py`

### AI and knowledge

- [Knowledge service](https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/services/knowledge_service.py): `backend/app/services/knowledge_service.py`
- [AI service](https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/services/ai_service.py): `backend/app/services/ai_service.py`
- [RAG retrieval](https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/ai/rag_engine.py): `backend/app/ai/rag_engine.py`
- [Text embeddings](https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/ai/embeddings.py): `backend/app/ai/embeddings.py`
- [Email analyzer](https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/ai/tasks/email_analyzer.py): `backend/app/ai/tasks/email_analyzer.py`
- [Gemini models](https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/ai/gemini_client.py): `backend/app/ai/gemini_client.py`

### State and integrations

- [PostgreSQL / pgvector](https://github.com/kcjiang/friendly-ai-explorer/blob/main/backend/app/database.py): `backend/app/database.py`
- **IMAP mailbox**
- **WebUSB device**

### Other components

- **Support user**

## Connections

- Support user → Workspace pages: uses
- Workspace pages → API client: requests data
- Workspace pages → Web sign-in: signs in
- Support user → Device debug: debugs device
- Device debug → WebUSB device: connects
- Web sign-in → Auth routes: posts credentials
- API client → FastAPI entry: calls API
- FastAPI entry → Auth routes: dispatches
- FastAPI entry → Ticket routes: dispatches
- FastAPI entry → Knowledge routes: dispatches
- FastAPI entry → AI routes: dispatches
- FastAPI entry → Email routes: dispatches
- FastAPI entry → Debug routes: dispatches
- Auth routes → Auth service: calls
- Email routes → Email workflow: calls
- Ticket routes → Ticket service: calls
- Knowledge routes → Knowledge service: calls
- AI routes → AI service: calls
- Email workflow → IMAP mailbox: fetches mail
- Knowledge service → Text embeddings: creates vectors
- RAG retrieval → Text embeddings: embeds query
- RAG retrieval → PostgreSQL / pgvector: searches vectors
- Knowledge service → PostgreSQL / pgvector: stores documents
- Auth service → PostgreSQL / pgvector: reads users
- Email workflow → PostgreSQL / pgvector: stores mail and tickets
- Ticket service → PostgreSQL / pgvector: manages tickets
- Email analyzer → Gemini models: uses model
- RAG retrieval → Gemini models: generates answers