# nabarvn/chadgpt architecture

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

- Interactive diagram: https://gitdiagram.com/nabarvn/chadgpt
- Repository: https://github.com/nabarvn/chadgpt

## Overview

##### Project type and purpose
- This is a full-stack, serverless web app (“ChadGPT”) built with Next.js 13 (App Router) and TypeScript.
- Purpose: Provide a chat interface backed by OpenAI’s GPT models, with real-time streaming, persistent history (Firestore), Google OAuth authentication, and Redis-backed rate limiting.

##### File structure
- src/app – Next.js App Router directory containing:
– Page routes (src/app/page.tsx, src/app/chat/[id]/page.tsx)
– API routes (src/app/api/auth/[...nextauth]/route.ts, chats/route.ts, prompt/route.ts, models/route.ts)
– layout.tsx and globals.css for app-wide layout & styling
- src/components – UI building blocks (chat list, input, header, theme switcher, etc.)
- src/lib – Core business logic and wrappers: auth.ts, chat.ts, openai.ts (streaming), rate-limiter.ts, redis.ts, utils.ts
- src/firebase – Firebase client/server setup for Firestore & Admin SDK
- src/hooks – Custom React hooks for chat state, Firebase messages, scrolling, etc.
- src/config – Static configuration (system prompts, showcase content)
- Middleware & config files – src/middleware.ts (session, rate-limit middleware), next.config.js, Tailwind config, etc.

##### Key insights from README
- Frontend: Next.js + React + Tailwind CSS + Headless UI
- Auth: NextAuth.js with Google OAuth
- Database & Real-time: Firebase Cloud Firestore + react-firebase-hooks
- AI Streaming: OpenAI API via Vercel AI SDK
- Rate Limiting: Upstash Redis + @upstash/ratelimit
- Deployment target: serverless (e.g., Vercel)

##### Diagramming the architecture
a. Main components
- User’s browser (React UI)
- Next.js Frontend (App Router pages + React components)
- NextAuth.js (API route for OAuth sessions)
- Next.js API Routes (serverless functions handling /api/chats, /api/prompt, /api/models)
- Rate limiter (Upstash Redis via @upstash/ratelimit)
- OpenAI API (GPT streaming endpoints)
- Firestore (persistent, real-time chat collection)

b. Relationships & data flow
1. Browser ↔ Next.js Frontend (UI rendering, React state, hooks)
2. Frontend → NextAuth API route → Google OAuth → Session cookie
3. Frontend → API Routes (chats/prompt/models)
4. API Routes → Redis (check/increment rate limit)
5. API Routes → OpenAI API (request & stream GPT response)
6. API Routes → Firestore (write new messages)
7. Browser ←→ Firestore (subscribe to real-time updates via react-firebase-hooks)

c. Architectural patterns
- Serverless microservices: each API route is an isolated function
- Client/Server separation via Next.js App Router (React Server/Client components)
- Real-time pub/sub with Firestore
- Middleware enforcing auth & rate limits on every request

d. Technologies & frameworks
- Frontend: Next.js 13, React 18, TypeScript, Tailwind CSS
- Auth: NextAuth.js, Google OAuth Provider
- DB: Firebase Cloud Firestore, Firebase Admin SDK
- AI: OpenAI API, Vercel AI SDK
- Caching/Rate-limit: Upstash Redis, @upstash/ratelimit

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Browser
    Browser["Browser (React UI)"]:::frontend

    %% Frontend App Router
    subgraph "Frontend (Next.js App)" 
        direction TB
        PageIndex["src/app/page.tsx"]:::frontend
        ChatPage["src/app/chat/[id]/page.tsx"]:::frontend
        Layout["src/app/layout.tsx"]:::frontend
        GlobalsCSS["src/app/globals.css"]:::frontend

        subgraph "UI Components" 
            direction TB
            ChatEntry["ChatEntry"]:::frontend
            ChatHeader["ChatHeader"]:::frontend
            ChatInput["ChatInput"]:::frontend
            ChatList["ChatList"]:::frontend
            ChatView["ChatView"]:::frontend
            ModelSelect["ModelSelect"]:::frontend
            Sidebar["Sidebar"]:::frontend
            ThemeSwitcher["ThemeSwitcher"]:::frontend
            UserAvatar["UserAvatar"]:::frontend
            UserMenu["UserMenu"]:::frontend
        end
    end

    %% API Layer with Middleware
    subgraph "API Layer (Serverless Functions & Middleware)"
        direction TB
        Middleware["src/middleware.ts"]:::api
        subgraph "Auth API"
            NextAuth["src/app/api/auth/[...nextauth]/route.ts"]:::api
        end
        subgraph "Chats API"
            ChatsRoot["src/app/api/chats/route.ts"]:::api
            ChatsId["src/app/api/chats/[id]/route.ts"]:::api
        end
        PromptAPI["src/app/api/prompt/route.ts"]:::api
        ModelsAPI["src/app/api/models/route.ts"]:::api
    end

    %% Core Business Logic
    subgraph "Core Logic (& Wrappers)"
        direction TB
        AuthLib["src/lib/auth.ts"]:::api
        ChatLib["src/lib/chat.ts"]:::api
        OpenAILib["src/lib/openai.ts"]:::api
        PromptLib["src/lib/prompt.ts"]:::api
        RateLimiterLib["src/lib/rate-limiter.ts"]:::api
        RedisLib["src/lib/redis.ts"]:::dbRedis
        UtilsLib["src/lib/utils.ts"]:::api
    end

    %% Firebase Setup
    subgraph "Firebase Setup"
        direction TB
        FirebaseClient["src/firebase/client.ts"]:::dbFire
        FirebaseServer["src/firebase/server.ts"]:::dbFire
    end

    %% Hooks
    subgraph "Custom Hooks"
        direction TB
        UseChatList["src/hooks/useChatList.ts"]:::frontend
        UseChatRefs["src/hooks/useChatRefs.ts"]:::frontend
        UseChatState["src/hooks/useChatState.ts"]:::frontend
        UseFirebaseMsgs["src/hooks/useFirebaseMessages.ts"]:::frontend
        UseScroll["src/hooks/useScrollManagement.ts"]:::frontend
        HooksIndex["src/hooks/index.ts"]:::frontend
    end

    %% Static Config
    subgraph "Static Configuration"
        direction TB
        SystemPrompt["src/config/system-prompt.ts"]:::api
        ShowcaseContent["src/config/showcase-content.ts"]:::api
    end

    %% Databases & External Services
    subgraph "Databases & External Services"
        direction TB
        Firestore["Firestore (Real-time DB)"]:::dbFire
        RedisCache["Redis (Rate Limiting)"]:::dbRedis
        OpenAIService["OpenAI API"]:::externalAI
        GoogleOAuth["Google OAuth Provider"]:::externalAI
    end

    %% Connections
    Browser -->|uses| PageIndex
    Browser -->|uses| ChatPage
    Browser -->|loads layout| Layout
    Browser -->|uses styles| GlobalsCSS
    Browser -->|renders| ChatEntry
    Browser -->|renders| ChatHeader
    Browser -->|renders| ChatInput
    Browser -->|renders| ChatList
    Browser -->|renders| ChatView
    Browser -->|renders| ModelSelect
    Browser -->|renders| Sidebar
    Browser -->|renders| ThemeSwitcher
    Browser -->|renders| UserAvatar
    Browser -->|renders| UserMenu

    Browser -->|calls| NextAuth
    Browser -->|calls| ChatsRoot
    Browser -->|calls| ChatsId
    Browser -->|calls| PromptAPI
    Browser -->|calls| ModelsAPI

    NextAuth -->|verifies| GoogleOAuth
    ChatsRoot -->|rate limit via| RateLimiterLib
    ChatsId -->|rate limit via| RateLimiterLib
    PromptAPI -->|rate limit via| RateLimiterLib
    ModelsAPI -->|rate limit via| RateLimiterLib

    ChatsRoot -->|uses| ChatLib
    ChatsId -->|uses| ChatLib
    PromptAPI -->|uses| PromptLib
    ModelsAPI -->|uses| UtilsLib

    ChatsRoot -->|streams to| OpenAIService
    PromptAPI -->|requests| OpenAIService

    ChatsRoot -->|writes| Firestore
    ChatsId -->|writes| Firestore
    PromptAPI -->|writes| Firestore

    Browser -->|subscribes| Firestore
    UseFirebaseMsgs -->|subscribes| Firestore

    RateLimiterLib -->|stores counters| RedisLib
    Middleware -->|checks auth| NextAuth
    Middleware -->|checks rate| RateLimiterLib

    %% Click Events
    click PageIndex "https://github.com/nabarvn/chadgpt/blob/main/src/app/page.tsx"
    click ChatPage "https://github.com/nabarvn/chadgpt/blob/main/src/app/chat/[id]/page.tsx"
    click Layout "https://github.com/nabarvn/chadgpt/blob/main/src/app/layout.tsx"
    click GlobalsCSS "https://github.com/nabarvn/chadgpt/blob/main/src/app/globals.css"
    click ChatEntry "https://github.com/nabarvn/chadgpt/blob/main/src/components/ChatEntry.tsx"
    click ChatHeader "https://github.com/nabarvn/chadgpt/blob/main/src/components/ChatHeader.tsx"
    click ChatInput "https://github.com/nabarvn/chadgpt/blob/main/src/components/ChatInput.tsx"
    click ChatList "https://github.com/nabarvn/chadgpt/blob/main/src/components/ChatList.tsx"
    click ChatView "https://github.com/nabarvn/chadgpt/blob/main/src/components/ChatView.tsx"
    click ModelSelect "https://github.com/nabarvn/chadgpt/blob/main/src/components/ModelSelect.tsx"
    click Sidebar "https://github.com/nabarvn/chadgpt/blob/main/src/components/Sidebar.tsx"
    click ThemeSwitcher "https://github.com/nabarvn/chadgpt/blob/main/src/components/ThemeSwitcher.tsx"
    click UserAvatar "https://github.com/nabarvn/chadgpt/blob/main/src/components/UserAvatar.tsx"
    click UserMenu "https://github.com/nabarvn/chadgpt/blob/main/src/components/UserMenu.tsx"
    click NextAuth "https://github.com/nabarvn/chadgpt/blob/main/src/app/api/auth/[...nextauth]/route.ts"
    click ChatsRoot "https://github.com/nabarvn/chadgpt/blob/main/src/app/api/chats/route.ts"
    click ChatsId "https://github.com/nabarvn/chadgpt/blob/main/src/app/api/chats/[id]/route.ts"
    click PromptAPI "https://github.com/nabarvn/chadgpt/blob/main/src/app/api/prompt/route.ts"
    click ModelsAPI "https://github.com/nabarvn/chadgpt/blob/main/src/app/api/models/route.ts"
    click Middleware "https://github.com/nabarvn/chadgpt/blob/main/src/middleware.ts"
    click AuthLib "https://github.com/nabarvn/chadgpt/blob/main/src/lib/auth.ts"
    click ChatLib "https://github.com/nabarvn/chadgpt/blob/main/src/lib/chat.ts"
    click OpenAILib "https://github.com/nabarvn/chadgpt/blob/main/src/lib/openai.ts"
    click PromptLib "https://github.com/nabarvn/chadgpt/blob/main/src/lib/prompt.ts"
    click RateLimiterLib "https://github.com/nabarvn/chadgpt/blob/main/src/lib/rate-limiter.ts"
    click RedisLib "https://github.com/nabarvn/chadgpt/blob/main/src/lib/redis.ts"
    click UtilsLib "https://github.com/nabarvn/chadgpt/blob/main/src/lib/utils.ts"
    click FirebaseClient "https://github.com/nabarvn/chadgpt/blob/main/src/firebase/client.ts"
    click FirebaseServer "https://github.com/nabarvn/chadgpt/blob/main/src/firebase/server.ts"
    click UseChatList "https://github.com/nabarvn/chadgpt/blob/main/src/hooks/useChatList.ts"
    click UseChatRefs "https://github.com/nabarvn/chadgpt/blob/main/src/hooks/useChatRefs.ts"
    click UseChatState "https://github.com/nabarvn/chadgpt/blob/main/src/hooks/useChatState.ts"
    click UseFirebaseMsgs "https://github.com/nabarvn/chadgpt/blob/main/src/hooks/useFirebaseMessages.ts"
    click UseScroll "https://github.com/nabarvn/chadgpt/blob/main/src/hooks/useScrollManagement.ts"
    click HooksIndex "https://github.com/nabarvn/chadgpt/blob/main/src/hooks/index.ts"
    click SystemPrompt "https://github.com/nabarvn/chadgpt/blob/main/src/config/system-prompt.ts"
    click ShowcaseContent "https://github.com/nabarvn/chadgpt/blob/main/src/config/showcase-content.ts"

    %% Styles
    classDef frontend fill:#f4f4f4,stroke:#333,stroke-width:1px
    classDef api fill:#222,stroke:#fff,stroke-width:1px,color:#fff
    classDef dbFire fill:#f90,stroke:#333,stroke-width:1px
    classDef dbRedis fill:#9f9,stroke:#333,stroke-width:1px
    classDef externalAI fill:#38b2ac,stroke:#333,stroke-width:1px,color:#fff
```
