# marioivanov063/custom-ai-chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/marioivanov063/custom-ai-chatbot
- Repository: https://github.com/marioivanov063/custom-ai-chatbot

## Overview

Chorus lets chatbot owners configure an AI agent and its facts, share a public chat link, and review transcripts. Owners use the management UI and guests provide contact details before chatting; the guest page starts a session through GraphQL and sends messages to the separate Ollama proxy. GraphQL resolvers enforce ownership and access PostgreSQL through data modules. Session review and the scheduled session-ending and summarisation job are distinct product stages. Edges reflect shown imports/calls or README statements; the background-job internals are documented but unsampled.

Main entry points: [`lib/apollo-client.ts`](https://github.com/marioivanov063/custom-ai-chatbot/blob/main/lib/apollo-client.ts) (GraphQL client), [`app/(guest)/chatbot/[id]/page.tsx`](https://github.com/marioivanov063/custom-ai-chatbot/blob/main/app/(guest)/chatbot/%5Bid%5D/page.tsx) (Public chat page), [`app/api/graphql/route.ts`](https://github.com/marioivanov063/custom-ai-chatbot/blob/main/app/api/graphql/route.ts) (GraphQL endpoint), [`app/(admin)`](https://github.com/marioivanov063/custom-ai-chatbot/tree/main/app/(admin)) (Management pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_management["Chatbot management"]
  node_create_ui["Create chatbot"]
  node_edit_ui["Edit bot and facts"]
  node_manage_pages["Management pages"]
end

subgraph group_guest["Guest conversations"]
  node_public_chat["Public chat page<br/>[page.tsx]"]
  node_start_chat["Start chat<br/>[start-new-chat.ts]"]
  node_message_api["Message proxy<br/>[route.ts]"]
end

subgraph group_review["Session review"]
  node_review_pages["Review pages"]
  node_session_views["Session lists and transcript"]
  node_sweeper["End and summarise sessions"]
end

subgraph group_backend["Application services"]
  node_graphql_client["GraphQL client<br/>[apollo-client.ts]"]
  node_graphql_api["GraphQL endpoint<br/>[route.ts]"]
  node_resolvers["GraphQL resolvers<br/>[resolvers.ts]"]
  node_chatbot_data["Chatbot data access<br/>[chatbots.ts]"]
  node_session_data["Session data access<br/>[sessions.ts]"]
  node_user_data["User data access<br/>[users.ts]"]
  node_postgres[("PostgreSQL")]
end

node_owner(("Chatbot owner"))
node_guest_user(("Guest"))
node_ollama{{"Ollama model"}}
node_clerk{{"Clerk identity"}}

node_owner -->|"manages bots"| node_manage_pages
node_manage_pages -->|"renders"| node_create_ui
node_manage_pages -->|"renders"| node_edit_ui
node_create_ui -->|"submits mutations"| node_graphql_client
node_edit_ui -->|"updates bot"| node_graphql_client
node_owner -->|"reviews sessions"| node_review_pages
node_review_pages -->|"renders"| node_session_views
node_session_views -->|"queries sessions"| node_graphql_client
node_guest_user -->|"opens shared link"| node_public_chat
node_public_chat -->|"loads chatbot"| node_graphql_client
node_public_chat -->|"starts session"| node_start_chat
node_public_chat -->|"sends message"| node_message_api
node_message_api -->|"proxies prompt"| node_ollama
node_graphql_client -->|"posts GraphQL"| node_graphql_api
node_graphql_api -->|"dispatches"| node_resolvers
node_resolvers -->|"reads and writes bots"| node_chatbot_data
node_resolvers -->|"reads sessions"| node_session_data
node_graphql_api -->|"resolves request user"| node_user_data
node_chatbot_data -->|"queries"| node_postgres
node_session_data -->|"queries"| node_postgres
node_user_data -->|"queries"| node_postgres
node_sweeper -.->|"ends and summarises"| node_postgres
node_sweeper -.->|"requests summaries"| node_ollama
node_graphql_api -.->|"uses identity"| node_clerk

click node_create_ui "https://github.com/marioivanov063/custom-ai-chatbot/blob/main/components/chatbots/create-chatbot-form.tsx"
click node_edit_ui "https://github.com/marioivanov063/custom-ai-chatbot/blob/main/components/chatbots/edit-chatbot-form.tsx"
click node_manage_pages "https://github.com/marioivanov063/custom-ai-chatbot/tree/main/app/(admin)"
click node_public_chat "https://github.com/marioivanov063/custom-ai-chatbot/blob/main/app/(guest)/chatbot/%5Bid%5D/page.tsx"
click node_start_chat "https://github.com/marioivanov063/custom-ai-chatbot/blob/main/lib/start-new-chat.ts"
click node_message_api "https://github.com/marioivanov063/custom-ai-chatbot/blob/main/app/api/send-message/route.ts"
click node_review_pages "https://github.com/marioivanov063/custom-ai-chatbot/tree/main/app/(admin)/review-sessions"
click node_session_views "https://github.com/marioivanov063/custom-ai-chatbot/tree/main/components/sessions"
click node_sweeper "https://github.com/marioivanov063/custom-ai-chatbot/blob/main/db/scripts/sweep-and-summarize.mjs"
click node_graphql_client "https://github.com/marioivanov063/custom-ai-chatbot/blob/main/lib/apollo-client.ts"
click node_graphql_api "https://github.com/marioivanov063/custom-ai-chatbot/blob/main/app/api/graphql/route.ts"
click node_resolvers "https://github.com/marioivanov063/custom-ai-chatbot/blob/main/app/api/graphql/resolvers.ts"
click node_chatbot_data "https://github.com/marioivanov063/custom-ai-chatbot/blob/main/lib/data/chatbots.ts"
click node_session_data "https://github.com/marioivanov063/custom-ai-chatbot/blob/main/lib/data/sessions.ts"
click node_user_data "https://github.com/marioivanov063/custom-ai-chatbot/blob/main/lib/data/users.ts"

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_create_ui,node_edit_ui,node_manage_pages toneBlue
class node_public_chat,node_start_chat,node_message_api toneAmber
class node_review_pages,node_session_views,node_sweeper toneMint
class node_graphql_client,node_graphql_api,node_resolvers,node_chatbot_data,node_session_data,node_user_data,node_postgres toneRose
class node_owner,node_guest_user,node_ollama,node_clerk toneIndigo
```

## Components

### Chatbot management

- [Create chatbot](https://github.com/marioivanov063/custom-ai-chatbot/blob/main/components/chatbots/create-chatbot-form.tsx): `components/chatbots/create-chatbot-form.tsx`
- [Edit bot and facts](https://github.com/marioivanov063/custom-ai-chatbot/blob/main/components/chatbots/edit-chatbot-form.tsx): `components/chatbots/edit-chatbot-form.tsx`
- [Management pages](https://github.com/marioivanov063/custom-ai-chatbot/tree/main/app/(admin)): `app/(admin)`

### Guest conversations

- [Public chat page](https://github.com/marioivanov063/custom-ai-chatbot/blob/main/app/(guest)/chatbot/%5Bid%5D/page.tsx): `app/(guest)/chatbot/[id]/page.tsx`
- [Start chat](https://github.com/marioivanov063/custom-ai-chatbot/blob/main/lib/start-new-chat.ts): `lib/start-new-chat.ts`
- [Message proxy](https://github.com/marioivanov063/custom-ai-chatbot/blob/main/app/api/send-message/route.ts): `app/api/send-message/route.ts`

### Session review

- [Review pages](https://github.com/marioivanov063/custom-ai-chatbot/tree/main/app/(admin)/review-sessions): `app/(admin)/review-sessions`
- [Session lists and transcript](https://github.com/marioivanov063/custom-ai-chatbot/tree/main/components/sessions): `components/sessions`
- [End and summarise sessions](https://github.com/marioivanov063/custom-ai-chatbot/blob/main/db/scripts/sweep-and-summarize.mjs): `db/scripts/sweep-and-summarize.mjs`

### Application services

- [GraphQL client](https://github.com/marioivanov063/custom-ai-chatbot/blob/main/lib/apollo-client.ts): `lib/apollo-client.ts`
- [GraphQL endpoint](https://github.com/marioivanov063/custom-ai-chatbot/blob/main/app/api/graphql/route.ts): `app/api/graphql/route.ts`
- [GraphQL resolvers](https://github.com/marioivanov063/custom-ai-chatbot/blob/main/app/api/graphql/resolvers.ts): `app/api/graphql/resolvers.ts`
- [Chatbot data access](https://github.com/marioivanov063/custom-ai-chatbot/blob/main/lib/data/chatbots.ts): `lib/data/chatbots.ts`
- [Session data access](https://github.com/marioivanov063/custom-ai-chatbot/blob/main/lib/data/sessions.ts): `lib/data/sessions.ts`
- [User data access](https://github.com/marioivanov063/custom-ai-chatbot/blob/main/lib/data/users.ts): `lib/data/users.ts`
- **PostgreSQL**

### Other components

- **Chatbot owner**
- **Guest**
- **Ollama model**
- **Clerk identity**

## Connections

- Chatbot owner → Management pages: manages bots (evidence: `README.md`)
- Management pages → Create chatbot: renders (evidence: `app/(admin)/create-chatbot/page.tsx`)
- Management pages → Edit bot and facts: renders (evidence: `app/(admin)/edit-chatbot/[id]/page.tsx`)
- Create chatbot → GraphQL client: submits mutations (evidence: `components/chatbots/create-chatbot-form.tsx`)
- Edit bot and facts → GraphQL client: updates bot (evidence: `components/chatbots/edit-chatbot-form.tsx`)
- Chatbot owner → Review pages: reviews sessions (evidence: `README.md`)
- Review pages → Session lists and transcript: renders (evidence: `app/(admin)/review-sessions/page.tsx`)
- Session lists and transcript → GraphQL client: queries sessions (evidence: `components/sessions/sessions-by-chatbot.tsx`)
- Guest → Public chat page: opens shared link (evidence: `README.md`)
- Public chat page → GraphQL client: loads chatbot (evidence: `app/(guest)/chatbot/[id]/page.tsx`)
- Public chat page → Start chat: starts session (evidence: `app/(guest)/chatbot/[id]/page.tsx`)
- Public chat page → Message proxy: sends message (evidence: `app/(guest)/chatbot/[id]/page.tsx`)
- Message proxy → Ollama model: proxies prompt (evidence: `README.md`)
- GraphQL client → GraphQL endpoint: posts GraphQL (evidence: `lib/apollo-client.ts`)
- GraphQL endpoint → GraphQL resolvers: dispatches (evidence: `app/api/graphql/route.ts`)
- GraphQL resolvers → Chatbot data access: reads and writes bots (evidence: `app/api/graphql/resolvers.ts`)
- GraphQL resolvers → Session data access: reads sessions (evidence: `app/api/graphql/resolvers.ts`)
- GraphQL endpoint → User data access: resolves request user (evidence: `app/api/graphql/route.ts`)
- Chatbot data access → PostgreSQL: queries (evidence: `lib/data/chatbots.ts`)
- Session data access → PostgreSQL: queries (evidence: `lib/data/sessions.ts`)
- User data access → PostgreSQL: queries (evidence: `lib/data/users.ts`)
- End and summarise sessions → PostgreSQL: ends and summarises (evidence: `README.md`)
- End and summarise sessions → Ollama model: requests summaries (evidence: `README.md`)
- GraphQL endpoint → Clerk identity: uses identity (evidence: `README.md`)
