# mahenoor-mehtab/chatcore architecture

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

- Interactive diagram: https://gitdiagram.com/mahenoor-mehtab/chatcore
- Repository: https://github.com/mahenoor-mehtab/chatcore

## Overview

ChatCore is a multi-tenant support platform: customers ask questions through a website widget, Convex-backed conversation handling grounds AI answers in organizational knowledge, and unresolved threads can reach the operator dashboard. The README also describes voice, team management, billing, and per-organization widget settings. The tree contains no embed-loader directory, so that documented entry point is not represented; backend feature wiring beyond the sampled schema, messages, and users files is based on README descriptions rather than inspected implementations.

Main entry points: [`apps/web/app/page.tsx`](https://github.com/mahenoor-mehtab/chatcore/blob/main/apps/web/app/page.tsx) (Operator dashboard), [`apps/widget/app/page.tsx`](https://github.com/mahenoor-mehtab/chatcore/blob/main/apps/widget/app/page.tsx) (Chat widget), [`packages/backend/convex`](https://github.com/mahenoor-mehtab/chatcore/tree/main/packages/backend/convex) (AI conversation agent), [`packages/backend/convex/messages.ts`](https://github.com/mahenoor-mehtab/chatcore/blob/main/packages/backend/convex/messages.ts) (Conversation messages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_customer["Customer experience"]
  node_widget["Chat widget<br/>[page.tsx]"]
  node_voice["Voice support<br/>[page.tsx]"]
end

subgraph group_backend["Conversation backend"]
  node_knowledge["Knowledge and RAG"]
  node_agent["AI conversation agent"]
  node_handoff["Human handoff"]
  node_messages["Conversation messages<br/>[messages.ts]"]
  node_users["Users and tenants<br/>[users.ts]"]
  node_schema["Data schema<br/>[schema.ts]"]
  node_convex[("Convex data")]
end

subgraph group_operator["Operator platform"]
  node_dashboard["Operator dashboard<br/>[page.tsx]"]
  node_widgetsettings["Widget settings"]
  node_billing["Plans and billing"]
end

subgraph group_identity["Identity and services"]
  node_clerk["Clerk identity"]
  node_vapi["Vapi voice"]
end

node_visitor(("Customer"))
node_operator(("Support operator"))

node_visitor -->|"asks question"| node_widget
node_widget -->|"submits question"| node_agent
node_agent -->|"retrieves context"| node_knowledge
node_agent -->|"records conversation"| node_messages
node_agent -->|"streams answer"| node_widget
node_agent -->|"escalates unresolved"| node_handoff
node_handoff -->|"surfaces thread"| node_dashboard
node_operator -->|"manages inbox"| node_dashboard
node_dashboard -->|"views conversations"| node_messages
node_schema -->|"defines tables"| node_convex
node_messages -->|"reads and writes"| node_convex
node_users -->|"reads and writes"| node_convex
node_dashboard -->|"manages appearance"| node_widgetsettings
node_widgetsettings -->|"provides configuration"| node_widget
node_widget -->|"offers voice"| node_voice
node_voice -.->|"uses voice service"| node_vapi
node_dashboard -->|"manages subscription"| node_billing
node_dashboard -->|"authenticates"| node_clerk
node_widget -->|"protects routes"| node_clerk
node_clerk -.->|"authenticates backend"| node_convex

click node_widget "https://github.com/mahenoor-mehtab/chatcore/blob/main/apps/widget/app/page.tsx"
click node_voice "https://github.com/mahenoor-mehtab/chatcore/blob/main/apps/widget/app/page.tsx"
click node_dashboard "https://github.com/mahenoor-mehtab/chatcore/blob/main/apps/web/app/page.tsx"
click node_knowledge "https://github.com/mahenoor-mehtab/chatcore/tree/main/packages/backend/convex"
click node_agent "https://github.com/mahenoor-mehtab/chatcore/tree/main/packages/backend/convex"
click node_handoff "https://github.com/mahenoor-mehtab/chatcore/tree/main/packages/backend/convex"
click node_messages "https://github.com/mahenoor-mehtab/chatcore/blob/main/packages/backend/convex/messages.ts"
click node_users "https://github.com/mahenoor-mehtab/chatcore/blob/main/packages/backend/convex/users.ts"
click node_schema "https://github.com/mahenoor-mehtab/chatcore/blob/main/packages/backend/convex/schema.ts"
click node_convex "https://github.com/mahenoor-mehtab/chatcore/tree/main/packages/backend/convex"
click node_widgetsettings "https://github.com/mahenoor-mehtab/chatcore/tree/main/packages/backend/convex"
click node_billing "https://github.com/mahenoor-mehtab/chatcore/tree/main/apps/web/app"

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_widget,node_voice toneBlue
class node_knowledge,node_agent,node_handoff,node_messages,node_users,node_schema,node_convex toneAmber
class node_dashboard,node_widgetsettings,node_billing toneMint
class node_clerk,node_vapi toneRose
class node_visitor,node_operator toneIndigo
```

## Components

### Customer experience

- [Chat widget](https://github.com/mahenoor-mehtab/chatcore/blob/main/apps/widget/app/page.tsx): `apps/widget/app/page.tsx`
- [Voice support](https://github.com/mahenoor-mehtab/chatcore/blob/main/apps/widget/app/page.tsx): `apps/widget/app/page.tsx`

### Conversation backend

- [Knowledge and RAG](https://github.com/mahenoor-mehtab/chatcore/tree/main/packages/backend/convex): `packages/backend/convex`
- [AI conversation agent](https://github.com/mahenoor-mehtab/chatcore/tree/main/packages/backend/convex): `packages/backend/convex`
- [Human handoff](https://github.com/mahenoor-mehtab/chatcore/tree/main/packages/backend/convex): `packages/backend/convex`
- [Conversation messages](https://github.com/mahenoor-mehtab/chatcore/blob/main/packages/backend/convex/messages.ts): `packages/backend/convex/messages.ts`
- [Users and tenants](https://github.com/mahenoor-mehtab/chatcore/blob/main/packages/backend/convex/users.ts): `packages/backend/convex/users.ts`
- [Data schema](https://github.com/mahenoor-mehtab/chatcore/blob/main/packages/backend/convex/schema.ts): `packages/backend/convex/schema.ts`
- [Convex data](https://github.com/mahenoor-mehtab/chatcore/tree/main/packages/backend/convex): `packages/backend/convex`

### Operator platform

- [Operator dashboard](https://github.com/mahenoor-mehtab/chatcore/blob/main/apps/web/app/page.tsx): `apps/web/app/page.tsx`
- [Widget settings](https://github.com/mahenoor-mehtab/chatcore/tree/main/packages/backend/convex): `packages/backend/convex`
- [Plans and billing](https://github.com/mahenoor-mehtab/chatcore/tree/main/apps/web/app): `apps/web/app`

### Identity and services

- **Clerk identity**
- **Vapi voice**

### Other components

- **Customer**
- **Support operator**

## Connections

- Customer → Chat widget: asks question
- Chat widget → AI conversation agent: submits question
- AI conversation agent → Knowledge and RAG: retrieves context
- AI conversation agent → Conversation messages: records conversation
- AI conversation agent → Chat widget: streams answer
- AI conversation agent → Human handoff: escalates unresolved
- Human handoff → Operator dashboard: surfaces thread
- Support operator → Operator dashboard: manages inbox
- Operator dashboard → Conversation messages: views conversations
- Data schema → Convex data: defines tables
- Conversation messages → Convex data: reads and writes
- Users and tenants → Convex data: reads and writes
- Operator dashboard → Widget settings: manages appearance
- Widget settings → Chat widget: provides configuration
- Chat widget → Voice support: offers voice
- Voice support → Vapi voice: uses voice service
- Operator dashboard → Plans and billing: manages subscription
- Operator dashboard → Clerk identity: authenticates
- Chat widget → Clerk identity: protects routes
- Clerk identity → Convex data: authenticates backend