# profe168/rag-workshop-code architecture

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

- Interactive diagram: https://gitdiagram.com/profe168/rag-workshop-code
- Repository: https://github.com/profe168/rag-workshop-code

## Overview

##### Project Type and Purpose
- This is a Node.js/TypeScript sample project demonstrating a Retrieval-Augmented Generation (RAG) pipeline using the Mastra library.
- It provides scripts for document chunking, embedding, vector store operations, semantic search via agents, and evaluation of a RAG workflow.

##### High‑Level Architecture Analysis
- There is no web frontend. The system is a collection of command‑line scripts orchestrating a data ingestion and query pipeline.
- Top‑level modules:
- src/rag – document chunking, embedding, upserting, searching, reranking, generation
- src/mastra – agent and tool abstractions wrapping Mastra’s APIs
- src/bonus – code‑search examples and bonus documents
- src/eval – evaluation routines measuring RAG accuracy
- External dependencies/tools:
- OpenAI API (for embeddings and generation)
- PostgreSQL with pgvector extension (vector database)
- Environment variables in .env for API keys and DB connection
- Docker Compose for spinning up the database

##### Main Components
- Document Store (ファイルシステム): markdown and JSON documents in src/documents
- Chunker Module (04 strategies): character, recursive, JSON, markdown chunkers
- Embedding Module: calls OpenAI embedding APIs
- Vector Store (PostgreSQL + pgvector): stores and indexes vectors
- Retrieval Module: vector similarity search and reranking
- Agent Layer (Mastra):
- Basic‑search agent
- Query‑vector agent
- Tool abstraction for search operations
- Evaluation Module: scripts in src/eval measuring relevancy
- Bonus Code Search: specialized agent using code documents

##### Relationships and Data Flows
- Ingestion Flow:
Documents → Chunker → Embedder → Vector Store
(use upsert.ts and 06-vector-upserting.ts)
- Query Flow:
User Query → Agent (Mastra) → Vector Store Search → (Optional) Reranker → Response Generation
(see 07-vector-search.ts, 08-vector-reranking.ts, 09‑10 agent examples)
- Evaluation Flow:
Sample queries + ground truth → src/eval scripts → Metrics
- Bonus Flow:
Code base documents → Bonus agent → Code usage results

##### Architectural Patterns and Principles
- Modular design: each pipeline step is a separate script/module
- Clear separation of concerns: chunking, embedding, storage, retrieval, evaluation
- Pluggable agents/tools using Mastra abstractions
- Externalized configuration via .env for API keys and DB connection
- Use of containerized DB for reproducibility (docker-compose.yml)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Ingestion Pipeline
    subgraph "Ingestion Pipeline"
        Documents["Document Store\n(src/documents)"]:::orange
        subgraph Chunking["Chunker Module"]
            Character["01-Character Chunking"]:::orange
            Recursive["02-Recursive Chunking"]:::orange
            JSONCh["03-JSON Chunking"]:::orange
            Markdown["04-Markdown Chunking"]:::orange
        end
        Embedder["05-Embedding"]:::orange
        UpsertHelper["upsert.ts\n(Upsert Helper)"]:::orange
        VectorUpsert["06-Vector Upserting"]:::orange
    end

    DockerCompose["Docker Compose\n(PostgreSQL + pgvector)"]:::green
    Env[".env.example"]:::gray
    VectorDB["PostgreSQL + pgvector\n(Vector DB)"]:::green
    OpenAI["OpenAI API"]:::cloud

    Documents --> Character --> Recursive --> JSONCh --> Markdown --> Embedder --> UpsertHelper --> VectorUpsert --> VectorDB
    DockerCompose --> VectorDB
    Env --> VectorDB
    Embedder --> OpenAI

    %% Query Pipeline
    subgraph "Query Pipeline"
        User["User Query"]:::external
        subgraph Agents["Agent Layer (Mastra)"]
            MastraEntry["src/mastra/index.ts"]:::blue
            BasicAgent["Basic-Search Agent"]:::blue
            QueryAgent["Query-Vector Agent"]:::blue
            subgraph Tools["Tool Abstractions"]
                ToolIndex["tools/index.ts"]:::blue
                BasicTool["basic-search.ts"]:::blue
                QueryTool["query-vector.ts"]:::blue
            end
        end
        BasicUsage["09-Basic Search Usage"]:::blue
        QueryUsage["10-Query-Vector Usage"]:::blue
        VectorSearch["07-Vector Search"]:::green
        Reranker["08-Vector Reranking"]:::green
    end

    User --> MastraEntry
    MastraEntry --> BasicAgent
    MastraEntry --> QueryAgent
    BasicAgent --> BasicUsage
    QueryAgent --> QueryUsage
    BasicUsage --> VectorSearch
    QueryUsage --> VectorSearch
    VectorSearch --> VectorDB
    VectorDB --> Reranker
    Reranker --> MastraEntry
    MastraEntry --> OpenAI

    %% Evaluation Suite
    subgraph "Evaluation Suite"
        SampleQueries["Sample Queries + Ground Truth"]:::external
        EvalRelMetric["Relevancy Eval w/ Metric"]:::gray
        EvalRel["Relevancy Eval"]:::gray
        MockEval["Mock Evaluation"]:::gray
        SampleQueries --> EvalRelMetric
        SampleQueries --> EvalRel
        SampleQueries --> MockEval
    end

    %% Bonus Examples
    subgraph "Bonus Examples"
        BonusDocs["Bonus Documents\n(src/bonus/documents)"]:::gray
        CodeUsage["01-Find Code Usage"]:::gray
        BonusAgent["Bonus Agent"]:::gray
        BonusTool["Bonus Tool"]:::gray
        BonusDocs --> CodeUsage --> BonusAgent --> BonusTool --> VectorDB
    end

    %% CLI & Config
    subgraph "CLI & Project Config"
        Package["package.json"]:::gray
        TSConfig["tsconfig.json"]:::gray
        TestConfig["vitest.config.ts"]:::gray
    end

    %% Click Events
    click Documents "https://github.com/profe168/rag-workshop-code/tree/main/src/documents"
    click Character "https://github.com/profe168/rag-workshop-code/blob/main/src/rag/chunking/01-character-chunking.ts"
    click Recursive "https://github.com/profe168/rag-workshop-code/blob/main/src/rag/chunking/02-recursive-chunking.ts"
    click JSONCh "https://github.com/profe168/rag-workshop-code/blob/main/src/rag/chunking/03-json-chunking.ts"
    click Markdown "https://github.com/profe168/rag-workshop-code/blob/main/src/rag/chunking/04-markdown-chunking.ts"
    click Embedder "https://github.com/profe168/rag-workshop-code/blob/main/src/rag/embedding/05-embedding.ts"
    click UpsertHelper "https://github.com/profe168/rag-workshop-code/blob/main/src/rag/embedding/upsert.ts"
    click VectorUpsert "https://github.com/profe168/rag-workshop-code/blob/main/src/rag/embedding/06-vector-upserting.ts"
    click DockerCompose "https://github.com/profe168/rag-workshop-code/blob/main/docker-compose.yml"
    click Env "https://github.com/profe168/rag-workshop-code/blob/main/.env.example"
    click MastraEntry "https://github.com/profe168/rag-workshop-code/blob/main/src/mastra/index.ts"
    click BasicAgent "https://github.com/profe168/rag-workshop-code/blob/main/src/mastra/agents/basic-agent.ts"
    click QueryAgent "https://github.com/profe168/rag-workshop-code/blob/main/src/mastra/agents/query-vector-agent.ts"
    click ToolIndex "https://github.com/profe168/rag-workshop-code/blob/main/src/mastra/tools/index.ts"
    click BasicTool "https://github.com/profe168/rag-workshop-code/blob/main/src/mastra/tools/basic-search.ts"
    click QueryTool "https://github.com/profe168/rag-workshop-code/blob/main/src/mastra/tools/query-vector.ts"
    click BasicUsage "https://github.com/profe168/rag-workshop-code/blob/main/src/rag/generate/09-basic-search-usage.ts"
    click QueryUsage "https://github.com/profe168/rag-workshop-code/blob/main/src/rag/generate/10-query-vector-usage.ts"
    click VectorSearch "https://github.com/profe168/rag-workshop-code/blob/main/src/rag/retrieval/07-vector-search.ts"
    click Reranker "https://github.com/profe168/rag-workshop-code/blob/main/src/rag/retrieval/08-vector-reranking.ts"
    click EvalRelMetric "https://github.com/profe168/rag-workshop-code/blob/main/src/eval/eval-context-relevancy-with-metric.ts"
    click EvalRel "https://github.com/profe168/rag-workshop-code/blob/main/src/eval/eval-context-relevancy.ts"
    click MockEval "https://github.com/profe168/rag-workshop-code/blob/main/src/eval/mock-eval.ts"
    click BonusDocs "https://github.com/profe168/rag-workshop-code/tree/main/src/bonus/documents"
    click CodeUsage "https://github.com/profe168/rag-workshop-code/blob/main/src/bonus/01-find-code-usage.ts"
    click BonusAgent "https://github.com/profe168/rag-workshop-code/blob/main/src/bonus/agent.ts"
    click BonusTool "https://github.com/profe168/rag-workshop-code/blob/main/src/bonus/tool.ts"
    click Package "https://github.com/profe168/rag-workshop-code/blob/main/package.json"
    click TSConfig "https://github.com/profe168/rag-workshop-code/blob/main/tsconfig.json"
    click TestConfig "https://github.com/profe168/rag-workshop-code/blob/main/vitest.config.ts"

    %% Styles
    classDef orange fill:#FFA500,stroke:#333,stroke-width:1px
    classDef green fill:#90EE90,stroke:#333,stroke-width:1px
    classDef blue fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef gray fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef cloud fill:#F0E68C,stroke:#333,stroke-width:1px
    classDef external fill:#FFFFFF,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
