# lamnhan/rag-demo architecture

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

- Interactive diagram: https://gitdiagram.com/lamnhan/rag-demo
- Repository: https://github.com/lamnhan/rag-demo

## Overview

##### Project type and purpose
- This is a full-stack Retrieval-Augmented Generation (RAG) demo web application.
- The README says: “A RAG system using SurrealDB, tRPC and Lit.”
- Purpose: ingest raw JSON samples into SurrealDB, index or query them via tRPC API, augment user prompts with retrieved data, and render an interactive chat UI in the browser using Lit components.

##### File structure
- Top-level directories:
- client/ – the front-end UI built with Lit (TypeScript, CSS, Vite).
- server/ – the back-end logic using tRPC, SurrealDB client, OpenAI calls.
- database/ – raw JSON samples + SurrealDB schema setup.
- scripts/ – CLI commands (download, insert, query, setup) to manage data ingestion and DB schema.
- shared/ – TypeScript types and transformer logic reused by client, server, and scripts.
- Config & build files: tsconfig.json (root, client, server), vite.config.ts, package.json, pnpm-lock.yaml.
- server/procedures/ and server/router.ts implement business logic and tRPC routing.
- scripts/commands/*.ts sequence through data ingestion and testing workflows.

##### README for additional insights
- Retrieve relevant JSON snippets from SurrealDB.
- Possibly transform them (shared/transformer.ts) into prompt context.
- Send combined prompt to OpenAI via server/openai.ts.
- Return generated responses to the client through tRPC endpoints.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        CI["client/index.ts"]:::frontend
        CIX["client/index.css"]:::frontend
        CC["client/config.ts"]:::frontend
        CTRPC["client/trpc.ts"]:::frontend
        CHATIN["client/components/chat-input.ts"]:::frontend
        MSGITEM["client/components/message-item.ts"]:::frontend
        RESMSG["client/components/result-message.ts"]:::frontend
        SIMTXT["client/components/simulated-text.ts"]:::frontend
        SIMTXTE["client/components/simulated-text-with-extra.ts"]:::frontend
        THINK["client/components/thinking-message.ts"]:::frontend
        ERRMSG["client/components/error-message.ts"]:::frontend
    end

    %% API & Business Logic Layer
    subgraph "API & Business Logic"
        direction TB
        STRPC["server/trpc.ts"]:::backend
        ROUTER["server/router.ts"]:::backend
        SCONFIG["server/config.ts"]:::backend
        SDB["server/surreal.ts"]:::backend
        OPENAI["server/openai.ts"]:::backend
        PROC["server/procedures/product.ts"]:::backend
    end

    %% Shared Layer
    subgraph "Shared"
        direction TB
        STYPES["shared/types.ts"]:::shared
        STRANS["shared/transformer.ts"]:::shared
    end

    %% Data Layer
    subgraph "Database Assets"
        direction TB
        SCHEMA["database/schema/setup.surql"]:::backend
        RAW["database/raw-samples/"]:::backend
    end

    %% Ingestion Scripts
    subgraph "CLI Scripts (Offline)" 
        direction TB
        SIDX["scripts/index.ts"]:::ingestion
        SCONF["scripts/config.ts"]:::ingestion
        SETUP["scripts/commands/setup.ts"]:::ingestion
        DOWNLOAD["scripts/commands/download.ts"]:::ingestion
        INSERT["scripts/commands/insert.ts"]:::ingestion
        QUERY["scripts/commands/query.ts"]:::ingestion
    end

    %% External Services
    SurrealDB["SurrealDB Instance"]:::external
    OpenAIAPI["OpenAI API"]:::external

    %% Connections
    CHATIN -->|"calls"| CTRPC
    CTRPC -->|"HTTP/RPC"| STRPC
    STRPC -->|"routes to"| ROUTER
    ROUTER -->|"invokes"| PROC
    PROC -->|"DB QUERY"| SDB
    SDB -->|"connects to"| SurrealDB
    PROC -->|"transform via"| STRANS
    STRANS -->|"types from"| STYPES
    STRANS -->|"to prompt"| OPENAI
    OPENAI -->|"calls"| OpenAIAPI
    OPENAI -->|"returns response"| STRPC
    STRPC -->|"response"| CTRPC
    CTRPC -->|"renders"| RESMSG

    %% Ingestion Flow (dashed)
    DOWNLOAD -.->|"fetch samples"| RAW
    SETUP -.->|"apply schema"| SCHEMA
    INSERT -.->|"load data"| SurrealDB
    QUERY -.->|"test queries"| SurrealDB
    SIDX --> SCONF

    %% Click Events
    click CI "https://github.com/lamnhan/rag-demo/blob/main/client/index.ts"
    click CIX "https://github.com/lamnhan/rag-demo/blob/main/client/index.css"
    click CC "https://github.com/lamnhan/rag-demo/blob/main/client/config.ts"
    click CTRPC "https://github.com/lamnhan/rag-demo/blob/main/client/trpc.ts"
    click CHATIN "https://github.com/lamnhan/rag-demo/blob/main/client/components/chat-input.ts"
    click MSGITEM "https://github.com/lamnhan/rag-demo/blob/main/client/components/message-item.ts"
    click RESMSG "https://github.com/lamnhan/rag-demo/blob/main/client/components/result-message.ts"
    click SIMTXT "https://github.com/lamnhan/rag-demo/blob/main/client/components/simulated-text.ts"
    click SIMTXTE "https://github.com/lamnhan/rag-demo/blob/main/client/components/simulated-text-with-extra.ts"
    click THINK "https://github.com/lamnhan/rag-demo/blob/main/client/components/thinking-message.ts"
    click ERRMSG "https://github.com/lamnhan/rag-demo/blob/main/client/components/error-message.ts"
    click STRPC "https://github.com/lamnhan/rag-demo/blob/main/server/trpc.ts"
    click ROUTER "https://github.com/lamnhan/rag-demo/blob/main/server/router.ts"
    click SCONFIG "https://github.com/lamnhan/rag-demo/blob/main/server/config.ts"
    click SDB "https://github.com/lamnhan/rag-demo/blob/main/server/surreal.ts"
    click OPENAI "https://github.com/lamnhan/rag-demo/blob/main/server/openai.ts"
    click PROC "https://github.com/lamnhan/rag-demo/blob/main/server/procedures/product.ts"
    click SCHEMA "https://github.com/lamnhan/rag-demo/blob/main/database/schema/setup.surql"
    click RAW "https://github.com/lamnhan/rag-demo/tree/main/database/raw-samples/"
    click SIDX "https://github.com/lamnhan/rag-demo/blob/main/scripts/index.ts"
    click SCONF "https://github.com/lamnhan/rag-demo/blob/main/scripts/config.ts"
    click SETUP "https://github.com/lamnhan/rag-demo/blob/main/scripts/commands/setup.ts"
    click DOWNLOAD "https://github.com/lamnhan/rag-demo/blob/main/scripts/commands/download.ts"
    click INSERT "https://github.com/lamnhan/rag-demo/blob/main/scripts/commands/insert.ts"
    click QUERY "https://github.com/lamnhan/rag-demo/blob/main/scripts/commands/query.ts"
    click STYPES "https://github.com/lamnhan/rag-demo/blob/main/shared/types.ts"
    click STRANS "https://github.com/lamnhan/rag-demo/blob/main/shared/transformer.ts"

    %% Styles
    classDef frontend fill:#CCE5FF,stroke:#007BFF
    classDef backend fill:#D4EDDA,stroke:#28A745
    classDef external fill:#FFF3CD,stroke:#FFC107
    classDef ingestion fill:#E2E3E5,stroke:#6C757D,stroke-dasharray:5 5
    classDef shared fill:#F0F0F0,stroke:#343A40
```
