# nishilfaldu/easy-rag architecture

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

- Interactive diagram: https://gitdiagram.com/nishilfaldu/easy-rag
- Repository: https://github.com/nishilfaldu/easy-rag

## Overview

##### Project type and purpose
- This is a full-stack web application built on Next.js (React) that lets users create and interact with chatbots.
- It uses Convex as a serverless backend (data modeling, authentication, functions), integrates with S3 for file storage, and external embedding/AI services for document ingestion.
- It also packages a distributable “chatbot-sdk” for embedding the chat widget in other sites.

##### File structure
- Top-level directories:
- app/ – Next.js “app router” pages, layouts, server- and client-components, split into marketing and main routes.
- src/components, src/app/_components, src/components/ui – reusable React UI.
- src/actions & src/lib – client-side wrappers for calling Convex, S3, and utility functions.
- convex/ – Convex serverless backend:
– schema.ts (data model), auth.config.ts (security), functions.ts, http.ts (API entry points), bots.ts, messages.ts, users.ts, documents.ts
– ingest/ – ingestion pipeline (db.ts, embed.ts, load.ts) calling external AI embedding services.
– _generated/ – Convex client & server code.
- public/ & dist/ – static assets and built chatbot-sdk for CDN inclusion.
- config files – next.config.mjs, tailwind.config.ts, webpack.config.js, tsconfig.json.

##### README for insights
- Standard Next.js boilerplate; nothing on architecture beyond noting Next.js.
- Runtime: “npm run dev” on localhost:3000.

##### Elements
- Blue for UI layer
- Green for serverless/backend layer
- Orange for external services/storage
- Annotations for the ingestion pipeline as a sub-component under Convex.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend"
        direction TB
        NextjsApp["Next.js App"]:::frontend
        Marketing["Marketing Routes\n(src/app/(marketing))"]:::frontend
        Main["Main Routes\n(src/app/(main)/(allroutes))"]:::frontend
        Shared["Shared App Components\n(src/app/_components)"]:::frontend
        UIcomp["Reusable UI Components\n(src/components/ui)"]:::frontend
        ConvexActions["Convex Actions\n(src/actions)"]:::frontend
        AuthLib["Auth Helpers\n(src/lib/auth.ts)"]:::frontend
        StorageLib["Storage Helpers\n(src/lib/storage.ts)"]:::frontend
        UtilsLib["Utils Helpers\n(src/lib/utils.ts)"]:::frontend
        S3Actions["S3 File Actions\n(src/actions/s3-actions.ts)"]:::frontend
        SDKSource["SDK Source\n(src/sdk/chatbot.tsx)"]:::frontend
        DistSDK["Chatbot SDK Dist\n(dist/chatbot-sdk.js)"]:::frontend
        PublicSDK["Chatbot SDK CDN\n(public/js/chatbot-sdk.js)"]:::frontend
    end

    %% Next.js Server
    NextjsApp --> NextjsServer["Next.js Server\n(SSR/API)"]:::backend
    Marketing --> NextjsServer
    Main --> NextjsServer
    Shared --> NextjsServer
    UIcomp --> NextjsServer

    ConvexActions --> NextjsServer
    AuthLib --> NextjsServer
    StorageLib --> NextjsServer
    UtilsLib --> NextjsServer

    S3Actions --> S3Bucket["S3 Bucket"]:::external

    SDKSource --> DistSDK --> PublicSDK
    PublicSDK --> ConvexHTTP

    %% Backend Layer - Convex Cloud
    subgraph "Convex Cloud"
        direction TB
        ConvexHTTP["Convex HTTP Endpoint\n(convex/http.ts)"]:::backend
        subgraph "Serverless Functions"
            direction TB
            AuthConfig["Auth Config\n(convex/auth.config.ts)"]:::backend
            UsersFunc["Users Functions\n(convex/users.ts)"]:::backend
            BotsFunc["Bots Functions\n(convex/bots.ts)"]:::backend
            MessagesFunc["Messages Functions\n(convex/messages.ts)"]:::backend
            DocumentsFunc["Documents Functions\n(convex/documents.ts)"]:::backend
            GeneralFunc["General Functions\n(convex/functions.ts)"]:::backend
            ServeSetup["Serve Setup\n(convex/serve.ts)"]:::backend
        end
        subgraph "Ingestion Pipeline"
            direction TB
            IngestDB["Ingest DB Setup\n(convex/ingest/db.ts)"]:::backend
            IngestEmbed["Embedding Service Calls\n(convex/ingest/embed.ts)"]:::backend
            IngestLoad["Data Loading\n(convex/ingest/load.ts)"]:::backend
        end
        GenClient["Convex Generated Client\n(convex/_generated)"]:::backend
        ConvexDB["Convex Database"]:::backend
    end

    %% External Services
    ExternalAI["AI Embedding API"]:::external

    %% Connections
    NextjsServer --> ConvexHTTP
    ConvexActions --> GenClient
    GenClient --> ConvexHTTP

    ConvexHTTP --> AuthConfig
    ConvexHTTP --> UsersFunc
    ConvexHTTP --> BotsFunc
    ConvexHTTP --> MessagesFunc
    ConvexHTTP --> DocumentsFunc
    ConvexHTTP --> GeneralFunc
    ConvexHTTP --> ServeSetup

    BotsFunc --> ConvexDB
    MessagesFunc --> ConvexDB
    DocumentsFunc --> ConvexDB
    UsersFunc --> ConvexDB
    GeneralFunc --> ConvexDB

    ConvexHTTP --> IngestDB
    IngestDB --> IngestEmbed
    IngestEmbed --> ExternalAI
    IngestEmbed --> ConvexDB
    IngestLoad --> ConvexDB

    %% Click Events
    click NextjsApp "https://github.com/nishilfaldu/easy-rag/tree/master/src/app"
    click Marketing "https://github.com/nishilfaldu/easy-rag/tree/master/src/app/(marketing)"
    click Main "https://github.com/nishilfaldu/easy-rag/tree/master/src/app/(main)/(allroutes)"
    click Shared "https://github.com/nishilfaldu/easy-rag/tree/master/src/app/_components"
    click UIcomp "https://github.com/nishilfaldu/easy-rag/tree/master/src/components/ui"
    click ConvexActions "https://github.com/nishilfaldu/easy-rag/tree/master/src/actions"
    click AuthLib "https://github.com/nishilfaldu/easy-rag/blob/master/src/lib/auth.ts"
    click StorageLib "https://github.com/nishilfaldu/easy-rag/blob/master/src/lib/storage.ts"
    click UtilsLib "https://github.com/nishilfaldu/easy-rag/blob/master/src/lib/utils.ts"
    click S3Actions "https://github.com/nishilfaldu/easy-rag/blob/master/src/actions/s3-actions.ts"
    click SDKSource "https://github.com/nishilfaldu/easy-rag/blob/master/src/sdk/chatbot.tsx"
    click DistSDK "https://github.com/nishilfaldu/easy-rag/blob/master/dist/chatbot-sdk.js"
    click PublicSDK "https://github.com/nishilfaldu/easy-rag/blob/master/public/js/chatbot-sdk.js"
    click ConvexHTTP "https://github.com/nishilfaldu/easy-rag/blob/master/convex/http.ts"
    click AuthConfig "https://github.com/nishilfaldu/easy-rag/blob/master/convex/auth.config.ts"
    click UsersFunc "https://github.com/nishilfaldu/easy-rag/blob/master/convex/users.ts"
    click BotsFunc "https://github.com/nishilfaldu/easy-rag/blob/master/convex/bots.ts"
    click MessagesFunc "https://github.com/nishilfaldu/easy-rag/blob/master/convex/messages.ts"
    click DocumentsFunc "https://github.com/nishilfaldu/easy-rag/blob/master/convex/documents.ts"
    click GeneralFunc "https://github.com/nishilfaldu/easy-rag/blob/master/convex/functions.ts"
    click ServeSetup "https://github.com/nishilfaldu/easy-rag/blob/master/convex/serve.ts"
    click IngestDB "https://github.com/nishilfaldu/easy-rag/blob/master/convex/ingest/db.ts"
    click IngestEmbed "https://github.com/nishilfaldu/easy-rag/blob/master/convex/ingest/embed.ts"
    click IngestLoad "https://github.com/nishilfaldu/easy-rag/blob/master/convex/ingest/load.ts"
    click GenClient "https://github.com/nishilfaldu/easy-rag/tree/master/convex/_generated"
    click ConvexDB "https://github.com/nishilfaldu/easy-rag/blob/master/convex/schema.ts"

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#1e88e5,color:#0d47a1;
    classDef backend fill:#c8e6c9,stroke:#43a047,color:#1b5e20;
    classDef external fill:#ffe0b2,stroke:#fb8c00,color:#e65100;
```
