# auto-bits/pgvectorscale-rag-solution-example architecture

> Architecture diagram of the GitHub repository auto-bits/pgvectorscale-rag-solution-example, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/auto-bits/pgvectorscale-rag-solution-example
- Repository: https://github.com/auto-bits/pgvectorscale-rag-solution-example

## Overview

##### Main Components

a) External Services Layer:
- OpenAI API (for embeddings and LLM)

b) Application Layer:
- Vector Insertion Service
- Similarity Search Service
- LLM Factory Service
- Synthesizer Service

c) Data Layer:
- PostgreSQL with Pgvectorscale
- Vector Store
- Raw Data Storage (CSV files)

##### Component Relationships

a) Data Ingestion Flow:
**Raw Data (CSV) → Vector Insertion Service → OpenAI Embedding API → PostgreSQL/Pgvectorscale**

b) Query Flow:
**User Query → Similarity Search Service → OpenAI Embedding API → PostgreSQL/Pgvectorscale → LLM Factory → Synthesizer → Response**

##### Key Technical Elements to Highlight

- Blue: Core application services
- Green: Database components
- Purple: External API services
- Yellow: Data storage
- Gray: Configuration components

##### Architectural Patterns to Emphasize

a) Service Layer Pattern:
- Clear separation between services in app/services/
- Factory pattern used in llm_factory.py
- Demonstrate the separation of concerns between vector storage and search operations

b) Configuration Management:
- Settings.py configuration component
- Environment variable handling (example.env)

##### Specific Implementation Details

- Vector Processing Pipeline
- Text chunking
- Embedding generation
- Vector storage
- Search Pipeline
- Query embedding
- Similarity search
- Result synthesis

##### Infrastructure Components

A Docker container boundary showing:
- PostgreSQL with Pgvectorscale
- Python application environment
- Network connections

##### Storage Layer

Important Details to Include:
- Database connection parameters
- API integration points
- Vector indexing mechanisms
- Data flow directions
- Component dependencies

Remember to emphasize the PostgreSQL/Pgvectorscale integration as it's a key differentiator of this system, showing how it handles both vector and relational data in a single database system.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles and Classes
    classDef external fill:#C586C0,stroke:#333,stroke-width:2px
    classDef service fill:#569CD6,stroke:#333,stroke-width:2px
    classDef database fill:#4EC9B0,stroke:#333,stroke-width:2px
    classDef storage fill:#DCDCAA,stroke:#333,stroke-width:2px
    classDef config fill:#808080,stroke:#333,stroke-width:2px

    %% External Services Layer
    OpenAI["OpenAI API\n(Embeddings & LLM)"]:::external

    %% Application Services Layer
    VectorInsertion["Vector Insertion Service"]:::service
    SimilaritySearch["Similarity Search Service"]:::service
    LLMFactory["LLM Factory Service"]:::service
    Synthesizer["Synthesizer Service"]:::service

    %% Data Processing Layer
    VectorStore["Vector Store"]:::database
    PostgreSQL[("PostgreSQL with\nPgvectorscale")]:::database
    RawData["Raw Data (CSV)"]:::storage
    Settings["Configuration Settings"]:::config
    EnvConfig["Environment Config"]:::config
    DockerConfig["Docker Configuration"]:::config

    %% Relationships
    RawData --> VectorInsertion
    VectorInsertion --> OpenAI
    OpenAI --> VectorInsertion
    VectorInsertion --> PostgreSQL
    
    SimilaritySearch --> OpenAI
    OpenAI --> SimilaritySearch
    SimilaritySearch --> PostgreSQL
    PostgreSQL --> SimilaritySearch
    
    SimilaritySearch --> LLMFactory
    LLMFactory --> OpenAI
    LLMFactory --> Synthesizer
    
    VectorStore --> PostgreSQL
    Settings --> VectorStore
    EnvConfig --> Settings
    DockerConfig --> PostgreSQL

    %% Technical Notes
    subgraph Notes
        direction TB
        Note1["Vector Dimensions:\nOpenAI Embeddings"]
        Note2["Cosine Similarity\nMeasurement"]
        Note3["ANN Search Indexes\n(timescale_vector_index)"]
    end

    %% Click Events
    click VectorInsertion "https://github.com/Auto-Bits/pgvectorscale-rag-solution-example/blob/main/app/insert_vectors.py"
    click SimilaritySearch "https://github.com/Auto-Bits/pgvectorscale-rag-solution-example/blob/main/app/similarity_search.py"
    click LLMFactory "https://github.com/Auto-Bits/pgvectorscale-rag-solution-example/blob/main/app/services/llm_factory.py"
    click Synthesizer "https://github.com/Auto-Bits/pgvectorscale-rag-solution-example/blob/main/app/services/synthesizer.py"
    click VectorStore "https://github.com/Auto-Bits/pgvectorscale-rag-solution-example/blob/main/app/database/vector_store.py"
    click RawData "https://github.com/Auto-Bits/pgvectorscale-rag-solution-example/blob/main/data/faq_dataset.csv"
    click Settings "https://github.com/Auto-Bits/pgvectorscale-rag-solution-example/blob/main/app/config/settings.py"
    click EnvConfig "https://github.com/Auto-Bits/pgvectorscale-rag-solution-example/blob/main/example.env"
    click DockerConfig "https://github.com/Auto-Bits/pgvectorscale-rag-solution-example/blob/main/docker-compose.yml"

    %% Legend
    subgraph Legend
        direction TB
        L1["External Services"]:::external
        L2["Application Services"]:::service
        L3["Database Components"]:::database
        L4["Data Storage"]:::storage
        L5["Configuration"]:::config
    end
```
