# sanjay-adtani/ai-chatbot architecture

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

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

## Overview

##### Project type and purpose
- This is a full-stack web application (Next.js 15 App Router) that allows administrators to create and configure AI chatbots and lets end users interact with them in real time.
- It uses a GraphQL backend (StepZen + IBM API Connect) over NeonDB (PostgreSQL) and calls out to OpenAI for AI responses.

##### File structure
- `app/` folder: Next.js App Router pages split into two segments—`(admin)` pages for bot management (create, edit, list) and `(guests)` pages for end-user chat interactions.
- `app/api/`: two serverless routes:
– `/api/graphql/route.ts` – proxies GraphQL requests to the StepZen endpoint.
– `/api/send-message/route.ts` – handles chat messages by calling OpenAI’s API and optionally persists them.
- `components/` + `components/ui/`: React UI building blocks (ApolloProvider, Sidebar, Messages, Button, etc.).
- `graphql/`: client-side Apollo setup plus GraphQL queries & mutations.
- `lib/`: server-side helper modules (`serverClient.ts` to talk to GraphQL/DB, `startNewChat.ts`, `utils.ts`).
- `stepzen/`: StepZen configuration and GraphQL schema definitions over PostgreSQL.
- `.env.example`: environment variables for Clerk (auth), GraphQL endpoint/token, and OpenAI API key.

##### README for additional insights
- Tech stack highlights Next.js, TypeScript, Apollo Client, OpenAI API, IBM API Connect, NeonDB.
- Key features clarify that the app persists conversation history and uses a GraphQL-driven architecture with server actions.

##### Main components
a. Frontend (Next.js App)
— Admin UI (Create/Edit/List Chatbots)
— Guest UI (Chat interface)
— Apollo Client (GraphQL queries/mutations)
— React UI Components (Sidebar, Messages, etc.)
b. Next.js Server (API Layer)
— `/api/graphql` route (GraphQL proxy)
— `/api/send-message` route (OpenAI integration)
— Server Actions / `lib` utilities (e.g., `startNewChat`)
c. GraphQL Backend
— StepZen GraphQL Server (managed via IBM API Connect)
— GraphQL schema layers (`stepzen/*.graphql`)
d. Database
— NeonDB (PostgreSQL) for chatbots metadata & conversation history
e. External Services
— OpenAI API for generating responses
— Clerk (Auth)

##### Architectural patterns & design principles
- Full-stack React (Next.js App Router) with server and client components
- GraphQL façade (StepZen + IBM API Connect) decouples schema from database
- Apollo Client for client-side caching & state management
- Serverless API routes in Next.js as “glue” between UI and external services
- Clear separation of concerns: UI vs. business logic vs. data layer vs. external AI

##### Technologies & frameworks to annotate
- Next.js 15 (App Router, Server Actions)
- TypeScript
- Apollo Client (frontend)
- StepZen + IBM API Connect (GraphQL server)
- NeonDB (PostgreSQL)
- OpenAI API
- Clerk (auth)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (Next.js App)" 
        direction TB
        AdminLayout["Admin Layout & Entry"]:::frontend
        CreateChatbot["Create Chatbot Page"]:::frontend
        EditChatbot["Edit Chatbot Page"]:::frontend
        ViewChatbots["View Chatbots List"]:::frontend
        GuestChat["Chat Interface Page"]:::frontend
        ApolloClient["Apollo Client Setup"]:::frontend
        Sidebar["Sidebar"]:::frontend
        MessagesComp["Messages"]:::frontend
        HeaderComp["Header"]:::frontend
        AvatarComp["Avatar"]:::frontend
        Characteristic["Characteristic"]:::frontend
        ButtonUI["Button"]:::frontend
        InputUI["Input"]:::frontend
        LabelUI["Label"]:::frontend
        DialogUI["Dialog"]:::frontend
        SonnerUI["Sonner"]:::frontend
        ApolloProv["ApolloProvider"]:::frontend
    end

    %% API Layer
    subgraph "API Layer (Next.js Server)" 
        direction TB
        GraphQLRoute["/api/graphql Route"]:::api
        SendMessage["/api/send-message Route"]:::api
        ServerClient["serverClient.ts"]:::api
        StartChat["startNewChat.ts"]:::api
        Utils["utils.ts"]:::api
    end

    %% GraphQL Backend
    subgraph "GraphQL Backend (StepZen + IBM API Connect)" 
        direction TB
        StepZenServer["StepZen GraphQL Server"]:::graphql
        CoreSchema["index.graphql"]:::graphql
        PgSchema["postgresql/index.graphql"]:::graphql
        ConfigYML["config.yaml"]:::graphql
        ConfigJSON["stepzen.config.json"]:::graphql
    end

    %% Database Layer
    NeonDB["NeonDB (PostgreSQL)"]:::db
    SeedScript["seed.sql"]:::db

    %% External Services
    OpenAI["OpenAI API"]:::external
    ClerkAuth["Clerk (Auth)"]:::external

    %% Data Flows
    Browser["Browser"]:::external

    Browser -->|"Admin UI Request"| AdminLayout
    Browser -->|"Guest UI Request"| GuestChat

    AdminLayout -->|uses| CreateChatbot
    AdminLayout -->|uses| EditChatbot
    AdminLayout -->|uses| ViewChatbots

    GuestChat -->|chat UI| MessagesComp

    CreateChatbot -->|GraphQL Mutation| ApolloClient
    EditChatbot -->|GraphQL Mutation| ApolloClient
    ViewChatbots -->|GraphQL Query| ApolloClient
    GuestChat -->|GraphQL Query| ApolloClient

    ApolloClient -->|requests| GraphQLRoute
    ApolloClient -->|requests| SendMessage

    GraphQLRoute -->|GraphQL Proxy| StepZenServer
    SendMessage -->|REST POST /send-message| OpenAI
    SendMessage -->|persist message| StepZenServer

    StepZenServer -->|reads/writes| NeonDB
    CoreSchema --> StepZenServer
    PgSchema --> StepZenServer
    ConfigYML --> StepZenServer
    ConfigJSON --> StepZenServer

    NeonDB -->|seed data| SeedScript

    Browser -->|auth| ClerkAuth

    %% Click Events
    click AdminLayout "https://github.com/sanjay-adtani/ai-chatbot/blob/main/app/(admin)/layout.tsx"
    click CreateChatbot "https://github.com/sanjay-adtani/ai-chatbot/blob/main/app/(admin)/create-chatbot/page.tsx"
    click EditChatbot "https://github.com/sanjay-adtani/ai-chatbot/blob/main/app/(admin)/edit-chatbot/[id]/page.tsx"
    click ViewChatbots "https://github.com/sanjay-adtani/ai-chatbot/blob/main/app/(admin)/view-chatbots/page.tsx"
    click GuestChat "https://github.com/sanjay-adtani/ai-chatbot/blob/main/app/(guests)/chatbot/[id]/page.tsx"
    click ApolloClient "https://github.com/sanjay-adtani/ai-chatbot/blob/main/graphql/apolloClient.ts"
    click Sidebar "https://github.com/sanjay-adtani/ai-chatbot/blob/main/components/Sidebar.tsx"
    click MessagesComp "https://github.com/sanjay-adtani/ai-chatbot/blob/main/components/Messages.tsx"
    click HeaderComp "https://github.com/sanjay-adtani/ai-chatbot/blob/main/components/Header.tsx"
    click AvatarComp "https://github.com/sanjay-adtani/ai-chatbot/blob/main/components/Avatar.tsx"
    click Characteristic "https://github.com/sanjay-adtani/ai-chatbot/blob/main/components/Characteristic.tsx"
    click ButtonUI "https://github.com/sanjay-adtani/ai-chatbot/blob/main/components/ui/button.tsx"
    click InputUI "https://github.com/sanjay-adtani/ai-chatbot/blob/main/components/ui/input.tsx"
    click LabelUI "https://github.com/sanjay-adtani/ai-chatbot/blob/main/components/ui/label.tsx"
    click DialogUI "https://github.com/sanjay-adtani/ai-chatbot/blob/main/components/ui/dialog.tsx"
    click SonnerUI "https://github.com/sanjay-adtani/ai-chatbot/blob/main/components/ui/sonner.tsx"
    click ApolloProv "https://github.com/sanjay-adtani/ai-chatbot/blob/main/components/ApolloProvider.tsx"
    click GraphQLRoute "https://github.com/sanjay-adtani/ai-chatbot/blob/main/app/api/graphql/route.ts"
    click SendMessage "https://github.com/sanjay-adtani/ai-chatbot/blob/main/app/api/send-message/route.ts"
    click ServerClient "https://github.com/sanjay-adtani/ai-chatbot/blob/main/lib/server/serverClient.ts"
    click StartChat "https://github.com/sanjay-adtani/ai-chatbot/blob/main/lib/startNewChat.ts"
    click Utils "https://github.com/sanjay-adtani/ai-chatbot/blob/main/lib/utils.ts"
    click CoreSchema "https://github.com/sanjay-adtani/ai-chatbot/blob/main/stepzen/index.graphql"
    click PgSchema "https://github.com/sanjay-adtani/ai-chatbot/blob/main/stepzen/postgresql/index.graphql"
    click ConfigYML "https://github.com/sanjay-adtani/ai-chatbot/blob/main/stepzen/config.yaml"
    click ConfigJSON "https://github.com/sanjay-adtani/ai-chatbot/blob/main/stepzen/stepzen.config.json"
    click SeedScript "https://github.com/sanjay-adtani/ai-chatbot/blob/main/seed.sql"
    click Browser "https://github.com/sanjay-adtani/ai-chatbot/blob/main/.env.example"
    click ClerkAuth "https://github.com/sanjay-adtani/ai-chatbot/blob/main/.env.example"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#2b6cb0,color:#1a202c
    classDef api fill:#d4edda,stroke:#276749,color:#1a202c
    classDef graphql fill:#ffe5b4,stroke:#dd6b20,color:#1a202c
    classDef db fill:#e0ffff,stroke:#319795,color:#1a202c
    classDef external fill:#f0f0f0,stroke:#4a5568,color:#1a202c
```
