# samalehzen/emd-chat-ai architecture

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

- Interactive diagram: https://gitdiagram.com/samalehzen/emd-chat-ai
- Repository: https://github.com/samalehzen/emd-chat-ai

## Overview

##### Project Type and Purpose
- This is a full-stack, self-hostable AI chat interface built on Next.js (“app” directory), with API routes for chat and user management, and integrations with multiple AI providers (OpenAI, Claude, Gemini, etc.) plus local Ollama models. It uses Supabase for auth & storage, and includes client-side state stores for chats, agents, settings, and user preferences.

##### Main Components
a. Frontend (Next.js + React)
- “app” directory: pages (client and server components) for chat UI, agent management, auth flows, and static pages.
- “app2/components” & “components”: reusable UI widgets (shadcn/ui, prompt-kit, motion-primitives).
- Hooks: custom React hooks (e.g., useChatDraft) for local state & UI behaviors.

b. Backend (Next.js API Routes & Lib Layer)
- “app/api” routes: chat, create-agent, user & guest creation, CSRF, rate limits, developer-tools, health checks.
- “lib” folder: core business logic & data access
- Providers for AI models (“lib/openproviders”, “lib/providers”)
- Chat & agent stores: in-memory/session via React contexts (“lib/chat-store”, “lib/agent-store”)
- Supabase integration (“lib/supabase” + “utils/supabase”) for DB reads/writes and auth.
- Tools engine (“lib/tools/exa”) for external utilities (web search, image search).
- Config, utilities (fetch wrappers, sanitization, CSRF helper).

c. External Services
- Supabase: Auth, Database, File Storage
- AI Providers: OpenAI/Mistral/Claude/Gemini via Vercel AI SDK & custom providers
- Ollama (local AI): via Docker or direct CLI, auto-detected by “lib/mcp”

##### Relationships & Data Flow
1) User interacts with Next.js UI →
2) Frontend calls API route (e.g., POST /api/chat/route.ts) →
3) Route handler uses lib/api.ts + lib/chat-store to:
- Validate session/CSRF →
- Persist messages in Supabase (or session store) →
- Call AI provider via lib/openproviders →
- Stream or return AI response →
4) Frontend receives response and updates UI & local store.
5) File uploads: via API route → Supabase Storage → context-aware prompts.
6) Agent creation/deletion: API → Supabase / local store → UI refresh.

##### Architectural Patterns & Principles
- Next.js App Router: server/client component separation
- Layered architecture: API routes → lib business logic → provider adapters → external services
- React Context / Provider pattern for state stores (Zustand or Context APIs)
- Routing via filesystem for both UI and API
- Extensibility: plugin-style AI provider map and tool invocation modules

## Diagram (Mermaid)

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

    %% Frontend Layer
    subgraph "Frontend UI" 
        direction TB
        FE1["Next.js App Router"]:::ui
        FE2["Global Layout & Styling"]:::ui
        FE3["Reusable UI Components"]:::ui
        FE4["Custom React Hooks"]:::ui
    end

    %% API Layer
    subgraph "API Layer" 
        direction TB
        API1["Next.js API Routes"]:::api
        API2["Core API & Routes Helper"]:::api
    end

    %% Business Logic & State Stores
    subgraph "Business Logic" 
        direction TB
        BL1["AI Provider Adapters"]:::logic
        BL2["Model Metadata Definitions"]:::logic
        BL3["Local Ollama Loader"]:::logic
        BL4["External Tools Engine"]:::logic
        BL5["Configuration & Utilities"]:::logic
        BL6["Supabase Integration"]:::external_service
        subgraph "State Stores" 
            direction TB
            SS1["Chat State Store"]:::store
            SS2["Agent State Store"]:::store
            SS3["Settings Store"]:::store
            SS4["User Preference Store"]:::store
            SS5["User Store & Guest Logic"]:::store
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        ES1["Supabase (Auth/DB/Storage)"]:::external_service
        ES2["AI Providers"]:::external_service
        ES3["Local Ollama"]:::external_service
        ES4["Tools Engine"]:::external_service
    end

    %% Connections
    User -->|"interacts"| FE1
    FE1 -->|"calls UI Layout"| FE2
    FE1 -->|"renders components"| FE3
    FE1 -->|"uses hooks"| FE4

    FE1 -->|"POST /api/*"| API1
    API1 -->|"uses lib/api & routes"| API2
    API2 -->|"invokes adapters"| BL1
    API2 -->|"reads models"| BL2
    API2 -->|"calls Ollama"| BL3
    API2 -->|"executes tools"| BL4
    API2 -->|"uses utils"| BL5
    API2 -->|"DB read/write"| BL6
    API2 -->|"manages sessions"| SS5

    FE1 -->|"context state"| SS1
    FE1 -->|"context state"| SS2
    FE1 -->|"context state"| SS3
    FE1 -->|"context state"| SS4

    BL6 -->|"calls"| ES1
    BL1 -->|"requests"| ES2
    BL3 -->|"invokes CLI"| ES3
    BL4 -->|"requests"| ES4

    %% Click Events for Component Mapping
    click FE1 "https://github.com/samalehzen/emd-chat-ai/tree/main/app/"
    click FE2 "https://github.com/samalehzen/emd-chat-ai/blob/main/app/layout.tsx"
    click FE2 "https://github.com/samalehzen/emd-chat-ai/blob/main/app/globals.css"
    click FE3 "https://github.com/samalehzen/emd-chat-ai/tree/main/app2/components/"
    click FE3 "https://github.com/samalehzen/emd-chat-ai/tree/main/components/"
    click FE4 "https://github.com/samalehzen/emd-chat-ai/tree/main/app/hooks/"

    click API1 "https://github.com/samalehzen/emd-chat-ai/tree/main/app/api/"
    click API2 "https://github.com/samalehzen/emd-chat-ai/blob/main/lib/api.ts"
    click API2 "https://github.com/samalehzen/emd-chat-ai/blob/main/lib/routes.ts"

    click BL1 "https://github.com/samalehzen/emd-chat-ai/tree/main/lib/openproviders/"
    click BL1 "https://github.com/samalehzen/emd-chat-ai/blob/main/lib/providers/index.ts"
    click BL2 "https://github.com/samalehzen/emd-chat-ai/tree/main/lib/models/"
    click BL3 "https://github.com/samalehzen/emd-chat-ai/tree/main/lib/mcp/"
    click BL4 "https://github.com/samalehzen/emd-chat-ai/tree/main/lib/tools/exa/"
    click BL4 "https://github.com/samalehzen/emd-chat-ai/blob/main/lib/tools/index.ts"
    click BL5 "https://github.com/samalehzen/emd-chat-ai/blob/main/lib/config.ts"
    click BL5 "https://github.com/samalehzen/emd-chat-ai/blob/main/lib/csrf.ts"
    click BL5 "https://github.com/samalehzen/emd-chat-ai/blob/main/lib/fetch.ts"
    click BL5 "https://github.com/samalehzen/emd-chat-ai/blob/main/lib/sanitize.ts"
    click BL5 "https://github.com/samalehzen/emd-chat-ai/blob/main/lib/utils.ts"
    click BL6 "https://github.com/samalehzen/emd-chat-ai/tree/main/lib/supabase/"
    click BL6 "https://github.com/samalehzen/emd-chat-ai/tree/main/utils/supabase/"

    click SS1 "https://github.com/samalehzen/emd-chat-ai/tree/main/lib/chat-store/"
    click SS2 "https://github.com/samalehzen/emd-chat-ai/tree/main/lib/agent-store/"
    click SS3 "https://github.com/samalehzen/emd-chat-ai/tree/main/lib/settings-store/"
    click SS4 "https://github.com/samalehzen/emd-chat-ai/tree/main/lib/user-preference-store/"
    click SS5 "https://github.com/samalehzen/emd-chat-ai/tree/main/lib/user-store/"
    click SS5 "https://github.com/samalehzen/emd-chat-ai/blob/main/lib/user/api.ts"

    click ES1 "https://github.com/samalehzen/emd-chat-ai/tree/main/lib/supabase/"
    click ES2 "https://github.com/samalehzen/emd-chat-ai/tree/main/lib/openproviders/"
    click ES3 "https://github.com/samalehzen/emd-chat-ai/tree/main/lib/mcp/"
    click ES4 "https://github.com/samalehzen/emd-chat-ai/tree/main/lib/tools/exa/"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef api fill:#D1F7C4,stroke:#228B22,color:#228B22;
    classDef logic fill:#E8F4FA,stroke:#4682B4,color:#4682B4;
    classDef store fill:#F5E0FD,stroke:#800080,color:#800080;
    classDef external_service fill:#FFE4B5,stroke:#FF8C00,color:#FF8C00;
    classDef external fill:#CCCCCC,stroke:#666666,color:#666666;
```
