# snarktank/ai-chatbot architecture

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

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

## Overview

##### Project type and purpose
- This is a full-stack web application template (“Chat SDK”) for building AI chatbot UIs.
- It provides authentication, chat interfaces, file uploads, history storage, and AI-driven artifacts (text, code, images, sheets).

##### File structure
- `app/` directory uses Next.js App Router with two main segments:
- `(auth)` – auth pages, Auth.js config, `/api/auth` routes.
- `(chat)` – chat UI pages, server actions, and API routes under `/api/chat`, `/api/history`, `/api/files`, `/api/suggestions`, etc.
- `lib/` contains core business logic:
- `lib/ai/` – wrappers around the AI SDK, prompts, tools.
- `lib/db/` – Drizzle schema, migrations, queries.
- `lib/artifacts/` – server functions for persisting and retrieving chat “artifacts.”
- `components/` – React UI components (sidebar, editors, message lists, etc.).
- Config and infra files: `drizzle.config.ts`, `next.config.ts`, `playwright.config.ts`, `.github/workflows`.

##### README for additional insights
- Confirms tech stack: Next.js App Router, React Server Components & Server Actions, AI SDK, shadcn/ui + Tailwind, Neon Postgres, Vercel Blob, Auth.js.
- Mentions model providers can be swapped (xAI, OpenAI, Anthropic, etc.).

##### Main components
a. Frontend (Browser)
- Next.js React Components (Client & Server Components)
- UI Library (shadcn/ui + Tailwind)
- Pages under `app/(auth)` and `app/(chat)`
b. Next.js Backend (Server)
- Server Actions & API Routes under `/api/*` (chat, history, files, suggestions, vote)
- Auth.js handlers for `/api/auth/[...nextauth]`
- Drizzle ORM layer (`lib/db`) connecting to Postgres
- AI service layer (`lib/ai`) calling out to LLM providers via AI SDK
- Artifact management layer (`lib/artifacts`) for saving and retrieving chat outputs
c. Database
- Neon Serverless Postgres (using Drizzle schema & migrations)
d. Blob Storage
- Vercel Blob for file uploads (images, documents)
e. External Services
- AI Providers (xAI, OpenAI, etc.) via AI SDK
- Authentication provider (OAuth, Email via Auth.js)
f. CI/CD & Testing
- GitHub Actions (lint, Playwright e2e)

##### Relationships & data flows
- Browser → Next.js pages & Server Actions (UI interactions like submitting a message)
- Next.js Server Actions → AI SDK → External LLM → response back to Server Action
- Server Actions → Drizzle ORM → Postgres (save chat history, user data)
- `/api/files/upload` → Vercel Blob (store and retrieve attachments)
- Frontend polls or streams chat history via `/api/history`
- Auth flows: Browser → `/api/auth` → Auth.js → session cookie → protected pages

##### Important architectural patterns
- React Server Components & Server Actions for minimal bundle size & reduced client JS.
- API-centric micro-routes under `app/(chat)/api` for each domain (chat, files, history, suggestions).
- Modular “artifact” pattern: text, code, image, sheet components each have client/server handlers (`artifacts/*`).
- Drizzle ORM with migration metadata ensures safe schema evolution.
- AI SDK abstraction isolates provider-specific code under `lib/ai/providers.ts`.

##### Technologies & frameworks
- Next.js 14 App Router
- React, React Server Components, Server Actions
- Vercel AI SDK
- Auth.js
- Drizzle ORM & Neon Postgres
- Vercel Blob
- shadcn/ui + Tailwind CSS
- Playwright & GitHub Actions for testing

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (Browser)" 
        direction TB
        A1["Login Page"]:::frontend
        A2["Register Page"]:::frontend
        A3["Chat List Page"]:::frontend
        A4["Chat Detail Page"]:::frontend
        A5["React UI Components"]:::frontend
        A6["UI Library (shadcn/ui + Tailwind)"]:::frontend
    end

    %% Server Layer
    subgraph "Next.js Backend" 
        direction TB
        B1["Auth Layer"]:::server
        B2["Server Actions"]:::server
        B3["API Routes"]:::server
        B4["AI Service Layer"]:::server
        B5["Artifact Management Layer"]:::server
    end

    %% Storage & External
    subgraph "Storage & External"
        direction TB
        C1["Postgres (Neon)"]:::storage
        C2["Vercel Blob"]:::storage
        C3["LLM Providers"]:::external
        C4["OAuth / Email Auth"]:::external
    end

    %% CI/CD
    D1["CI/CD & Testing"]:::infra

    %% Connections
    A1 -->|"Auth.js flows"| B1
    A2 -->|"Auth.js flows"| B1
    A3 -->|"Server Components & Actions"| B2
    A4 -->|"Server Components & Actions"| B2
    A5 -->|Uses| A6

    B1 -->|"POST /api/auth/[...nextauth]"| C4
    B2 -->|"invoke actions"| B4
    B2 -->|"invoke actions"| B1
    B2 -->|"Drizzle queries"| C1
    B3 -->|"POST /api/chat"| B4
    B3 -->|"GET /api/history"| C1
    B3 -->|"POST /api/files/upload"| C2
    B3 -->|"GET /api/suggestions"| B4
    B3 -->|"POST /api/vote"| C1
    B3 -->|"POST /api/document"| B5

    B4 -->|"AI.generate()"| C3
    B5 -->|"save/retrieve artifacts"| C1

    C2 -->|"store attachments"| B3

    D1 -->|"CI Pipelines, E2E tests"| B2

    %% Click events - Frontend Pages
    click A1 "https://github.com/snarktank/ai-chatbot/blob/main/app/(auth)/login/page.tsx"
    click A2 "https://github.com/snarktank/ai-chatbot/blob/main/app/(auth)/register/page.tsx"
    click A3 "https://github.com/snarktank/ai-chatbot/blob/main/app/(chat)/page.tsx"
    click A4 "https://github.com/snarktank/ai-chatbot/blob/main/app/(chat)/chat/[id]/page.tsx"

    %% Click events - UI Components & Library
    click A5 "https://github.com/snarktank/ai-chatbot/tree/main/components/"
    click A6 "https://github.com/snarktank/ai-chatbot/tree/main/components/ui/"
    click A6 "https://github.com/snarktank/ai-chatbot/blob/main/tailwind.config.ts"
    click A6 "https://github.com/snarktank/ai-chatbot/blob/main/postcss.config.mjs"

    %% Click events - Auth Layer
    click B1 "https://github.com/snarktank/ai-chatbot/blob/main/app/(auth)/auth.config.ts"
    click B1 "https://github.com/snarktank/ai-chatbot/blob/main/app/(auth)/auth.ts"
    click B1 "https://github.com/snarktank/ai-chatbot/blob/main/app/(auth)/actions.ts"
    click B1 "https://github.com/snarktank/ai-chatbot/blob/main/app/(auth)/api/auth/[...nextauth]/route.ts"
    click B1 "https://github.com/snarktank/ai-chatbot/blob/main/app/(auth)/api/auth/guest/route.ts"

    %% Click events - Server Actions
    click B2 "https://github.com/snarktank/ai-chatbot/blob/main/app/(auth)/actions.ts"
    click B2 "https://github.com/snarktank/ai-chatbot/blob/main/app/(chat)/actions.ts"

    %% Click events - API Routes
    click B3 "https://github.com/snarktank/ai-chatbot/blob/main/app/(chat)/api/chat/route.ts"
    click B3 "https://github.com/snarktank/ai-chatbot/blob/main/app/(chat)/api/chat/schema.ts"
    click B3 "https://github.com/snarktank/ai-chatbot/blob/main/app/(chat)/api/history/route.ts"
    click B3 "https://github.com/snarktank/ai-chatbot/blob/main/app/(chat)/api/files/upload/route.ts"
    click B3 "https://github.com/snarktank/ai-chatbot/blob/main/app/(chat)/api/suggestions/route.ts"
    click B3 "https://github.com/snarktank/ai-chatbot/blob/main/app/(chat)/api/vote/route.ts"
    click B3 "https://github.com/snarktank/ai-chatbot/blob/main/app/(chat)/api/document/route.ts"

    %% Click events - AI Service
    click B4 "https://github.com/snarktank/ai-chatbot/blob/main/lib/ai/models.ts"
    click B4 "https://github.com/snarktank/ai-chatbot/blob/main/lib/ai/providers.ts"
    click B4 "https://github.com/snarktank/ai-chatbot/blob/main/lib/ai/prompts.ts"
    click B4 "https://github.com/snarktank/ai-chatbot/blob/main/lib/ai/entitlements.ts"
    click B4 "https://github.com/snarktank/ai-chatbot/tree/main/lib/ai/tools/"

    %% Click events - Artifact Layer
    click B5 "https://github.com/snarktank/ai-chatbot/blob/main/lib/artifacts/server.ts"
    click B5 "https://github.com/snarktank/ai-chatbot/blob/main/artifacts/text/client.tsx"
    click B5 "https://github.com/snarktank/ai-chatbot/blob/main/artifacts/text/server.ts"
    click B5 "https://github.com/snarktank/ai-chatbot/blob/main/artifacts/code/client.tsx"
    click B5 "https://github.com/snarktank/ai-chatbot/blob/main/artifacts/code/server.ts"
    click B5 "https://github.com/snarktank/ai-chatbot/blob/main/artifacts/image/client.tsx"
    click B5 "https://github.com/snarktank/ai-chatbot/blob/main/artifacts/image/server.ts"
    click B5 "https://github.com/snarktank/ai-chatbot/blob/main/artifacts/sheet/client.tsx"
    click B5 "https://github.com/snarktank/ai-chatbot/blob/main/artifacts/sheet/server.ts"
    click B5 "https://github.com/snarktank/ai-chatbot/blob/main/artifacts/actions.ts"

    %% Click events - DB Layer
    click C1 "https://github.com/snarktank/ai-chatbot/blob/main/drizzle.config.ts"
    click C1 "https://github.com/snarktank/ai-chatbot/blob/main/lib/db/schema.ts"
    click C1 "https://github.com/snarktank/ai-chatbot/blob/main/lib/db/queries.ts"
    click C1 "https://github.com/snarktank/ai-chatbot/blob/main/lib/db/migrate.ts"
    click C1 "https://github.com/snarktank/ai-chatbot/tree/main/lib/db/migrations/"
    click C1 "https://github.com/snarktank/ai-chatbot/tree/main/lib/db/migrations/meta/"
    click C1 "https://github.com/snarktank/ai-chatbot/blob/main/lib/db/helpers/01-core-to-parts.ts"

    %% Click events - Blob Storage
    click C2 "https://github.com/snarktank/ai-chatbot/blob/main/app/(chat)/api/files/upload/route.ts"

    %% Click events - CI/CD
    click D1 "https://github.com/snarktank/ai-chatbot/blob/main/.github/workflows/lint.yml"
    click D1 "https://github.com/snarktank/ai-chatbot/blob/main/.github/workflows/playwright.yml"
    click D1 "https://github.com/snarktank/ai-chatbot/blob/main/playwright.config.ts"
    click D1 "https://github.com/snarktank/ai-chatbot/tree/main/tests/e2e/"
    click D1 "https://github.com/snarktank/ai-chatbot/tree/main/tests/routes/"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064,color:#006064
    classDef server fill:#E8F5E9,stroke:#2E7D32,color:#2E7D32
    classDef storage fill:#FFF8E1,stroke:#F9A825,color:#F9A825
    classDef external fill:#FFF3E0,stroke:#EF6C00,color:#EF6C00
    classDef infra fill:#ECEFF1,stroke:#607D8B,color:#37474F
```
