# samuraigpt/ai-knowledge-base architecture

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

- Interactive diagram: https://gitdiagram.com/samuraigpt/ai-knowledge-base
- Repository: https://github.com/samuraigpt/ai-knowledge-base

## Overview

KnowBase AI is a self-hosted knowledge-base and RAG chatbot SaaS. Users authenticate, create knowledge bases, add document or Q&A sources, and chat with citations; credit purchases fund training and queries. The graph preserves documented widget/API, URL-ingestion, and billing capabilities, but the sampled source does not expose the full chat or ingestion implementation, so those links are documented rather than inferred from module names.

Main entry points: [`src/app/page.js`](https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/app/page.js) (Studio workspace), [`src/lib/prisma.js`](https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/lib/prisma.js) (Prisma client), [`src/lib/services/billing.js`](https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/lib/services/billing.js) (Billing service), [`src/app/api/kb/[id]/chat/[chatId]/messages/route.js`](https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/app/api/kb/%5Bid%5D/chat/%5BchatId%5D/messages/route.js) (Chat and citations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Workspace experience"]
  node_workspace["Studio workspace<br/>[page.js]"]
  node_gallery["Knowledge gallery<br/>[page.js]"]
  node_pricing["Pricing page<br/>[page.js]"]
  node_navbar["Account navigation<br/>[Navbar.js]"]
  node_authui["Sign-in page<br/>[page.js]"]
end

subgraph group_knowledge["Knowledge and chat"]
  node_kbapi["Knowledge-base API<br/>[route.js]"]
  node_sourcesapi["Source training API<br/>[route.js]"]
  node_chatapi["Chat sessions API<br/>[route.js]"]
  node_messages["Chat and citations<br/>[route.js]"]
  node_chat{{"RAG and AI engine"}}
  node_widgets["Embed widget and API"]
end

subgraph group_identity["Identity and account"]
  node_authroute["Auth endpoint<br/>[route.js]"]
  node_auth["Session and providers<br/>[auth.js]"]
  node_apikey["Custom API key<br/>[route.js]"]
end

subgraph group_billing["Credits and billing"]
  node_checkout["Checkout endpoints<br/>[route.js]"]
  node_webhook["Stripe webhook<br/>[route.js]"]
  node_billingservice["Billing service<br/>[billing.js]"]
end

subgraph group_foundation["Persistence and services"]
  node_userservice["Credit service<br/>[user.js]"]
  node_prisma["Prisma client<br/>[prisma.js]"]
  node_database[("PostgreSQL data<br/>[schema.prisma]")]
  node_config["Product configuration<br/>[config.js]"]
end

node_user(("Workspace user"))
node_stripe{{"Stripe"}}

node_user -->|"uses"| node_workspace
node_user -->|"browses"| node_gallery
node_user -->|"buys credits"| node_pricing
node_user -->|"signs in"| node_authui
node_navbar -->|"saves key"| node_apikey
node_workspace -->|"manages bases"| node_kbapi
node_workspace -->|"trains sources"| node_sourcesapi
node_workspace -->|"opens chats"| node_chatapi
node_workspace -->|"sends queries"| node_messages
node_messages -.->|"retrieves and generates"| node_chat
node_chat -->|"returns citations"| node_messages
node_workspace -->|"exports embeds"| node_widgets
node_authroute -->|"loads options"| node_auth
node_kbapi -->|"checks session"| node_auth
node_kbapi -->|"reads and writes"| node_prisma
node_sourcesapi -->|"reads and writes"| node_prisma
node_sourcesapi -->|"deducts credits"| node_userservice
node_messages -->|"loads chat data"| node_prisma
node_checkout -->|"creates session"| node_billingservice
node_webhook -->|"handles event"| node_billingservice
node_billingservice -->|"creates checkout"| node_stripe
node_billingservice -->|"adds credits"| node_userservice
node_userservice -->|"updates balances"| node_prisma
node_auth -->|"uses adapter"| node_prisma
node_prisma -.->|"persists records"| node_database
node_billingservice -->|"reads plans"| node_config

click node_workspace "https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/app/page.js"
click node_gallery "https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/app/gallery/page.js"
click node_pricing "https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/app/pricing/page.js"
click node_navbar "https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/components/Navbar.js"
click node_authui "https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/app/login/page.js"
click node_kbapi "https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/app/api/kb/route.js"
click node_sourcesapi "https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/app/api/kb/%5Bid%5D/sources/route.js"
click node_chatapi "https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/app/api/kb/%5Bid%5D/chat/route.js"
click node_messages "https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/app/api/kb/%5Bid%5D/chat/%5BchatId%5D/messages/route.js"
click node_widgets "https://github.com/samuraigpt/ai-knowledge-base/tree/main/src/app"
click node_authroute "https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/app/api/auth/%5B...nextauth%5D/route.js"
click node_auth "https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/lib/auth.js"
click node_apikey "https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/app/api/user/apikey/route.js"
click node_checkout "https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/app/api/stripe/checkout/route.js"
click node_webhook "https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/app/api/stripe/webhook/route.js"
click node_billingservice "https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/lib/services/billing.js"
click node_userservice "https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/lib/services/user.js"
click node_prisma "https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/lib/prisma.js"
click node_database "https://github.com/samuraigpt/ai-knowledge-base/blob/main/prisma/schema.prisma"
click node_config "https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/lib/config.js"

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_workspace,node_gallery,node_pricing,node_navbar,node_authui,node_user toneBlue
class node_kbapi,node_sourcesapi,node_chatapi,node_messages,node_chat,node_widgets toneAmber
class node_authroute,node_auth,node_apikey toneMint
class node_checkout,node_webhook,node_billingservice toneRose
class node_userservice,node_prisma,node_database,node_config,node_stripe toneIndigo
```

## Components

### Workspace experience

- [Studio workspace](https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/app/page.js): `src/app/page.js`
- [Knowledge gallery](https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/app/gallery/page.js): `src/app/gallery/page.js`
- [Pricing page](https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/app/pricing/page.js): `src/app/pricing/page.js`
- [Account navigation](https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/components/Navbar.js): `src/components/Navbar.js`
- [Sign-in page](https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/app/login/page.js): `src/app/login/page.js`

### Knowledge and chat

- [Knowledge-base API](https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/app/api/kb/route.js): `src/app/api/kb/route.js`
- [Source training API](https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/app/api/kb/%5Bid%5D/sources/route.js): `src/app/api/kb/[id]/sources/route.js`
- [Chat sessions API](https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/app/api/kb/%5Bid%5D/chat/route.js): `src/app/api/kb/[id]/chat/route.js`
- [Chat and citations](https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/app/api/kb/%5Bid%5D/chat/%5BchatId%5D/messages/route.js): `src/app/api/kb/[id]/chat/[chatId]/messages/route.js`
- **RAG and AI engine**
- [Embed widget and API](https://github.com/samuraigpt/ai-knowledge-base/tree/main/src/app): `src/app`

### Identity and account

- [Auth endpoint](https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/app/api/auth/%5B...nextauth%5D/route.js): `src/app/api/auth/[...nextauth]/route.js`
- [Session and providers](https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/lib/auth.js): `src/lib/auth.js`
- [Custom API key](https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/app/api/user/apikey/route.js): `src/app/api/user/apikey/route.js`

### Credits and billing

- [Checkout endpoints](https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/app/api/stripe/checkout/route.js): `src/app/api/stripe/checkout/route.js`
- [Stripe webhook](https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/app/api/stripe/webhook/route.js): `src/app/api/stripe/webhook/route.js`
- [Billing service](https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/lib/services/billing.js): `src/lib/services/billing.js`

### Persistence and services

- [Credit service](https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/lib/services/user.js): `src/lib/services/user.js`
- [Prisma client](https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/lib/prisma.js): `src/lib/prisma.js`
- [PostgreSQL data](https://github.com/samuraigpt/ai-knowledge-base/blob/main/prisma/schema.prisma): `prisma/schema.prisma`
- [Product configuration](https://github.com/samuraigpt/ai-knowledge-base/blob/main/src/lib/config.js): `src/lib/config.js`

### Other components

- **Workspace user**
- **Stripe**

## Connections

- Workspace user → Studio workspace: uses (evidence: `README.md`)
- Workspace user → Knowledge gallery: browses (evidence: `README.md`)
- Workspace user → Pricing page: buys credits (evidence: `README.md`)
- Workspace user → Sign-in page: signs in (evidence: `README.md`)
- Account navigation → Custom API key: saves key (evidence: `src/components/Navbar.js`)
- Studio workspace → Knowledge-base API: manages bases (evidence: `README.md`)
- Studio workspace → Source training API: trains sources (evidence: `README.md`)
- Studio workspace → Chat sessions API: opens chats (evidence: `README.md`)
- Studio workspace → Chat and citations: sends queries (evidence: `README.md`)
- Chat and citations → RAG and AI engine: retrieves and generates
- RAG and AI engine → Chat and citations: returns citations (evidence: `README.md`)
- Studio workspace → Embed widget and API: exports embeds (evidence: `README.md`)
- Auth endpoint → Session and providers: loads options (evidence: `src/app/api/auth/[...nextauth]/route.js`)
- Knowledge-base API → Session and providers: checks session (evidence: `src/app/api/kb/route.js`)
- Knowledge-base API → Prisma client: reads and writes (evidence: `src/app/api/kb/route.js`)
- Source training API → Prisma client: reads and writes (evidence: `src/app/api/kb/[id]/sources/route.js`)
- Source training API → Credit service: deducts credits (evidence: `src/app/api/kb/[id]/sources/route.js`)
- Chat and citations → Prisma client: loads chat data (evidence: `src/app/api/kb/[id]/chat/[chatId]/messages/route.js`)
- Checkout endpoints → Billing service: creates session (evidence: `src/app/api/stripe/checkout/route.js`)
- Stripe webhook → Billing service: handles event (evidence: `src/app/api/stripe/webhook/route.js`)
- Billing service → Stripe: creates checkout (evidence: `src/lib/services/billing.js`)
- Billing service → Credit service: adds credits (evidence: `src/lib/services/billing.js`)
- Credit service → Prisma client: updates balances (evidence: `src/lib/services/user.js`)
- Session and providers → Prisma client: uses adapter (evidence: `src/lib/auth.js`)
- Prisma client → PostgreSQL data: persists records
- Billing service → Product configuration: reads plans (evidence: `src/lib/services/billing.js`)
