# ibelick/zola architecture

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

- Interactive diagram: https://gitdiagram.com/ibelick/zola
- Repository: https://github.com/ibelick/zola

## Overview

##### Project’s Type and Purpose
- Zola is an open-source AI chat application with multi-model support. It integrates AI models (like OpenAI and Mistral) to facilitate chat functionalities.
- The README highlights key features (prompt suggestions, file uploads, multi-model integration, light/dark mode) and technologies (prompt-kit, shadcn/ui, motion-primitives, vercel ai sdk, and supabase).

##### File Structure
- The project follows a Next.js architecture given the /app directory structure and API routes in /app/api. Notice the use of files like route.ts, page.tsx, and layout.tsx, which are typical for Next.js apps.
- The structure separates out API endpoints (e.g., chat, create-chat, auth callbacks) and UI components (nested inside app/components and additional shared components under components/).
- There is a clear division between front-end pages (React components, layouts, hooks, and UI pieces) and server-side functionalities (API endpoints, authentication, and supabase integrations stored under app/api, app/lib, and utils/supabase).

##### Main Components
a. Frontend (User Interface):
- Pages: Main pages like the chat screen, authentication pages (login, error, callback).
- Layout & UI Components: Under app/components and components/ui, which include header, chat input, conversation display, history view, and dynamic UI elements (via shadcn/ui, motion-primitives, prompt-kit).
- Client-side hooks and providers: Manage breakpoint detection, outside clicks, user state (user-provider.tsx) to ensure interactive experience.

b. Backend (API and Server-side Logic):
- API Endpoints: Clear endpoints for chat functionalities, creating chat sessions/guests, updating chat models, handling rate limits.
- Authentication: The auth folder contains routes and pages to handle login callbacks, errors, and secure access.
- Server-Side Libraries: app/lib contains server helpers for API handling and supabase integrations, along with file handling and configuration utilities.

c. Storage and External Services:
- Integration with Supabase: Found under app/lib/supabase, utils/supabase, indicating authentication and possibly data storage.
- AI Model Integration: Using the vercel ai sdk and prompt-kit, the app supports multi-model operations and possibly model switching.

##### Relationships and Interactions
- The Frontend interacts with Backend API endpoints to perform operations such as initiating chat sessions, updating models, and enforcing rate limits.
- The authentication flow includes callbacks and error pages that mediate between the Supabase backend and the frontend.
- UI components leverage external libraries (prompt-kit, shadcn/ui, motion-primitives) to build an interactive and responsive chat interface.
- The API endpoints feed into the functional components (chat input, conversation views) that are rendered on client-side pages.

##### Architectural Patterns & Design Principles
- Component-based design: Clear separation of UI elements into modular components, state providers, and hooks.
- API-driven architecture: Distinct API endpoints for handling different chat functionalities (e.g., chat creation, update, rate-limiting).
- Integration of external services: Supabase for authentication/storage and multiple libraries to support rich UI/UX and AI model integration.
- File-based routing: Leveraging Next.js capabilities by organizing routes and endpoints within the filesystem (using route.ts and page.tsx files).

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User"]:::external

    subgraph "Frontend UI"
        subgraph "Pages & Layout"
            PL_Main["Main Page"]:::frontend
            PL_Chat["Chat Page"]:::frontend
            PL_Global["Global Layout"]:::frontend
            PL_Layout["Layout Components"]:::frontend
        end
        subgraph "Chat & Conversation"
            ChatComp["Chat Components"]:::frontend
        end
        subgraph "Chat Input"
            ChatInput["Chat Input Components"]:::frontend
        end
        subgraph "History & Navigation"
            History["History Components"]:::frontend
            Nav["Navigation Components"]:::frontend
        end
        subgraph "UI Elements & Providers"
            Provider["User Provider"]:::frontend
            Hooks["Hooks"]:::frontend
            UIComp["UI Components"]:::frontend
        end
    end

    subgraph "Backend API Endpoints"
        ChatAPI["Chat API"]:::backend
        CreateChatAPI["Create Chat API"]:::backend
        CreateGuestAPI["Create Guest API"]:::backend
        UpdateChatAPI["Update Chat Model API"]:::backend
        RateLimitAPI["Rate Limits API"]:::backend
    end

    subgraph "Authentication"
        AuthCallback["Auth Callback"]:::backend
        AuthError["Auth Error Page"]:::backend
        AuthLogin["Auth Login Actions"]:::backend
        AuthPage["Auth Page"]:::backend
    end

    subgraph "External Services"
        SupabaseHelp["Supabase Helpers"]:::external
        SupabaseMid["Supabase Middleware"]:::external
        AIPrompt["AI Prompt Kit"]:::external
        AIIcons["AI Icons"]:::external
    end

    %% User interactions with Frontend
    User -->|"interacts"| PL_Main
    User -->|"interacts"| ChatComp
    User -->|"interacts"| ChatInput
    User -->|"interacts"| History
    User -->|"interacts"| Nav

    %% Frontend to Backend API calls
    ChatComp -->|"calls"| ChatAPI
    ChatInput -->|"calls"| ChatAPI

    %% API chaining within Backend Endpoints
    ChatAPI -->|"triggers"| CreateChatAPI
    ChatAPI -->|"triggers"| CreateGuestAPI
    ChatAPI -->|"triggers"| UpdateChatAPI
    ChatAPI -->|"triggers"| RateLimitAPI

    %% API endpoints interacting with Supabase integration
    ChatAPI -->|"accesses"| SupabaseHelp
    CreateChatAPI -->|"accesses"| SupabaseHelp
    CreateGuestAPI -->|"accesses"| SupabaseHelp
    UpdateChatAPI -->|"accesses"| SupabaseHelp
    RateLimitAPI -->|"accesses"| SupabaseHelp

    %% Supabase integration links to Authentication flows
    SupabaseHelp -->|"authenticates"| AuthCallback
    SupabaseHelp -->|"authenticates"| AuthError
    SupabaseHelp -->|"authenticates"| AuthLogin
    SupabaseHelp -->|"authenticates"| AuthPage
    SupabaseHelp -->|"flows to"| SupabaseMid

    %% Frontend UI Providers using AI Model Integration
    Provider -->|"uses"| AIPrompt
    Hooks -->|"uses"| AIPrompt
    UIComp -->|"uses"| AIPrompt
    AIPrompt -->|"complements"| AIIcons

    %% Click Events for Frontend UI Components
    click PL_Main "https://github.com/ibelick/zola/blob/main/app/page.tsx"
    click PL_Chat "https://github.com/ibelick/zola/blob/main/app/c/[chatId]/page.tsx"
    click PL_Global "https://github.com/ibelick/zola/blob/main/app/layout.tsx"
    click PL_Layout "https://github.com/ibelick/zola/tree/main/app/components/layout/"

    click ChatComp "https://github.com/ibelick/zola/tree/main/app/components/chat/"
    click ChatInput "https://github.com/ibelick/zola/tree/main/app/components/chat-input/"
    click History "https://github.com/ibelick/zola/tree/main/app/components/history/"
    click Nav "https://github.com/ibelick/zola/tree/main/app/components/layout/"

    click Provider "https://github.com/ibelick/zola/blob/main/app/providers/user-provider.tsx"
    click Hooks "https://github.com/ibelick/zola/tree/main/app/hooks/"
    click UIComp "https://github.com/ibelick/zola/tree/main/components/ui/"

    %% Click Events for Backend API Endpoints
    click ChatAPI "https://github.com/ibelick/zola/blob/main/app/api/chat/route.ts"
    click CreateChatAPI "https://github.com/ibelick/zola/blob/main/app/api/create-chat/route.ts"
    click CreateGuestAPI "https://github.com/ibelick/zola/blob/main/app/api/create-guest/route.ts"
    click UpdateChatAPI "https://github.com/ibelick/zola/blob/main/app/api/update-chat-model/route.ts"
    click RateLimitAPI "https://github.com/ibelick/zola/blob/main/app/api/rate-limits/route.ts"

    %% Click Events for Authentication Components
    click AuthCallback "https://github.com/ibelick/zola/blob/main/app/auth/callback/route.ts"
    click AuthError "https://github.com/ibelick/zola/blob/main/app/auth/error/page.tsx"
    click AuthLogin "https://github.com/ibelick/zola/blob/main/app/auth/login/actions.ts"
    click AuthPage "https://github.com/ibelick/zola/blob/main/app/auth/page.tsx"

    %% Click Events for Supabase Integration
    click SupabaseHelp "https://github.com/ibelick/zola/tree/main/app/lib/supabase/"
    click SupabaseMid "https://github.com/ibelick/zola/blob/main/utils/supabase/middleware.ts"

    %% Click Events for AI Model Integration
    click AIPrompt "https://github.com/ibelick/zola/tree/main/components/prompt-kit/"
    click AIIcons "https://github.com/ibelick/zola/tree/main/components/icons/"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef backend fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef external fill:#D5F5E3,stroke:#28B463,stroke-width:2px;
```
