# predixus/dynarag architecture

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

- Interactive diagram: https://gitdiagram.com/predixus/dynarag
- Repository: https://github.com/predixus/dynarag

## Overview

##### Project Type & Overall Purpose
- Project Type: A backend service implementing a RAG pipeline.
- Purpose: To provide fast and robust operations for adding text chunks, performing vector similarity (using PGVector in PostgreSQL), and leveraging LLM-based summarisation/response generation. Essentially, it is engineered for optimal performance and minimal overhead, ideal for inclusion in larger applications that require efficient text chunk handling and retrieval.

##### Key Components
a. Core Backend Service:
- Depicted by the main executable (e.g., “dynarag.go”) which wires together the service’s business logic.
- Initialization process where migrations are executed (see “db-init-scripts” and “migrations” directories).

b. Database Component:
- PostgreSQL with the PGVector extension configured via migrations.
- That the “internal/store” package manages database interactions—including schema definitions, SQL queries (via sqlc-generated code), and migrations.

c. Embedding/Feature Extraction Module:
- Use a module block labeled “Embedding Module” (internal/embed) which interacts with the Onnx runtime and Hugot library.
- That, on first inference, it downloads the necessary .onnx models from Huggingface and stores them locally under a models directory.

d. LLM Integration Module:
- “LLM Module” (internal/llm) as the component managing the interface to various external LLM providers (e.g., Groq or Ollama).
- That this module handles the generation/summarization aspect of the pipeline.

e. RAG Orchestration Layer:
- “RAG Module” (internal/rag) that serves as the final summarisation layer and application of system prompts, combining the outputs from the embedding/LLM modules.
- That it manipulates the text chunks before feeding the LLM.

f. Utility and Shared Modules:

g. Client Operations/Examples:
- Example clients (from the examples/ folder) demonstrating how operations like “Chunk”, “Similar”, “Query”, and “PurgeChunks” are invoked.

##### Relationships and Data Flow
- How user/client requests enter the main service which then calls the RAG orchestration layer.
- That migrations initialize/configure the database, setting up tables and extensions before any client operations commence.

##### Architectural Patterns & Design Principles
- That the project leverages a modular design:
- Each “internal” package (llm, rag, embed, store, utils) represents a clear separation of concerns.
- The project takes advantage of Go’s strengths, including concurrency and a single binary deployment.
- How the separation also helps in optimising latency (e.g., by pushing inference and database query latencies into the parts of the pipeline with the lowest round trip time).
- That the project uses configuration files like docker-compose.yml for container setups and a Makefile for build tasks.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Operations"
        clientExamples["Client Operations/Examples"]:::client
    end

    subgraph "Backend Service"
        mainService["Main Service"]:::service
        ragLayer["RAG Orchestration"]:::service
        ragPrompt["RAG Prompt"]:::module
        embedEngine["Embedding Engine (Onnx/Hugot)"]:::module
        llmInterface["LLM Interface"]:::module
        utils["Utilities"]:::module
        types["Types"]:::module
    end

    subgraph "Database Layer"
        database["Database (PostgreSQL + PGVector)"]:::database
        migrations["Migrations (migrations/)"]:::database
        dbInit["DB Initialization (db-init-scripts/)"]:::database
    end

    clientExamples -->|"sendsRequest"| mainService
    mainService -->|"orchestrates"| ragLayer
    ragLayer -->|"fetchesPrompt"| ragPrompt
    ragLayer -->|"callsEmbedding"| embedEngine
    ragLayer -->|"callsLLM"| llmInterface
    mainService -->|"dbOperations"| database
    ragLayer -->|"queriesDB"| database
    migrations -->|"configuresDB"| database
    dbInit -->|"initializesDB"| database
    mainService -.->|"usesUtilities"| utils
    mainService -.->|"usesTypes"| types

    click mainService "https://github.com/predixus/dynarag/blob/main/dynarag/dynarag.go"
    click database "https://github.com/predixus/dynarag/tree/main/internal/store"
    click migrations "https://github.com/predixus/dynarag/tree/main/migrations/"
    click dbInit "https://github.com/predixus/dynarag/tree/main/db-init-scripts/"
    click embedEngine "https://github.com/predixus/dynarag/blob/main/internal/embed/main.go"
    click llmInterface "https://github.com/predixus/dynarag/blob/main/internal/llm/llm.go"
    click ragLayer "https://github.com/predixus/dynarag/blob/main/internal/rag/rag.go"
    click ragPrompt "https://github.com/predixus/dynarag/blob/main/internal/rag/rag_prompt_with_initial_query.txt"
    click utils "https://github.com/predixus/dynarag/blob/main/internal/utils/hashing.go"
    click types "https://github.com/predixus/dynarag/blob/main/types/main.go"
    click clientExamples "https://github.com/predixus/dynarag/tree/main/examples/"

    classDef service fill:#cce5ff,stroke:#007bff,stroke-width:2px;
    classDef database fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef module fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef client fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
