# okisdev/chatchat architecture

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

- Interactive diagram: https://gitdiagram.com/okisdev/chatchat
- Repository: https://github.com/okisdev/chatchat

## Overview

##### Project type and purpose
- This is a full‑stack web application built with Next.js (app router) that provides a unified chat and search interface to multiple AI providers.
- Its primary use case is to let end‑users perform chat conversations and web‑style searches via a single interface, backed by major AI/ML APIs (OpenAI, Anthropic, Google Gemini, Cohere, etc.).

##### File structure
- Top‑level:
- app/ — Next.js “app router” pages, layouts, server/provider components
- app/api/ — API route handlers for chat and search
- components/ — shared UI primitives and layouts (shadcn/ui + Tailwind CSS)
- config/ — provider and search configuration files
- lib/ — core logic modules (provider and search implementations)
- hooks/, utils/ — React hooks and utility functions
- public/, styles/, locales/ — static assets, global styles, i18n resource files
- Dockerfile, docker‑compose.yml, GitHub workflows — containerization and CI/CD
- The project uses an MVC‑style split:
- View: React components in app/ and components/
- Controller: Next.js API routes in app/api/
- Model/Logic: lib/ and config/ modules that wrap external AI/search services

##### README for additional insights
- The stack is Next.js + Tailwind CSS + shadcn UI.
- Deployable on Vercel, Railway, or Docker.

##### Main components
a. Frontend (Next.js SSR/CSR)
- App router pages: app/[locale]/(home)/…
- React state/hook layer: hooks/, app/provider.tsx
- UI component library: components/ui + components/layout
- i18n: locales/ + config/i18n
b. Backend API
- Chat service endpoints: app/api/chat/messages/[provider]/route.ts
- Search service endpoints: app/api/search/[engine]/route.ts
- App metadata endpoint: app/api/app/latest/route.ts
c. Core business logic
- Provider abstractions: lib/provider/*.ts + config/provider/*.ts
- Search modules: lib/search/*.ts + config/search/*.ts
- Shared utilities: utils/app, utils/provider, utils/search
d. External services
- AI provider REST APIs (OpenAI, Anthropic, Cohere, …)
- Search engine APIs (Google, Tavern, You.com, etc.)
- Optional: Vercel/Railway hosting, Docker registry
e. Static and supporting layers
- Global styling: styles/globals.css, tailwind.config.ts

##### Relationships and interactions
- User ↔ Frontend UI
- Frontend sends HTTP requests to Next.js API routes
- API routes invoke lib/provider or lib/search modules
- Those modules call external AI/search APIs
- Results flow back through API → frontend → rendered components
- Config files drive runtime behavior (provider keys, search parameters)
- Hooks manage client state (theme, storage, session)

##### Architectural patterns and design principles
- Separation of concerns (UI vs. API vs. business logic)
- Pluggable provider strategy (one route per provider, common interface)
- Modular component library for consistent styling and functionality
- Internationalization at routing layer via Next.js dynamic locale segments
- Containerized deployment for consistent environments

##### Final advice
- Be exhaustive: map out each major directory as a component or subcomponent.
- Flow of data (chat vs. search) separately if needed.
- Review the README stack & config folders to ensure all runtime dependencies (i18n, theming, hooks) are represented.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client-side
    subgraph "Client-side" 
        direction TB
        FE["Next.js Frontend"]:::frontend
        subgraph "Layouts & Providers"
            direction TB
            L1["app/layout.tsx"]:::frontend
            L2["app/provider.tsx"]:::frontend
            L3["app/[locale]/layout.tsx"]:::frontend
            L4["app/[locale]/provider.tsx"]:::frontend
            L5["app/[locale]/(home)/layout.tsx"]:::frontend
        end
        subgraph "Pages & Views"
            direction TB
            P1["app/[locale]/(home)/(chat)/page.tsx"]:::frontend
            P2["app/[locale]/(home)/search/page.tsx"]:::frontend
            P3["app/[locale]/(home)/action.tsx"]:::frontend
            P4["app/[locale]/(home)/sidebar.tsx"]:::frontend
            P5["app/not-found.tsx"]:::frontend
        end
        subgraph "UI Components"
            direction TB
            UI1["components/ui/**"]:::frontend
            UI2["components/layout/**"]:::frontend
        end
        subgraph "Hooks"
            direction TB
            H1["hooks/storage.ts"]:::frontend
            H2["hooks/store.ts"]:::frontend
            H3["hooks/theme.tsx"]:::frontend
            H4["hooks/window.ts"]:::frontend
        end
    end

    %% Server-side
    subgraph "Server-side"
        direction TB
        API["Next.js API Server"]:::server

        subgraph "Chat Service Endpoints"
            direction TB
            C0["app/api/chat/messages/route.ts"]:::server
            C1["app/api/chat/messages/openai/route.ts"]:::server
            C2["app/api/chat/messages/anthropic/route.ts"]:::server
            %% ... other providers
        end

        subgraph "Search Service Endpoints"
            direction TB
            S0["app/api/search/route.ts"]:::server
            S1["app/api/search/google/route.ts"]:::server
        end

        M["app/api/app/latest/route.ts"]:::server
    end

    %% Core Logic Modules
    subgraph "Core Logic & Config"
        direction TB
        subgraph "Provider Abstractions"
            direction TB
            PA1["lib/provider/Anthropic.ts"]:::logic
            PA2["lib/provider/Google.ts"]:::logic
            PA3["lib/provider/OpenAI.ts"]:::logic
        end
        subgraph "Search Implementations"
            direction TB
            SI1["lib/search/challenger.tsx"]:::logic
            SI2["lib/search/clarifier.tsx"]:::logic
            SI3["lib/search/illustrator.tsx"]:::logic
            SI4["lib/search/searcher.tsx"]:::logic
        end
        PH["lib/prompt/index.ts"]:::logic

        subgraph "Configurations"
            direction TB
            PC["config/provider/*.ts"]:::config
            SC["config/search/index.ts"]:::config
            IC["config/i18n/index.ts"]:::config
            TC["config/theme/index.ts"]:::config
        end

        subgraph "Utilities"
            direction TB
            U1["utils/app/time.ts"]:::config
            U2["utils/app/uuid.ts"]:::config
            U3["utils/app/version.ts"]:::config
            U4["utils/provider/google.tsx"]:::config
            U5["utils/provider/cohere.tsx"]:::config
            U6["utils/search/engines/google.ts"]:::config
            U7["utils/search/engines/tavily.ts"]:::config
            U8["utils/search/engines/you.ts"]:::config
            U9["utils/search/image.ts"]:::config
        end
    end

    %% External Services
    subgraph "External AI/Search Services"
        direction TB
        EA["AI Provider APIs"]:::external
        ES["Search Engine APIs"]:::external
    end

    %% Static Assets & Styles
    subgraph "Static & i18n"
        direction TB
        SA["public/icons/**, public/img/**"]:::static
        GS["styles/globals.css, tailwind.config.ts"]:::static
        LO["locales/*.json"]:::static
    end

    %% Deployment
    subgraph "Deployment & CI/CD"
        direction TB
        D1["Dockerfile"]:::devops
        D2["docker-compose.yml"]:::devops
        D3[".github/workflows/docker-image.yml"]:::devops
    end

    %% Connections
    FE -->|renders| P1
    FE -->|renders| P2
    FE -->|uses| L1
    FE -->|uses| UI1
    FE -->|uses| H1

    P1 -->|POST /api/chat/messages/openai| C1
    P1 -->|POST /api/chat/messages/anthropic| C2
    P2 -->|GET /api/search/google| S1
    M -->|GET metadata| FE

    C1 -->|invoke| PA3
    C2 -->|invoke| PA1
    S1 -->|invoke| SI4
    PA3 -->|calls| EA
    PA1 -->|calls| EA
    SI4 -->|calls| ES

    PC -->|drives| PA1
    SC -->|drives| SI4
    IC -->|drives| FE
    TC -->|drives| FE

    SA -->|served by CDN| FE
    GS -->|applied to| FE
    LO -->|i18n resources| FE

    D1 -->|build & deploy| FE
    D1 -->|build & deploy| API
    D3 -->|CI/CD pipeline| D1

    %% Click Events
    click L1 "https://github.com/okisdev/chatchat/blob/main/app/layout.tsx"
    click L2 "https://github.com/okisdev/chatchat/blob/main/app/provider.tsx"
    click L3 "https://github.com/okisdev/chatchat/blob/main/app/[locale]/layout.tsx"
    click L4 "https://github.com/okisdev/chatchat/blob/main/app/[locale]/provider.tsx"
    click L5 "https://github.com/okisdev/chatchat/blob/main/app/[locale]/(home)/layout.tsx"
    click P1 "https://github.com/okisdev/chatchat/blob/main/app/[locale]/(home)/(chat)/page.tsx"
    click P2 "https://github.com/okisdev/chatchat/blob/main/app/[locale]/(home)/search/page.tsx"
    click P3 "https://github.com/okisdev/chatchat/blob/main/app/[locale]/(home)/action.tsx"
    click P4 "https://github.com/okisdev/chatchat/blob/main/app/[locale]/(home)/sidebar.tsx"
    click P5 "https://github.com/okisdev/chatchat/blob/main/app/not-found.tsx"
    click UI1 "https://github.com/okisdev/chatchat/tree/main/components/ui/"
    click UI2 "https://github.com/okisdev/chatchat/tree/main/components/layout/"
    click H1 "https://github.com/okisdev/chatchat/blob/main/hooks/storage.ts"
    click H2 "https://github.com/okisdev/chatchat/blob/main/hooks/store.ts"
    click H3 "https://github.com/okisdev/chatchat/blob/main/hooks/theme.tsx"
    click H4 "https://github.com/okisdev/chatchat/blob/main/hooks/window.ts"
    click M "https://github.com/okisdev/chatchat/blob/main/app/api/app/latest/route.ts"
    click C0 "https://github.com/okisdev/chatchat/blob/main/app/api/chat/messages/route.ts"
    click C1 "https://github.com/okisdev/chatchat/blob/main/app/api/chat/messages/openai/route.ts"
    click C2 "https://github.com/okisdev/chatchat/blob/main/app/api/chat/messages/anthropic/route.ts"
    click S0 "https://github.com/okisdev/chatchat/blob/main/app/api/search/route.ts"
    click S1 "https://github.com/okisdev/chatchat/blob/main/app/api/search/google/route.ts"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#3399ff,color:#000
    classDef server fill:#d4edda,stroke:#28a745,color:#000
    classDef logic fill:#f8d7da,stroke:#dc3545,color:#000
    classDef config fill:#e2e3e5,stroke:#6c757d,color:#000
    classDef external fill:#fff3cd,stroke:#ffc107,color:#000
    classDef static fill:#e2e3e5,stroke:#6c757d,color:#000
    classDef devops fill:#d1ecf1,stroke:#17a2b8,color:#000
```
