# homanp/langchain-ui architecture

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

- Interactive diagram: https://gitdiagram.com/homanp/langchain-ui
- Repository: https://github.com/homanp/langchain-ui

## Overview

##### Project Type and Purpose
- This is a full-stack web application built with Next.js 13 (appDir).
- It provides a no-code UI for creating and hosting AI chatbots on top of LangChain.
- Key features include chatbot CRUD, external data-source ingestion, custom prompt templates, auth via NextAuth, database via Prisma, and an external Python-based LangChain UI API.

##### Main Architectural Components
a. Frontend (Next.js appDir + Components)
- `app/` directory: UI pages and layouts (chatbots, datasources, prompt-templates, login).
- `components/`: reusable React components (Chat UI, file picker, page header, user menu).
- `public/`: static assets.
b. Backend (Next.js API routes + Lib modules)
- `pages/api/`: Next.js serverless functions handling CRUD for chatbots, datasources, prompt-templates, and auth (`next-auth`).
- `lib/`: utility modules (API client for LangChain UI Python service, Prisma client, S3 upload, sidebar data, theming, markdown rendering).
c. Database (Prisma + Underlying DB)
- `prisma/schema.prisma` and migration files define models: User, Chatbot, Message, PromptTemplate, Datasource, UsageQuotas.
- Interactions performed via Prisma Client in `lib/prisma.js`.
d. External Services
- LangChain UI Python API: handles LLM calls, agent orchestration, prompt execution. Accessed via HTTP in `lib/api.js`.
- OAuth Provider (GitHub by default) via NextAuth.
- AWS S3 (or other object storage) for file uploads (`lib/s3.js`, `lib/upload-file.js`, `lib/upload-url.js`).

##### Component Interactions and Data Flows
- User → Frontend UI → NextAuth middleware → Session context.
- Frontend chat UI → Next.js API `/api/chatbots/[id]/messages` → `lib/api.js` calls external Python API → LLM processes + returns response → saved via Prisma → returned to frontend.
- CRUD operations on chatbots, datasources, prompt-templates → Next.js API routes → Prisma → Database.
- File ingestion → Frontend file-picker → Next.js API `/api/datasources/ingest` → `lib/s3.js` or `lib/upload-url.js` → persisted data → Database.
- Prompt execution → Frontend selects template → API routes → combined with user input → passed to external API.

##### Architectural Patterns and Design Principles
- Full-stack React + Serverless Functions (Next.js API routes) with clear separation of concerns.
- Thin server layer: most business logic deferred to external LangChain UI Python API.
- Modular design: `app/`, `components/`, `pages/api/`, and `lib/`.
- Data access layer via Prisma ORM.
- Authentication as middleware (NextAuth).
- Environment-driven configuration (`.env`).

2. Next.js Frontend block (app/ + components/) next.
- UI → API (CRUD) → DB
- UI → API → External API → DB → API → UI
- API → S3 for uploads
- UI ↔ Auth provider → DB (sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User((User)):::external

    %% Frontend Layer
    subgraph "Frontend (Next.js React)" 
        direction TB
        ChatbotsUI["Chatbots UI Pages"]:::frontend
        DatasourcesUI["Datasources UI Pages"]:::frontend
        PromptTemplatesUI["Prompt Templates UI Pages"]:::frontend
        LoginUI["Login UI Pages"]:::frontend
        Layouts["Layouts & Shared UI"]:::frontend
        GlobalApp["Global App & Providers"]:::frontend
    end

    %% API Layer
    subgraph "API Layer (Next.js API Routes)"
        direction TB
        ChatbotsAPI["Chatbots CRUD & Messages API"]:::api
        DatasourcesAPI["Datasources CRUD & Ingest API"]:::api
        PromptsAPI["Prompt Templates CRUD API"]:::api
        AuthAPI["NextAuth API Route"]:::api
    end

    %% Business Logic & Utilities
    subgraph "Business Logic & Utilities (lib/)" 
        direction TB
        APIClient["LangChain UI Python API Client\n(lib/api.js)"]:::logic
        PrismaClient["Prisma Client (lib/prisma.js)"]:::logic
        S3Utils["S3 Utilities (lib/s3.js)"]:::logic
        UploadFile["File Upload (lib/upload-file.js)"]:::logic
        UploadURL["URL Upload (lib/upload-url.js)"]:::logic
        Sidebar["Sidebar & Theme (lib/sidebar.js,\n lib/theme.js, lib/metal.js)"]:::logic
        Markdown["Markdown & API Docs\n(lib/markdown.js, lib/api-docs.js)"]:::logic
    end

    %% Persistence Layer
    subgraph "Persistence"
        direction TB
        Database["Database (PostgreSQL/MySQL)"]:::persistence
        Migrations["Prisma Migrations"]:::persistence
        S3Bucket["Object Storage (S3)"]:::persistence
    end

    %% External Services
    subgraph "External Services"
        direction TB
        LangChainAPI["LangChain UI Python API"]:::external
        OAuthProvider["GitHub OAuth Provider"]:::external
    end

    %% Connections
    User -->|"Interacts with"| ChatbotsUI
    User -->|"Interacts with"| DatasourcesUI
    User -->|"Interacts with"| PromptTemplatesUI
    User -->|"Interacts with"| LoginUI

    ChatbotsUI -->|"REST/HTTP"| ChatbotsAPI
    DatasourcesUI -->|"REST/HTTP"| DatasourcesAPI
    PromptTemplatesUI -->|"REST/HTTP"| PromptsAPI
    LoginUI -->|"REST/HTTP"| AuthAPI
    ChatbotsUI -->|"NextAuth Session"| AuthAPI
    AuthAPI -->|"<-> Session Data"| Database

    ChatbotsAPI -->|"SQL Queries"| PrismaClient
    DatasourcesAPI -->|"SQL Queries"| PrismaClient
    PromptsAPI -->|"SQL Queries"| PrismaClient

    PrismaClient -->|"Reads/Writes"| Database
    PrismaClient -->|"Runs"| Migrations

    ChatbotsAPI -->|"Calls"| APIClient
    APIClient -->|"HTTP Request"| LangChainAPI
    LangChainAPI -->|"LLM Response"| APIClient
    APIClient -->|"Returns Data"| ChatbotsAPI

    DatasourcesAPI -->|"File Upload"| S3Utils
    S3Utils -->|"PUT Object"| S3Bucket
    DatasourcesAPI -->|"URL Upload"| UploadURL
    UploadURL -->|"PUT Object"| S3Bucket

    PromptsAPI -->|"Uses Templates"| Markdown

    ChatbotsAPI -->|"Sidebar Data"| Sidebar
    DatasourcesAPI -->|"Theme Data"| Sidebar

    %% Legend (optional grouping)
    subgraph Legend
        direction TB
        F[Frontend]:::frontend
        A[API]:::api
        L[Logic]:::logic
        P[Persistence]:::persistence
        E[External]:::external
    end

    %% Click Events for component mappings
    click ChatbotsUI "https://github.com/homanp/langchain-ui/tree/main/app/app/chatbots"
    click DatasourcesUI "https://github.com/homanp/langchain-ui/tree/main/app/app/datasources"
    click PromptTemplatesUI "https://github.com/homanp/langchain-ui/tree/main/app/app/prompt-templates"
    click LoginUI "https://github.com/homanp/langchain-ui/tree/main/app/app/user/login"
    click Layouts "https://github.com/homanp/langchain-ui/tree/main/app/app"
    click GlobalApp "https://github.com/homanp/langchain-ui/tree/main/app"
    click AuthAPI "https://github.com/homanp/langchain-ui/blob/main/pages/api/auth/[...nextauth].js"
    click ChatbotsAPI "https://github.com/homanp/langchain-ui/tree/main/pages/api/chatbots"
    click DatasourcesAPI "https://github.com/homanp/langchain-ui/tree/main/pages/api/datasources"
    click PromptsAPI "https://github.com/homanp/langchain-ui/tree/main/pages/api/prompt-templates"
    click APIClient "https://github.com/homanp/langchain-ui/blob/main/lib/api.js"
    click PrismaClient "https://github.com/homanp/langchain-ui/blob/main/lib/prisma.js"
    click S3Utils "https://github.com/homanp/langchain-ui/blob/main/lib/s3.js"
    click UploadFile "https://github.com/homanp/langchain-ui/blob/main/lib/upload-file.js"
    click UploadURL "https://github.com/homanp/langchain-ui/blob/main/lib/upload-url.js"
    click Sidebar "https://github.com/homanp/langchain-ui/blob/main/lib/sidebar.js"
    click Markdown "https://github.com/homanp/langchain-ui/blob/main/lib/markdown.js"
    click Database "https://github.com/homanp/langchain-ui/blob/main/prisma/schema.prisma"
    click Migrations "https://github.com/homanp/langchain-ui/tree/main/prisma/migrations"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#000,stroke-width:1px
    classDef api fill:#d4edda,stroke:#000,stroke-width:1px
    classDef logic fill:#f0f8ff,stroke:#000,stroke-width:1px
    classDef persistence fill:#fff3cd,stroke:#000,stroke-width:1px
    classDef external fill:#e2c2ff,stroke:#000,stroke-width:1px
```
