# oscxrojas/rag_environment architecture

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

- Interactive diagram: https://gitdiagram.com/oscxrojas/rag_environment
- Repository: https://github.com/oscxrojas/rag_environment

## Overview

##### Project Type and Purpose
- This is not a monolithic application but a “playground” environment composed of multiple Docker‐based microservices to support Retrieval-Augmented Generation (RAG) experimentation.
- Purpose: spin up LLM inference (Ollama), vector storage (Qdrant), relational/analytics stores (Postgres, ClickHouse), object store (MinIO), caching (Redis), event tracking (Langfuse worker + web UI), and Jupyter notebooks for interactive demos—all via Docker Compose.

##### File Structure
- .env-template: holds environment variables for API keys, model names, ports.
- docker-compose.yml: defines the nine services and how they network/connect.
- bootstrap.sh: orchestrates build, cleanup, startup, and model downloading via volumes/ollama/model-downloader.sh.
- requirements.txt: Python deps for Jupyter environment.
- volumes/jupyter/demos: sample notebooks that interact with the services.
- volumes/ollama: persistent store for downloaded Ollama models.

##### README for Insights
- Outlines startup sequence: Docker removes orphaned containers, builds images, brings up services in order.
- Lists service URLs and ports.
- Emphasizes environment customization via .env.
- Mentions “Langfuse” for event tracking and the model-change workflow.

- Client Tier
- Web Browser → Jupyter UI (port 8888)
- Web Browser → Langfuse Web UI (port 3000)
- Compute/Service Tier (hexagons or rectangles)
- Jupyter Notebook Server (Python kernel, uses requirements.txt)
- Ollama LLM Server
- Langfuse Worker
- Langfuse Web UI
- Qdrant (vector DB)
- Postgres (metadata store)
- ClickHouse (analytics store)
- MinIO (S3-compatible object store)
- Redis (caching or message broker)
- Infrastructure Tier
- Docker Host / Docker Compose Network
- Shared Volumes (for model storage and demo notebooks)
- Jupyter → Ollama: POST requests to /v1/chat/completions for model inference
- Jupyter → Qdrant: upsert/query embeddings via Qdrant HTTP API
- Jupyter → MinIO: PUT/GET for document storage (if demos use it)
- Jupyter → Redis: caching intermediate values (optional)
- Langfuse Worker → Postgres/ClickHouse: write event logs and analytics data
- Langfuse Web UI → ClickHouse/Postgres: read for dashboards
- All containers communicate over the Docker Compose network
- Shared volumes mount at host → containers for persistent data
c. Architectural Patterns & Principles
- Microservices: each major function is a separate container
- Clear separation: UI (Jupyter + Langfuse Web), compute (Ollama, Worker), storage (DBs, object store)
- Environment-as-code: all services and dependencies are declared in docker-compose.yml + .env
- Event-driven logging/analytics: Langfuse captures every interaction for observability
d. Key Technologies & Frameworks
- Docker + Docker Compose for orchestration
- Python/Jupyter for interactive experimentation
- Ollama for local LLM serving
- Qdrant, Postgres, ClickHouse, Redis, MinIO for data persistence
- Langfuse for event tracking and UI dashboards

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Tier
    subgraph "Client Tier"
        direction TB
        Browser["Web Browser"]:::client
        Browser -->|HTTP| JupyterUI["Jupyter UI<br/>(port 8888)"]:::client
        Browser -->|HTTP| LFWebUI["Langfuse Web UI<br/>(port 3000)"]:::client
    end

    %% Infrastructure & Configuration
    subgraph "Infrastructure & Configuration"
        direction TB
        Env[".env-template"]:::doc
        Compose["docker-compose.yml"]:::doc
        Bootstrap["bootstrap.sh"]:::doc
        README["README.md"]:::doc
        VolumesJupyter["volumes/jupyter"]:::infra
        VolumesDemos["volumes/jupyter/demos"]:::infra
        BasicDemo["basic.ipynb"]:::doc
        ToolsDemo["ollama_tools_langfuse.ipynb"]:::doc
        VolumesOllama["volumes/ollama"]:::infra
        ModelDL["model-downloader.sh"]:::doc
    end

    %% Docker Network Boundary
    subgraph "Docker Compose Network"
        direction TB
        %% Compute/Service Tier
        Jupyter["Jupyter Notebook Server<br/>(port 8888)"]:::compute
        Ollama["Ollama LLM Server"]:::compute
        LFWorker["Langfuse Worker"]:::obs
        LFWeb["Langfuse Web UI"]:::obs

        %% Data Tier
        Qdrant["Qdrant<br/>(port 6333)"]:::data
        Postgres["Postgres<br/>(port 5432)"]:::data
        ClickHouse["ClickHouse<br/>(port 8123)"]:::data
        MinIO["MinIO<br/>(port 9000)"]:::data
        Redis["Redis<br/>(port 6379)"]:::data

        %% Shared Volumes for models and notebooks
        VolJup["/host/volumes/jupyter"]:::infra
        VolOll["/host/volumes/ollama"]:::infra
    end

    %% Data Flows
    Jupyter -->|"/v1/chat/completions"| Ollama
    Jupyter -->|HTTP API| Qdrant
    Jupyter -->|PUT/GET| MinIO
    Jupyter -->|GET/SET| Redis
    LFWorker -->|writes events| Postgres
    LFWorker -->|writes analytics| ClickHouse
    LFWeb -->|reads| Postgres
    LFWeb -->|reads| ClickHouse

    %% Volumes & Bootstrap
    Bootstrap -.-> VolOll
    Bootstrap -.-> VolumesJupyter
    Bootstrap -->|initializes| Ollama
    Bootstrap -->|initializes| Jupyter

    %% Clients to Docker Network
    JupyterUI -->|proxied| Jupyter
    LFWebUI -->|proxied| LFWeb

    %% Shared Volumes mounts
    VolJup --> Jupyter
    VolOll --> Ollama

    %% Config & Orchestration
    Env --> Compose
    Compose -->|defines services| Jupyter
    Compose -->|defines services| Ollama
    Compose -->|defines| Qdrant
    Compose -->|defines| Postgres
    Compose -->|defines| ClickHouse
    Compose -->|defines| MinIO
    Compose -->|defines| Redis
    Compose -->|defines| LFWorker
    Compose -->|defines| LFWeb

    %% Legend
    subgraph "Legend"
        direction TB
        C1["Client Tier"]:::client
        C2["Compute/Service Tier"]:::compute
        D1["Data Tier"]:::data
        O1["Observability"]:::obs
        I1["Infrastructure"]:::infra
        Doc["Documentation & Config"]:::doc
    end

    %% Click Events
    click Env "https://github.com/oscxrojas/rag_environment/blob/master/.env-template"
    click Compose "https://github.com/oscxrojas/rag_environment/blob/master/docker-compose.yml"
    click Bootstrap "https://github.com/oscxrojas/rag_environment/blob/master/bootstrap.sh"
    click README "https://github.com/oscxrojas/rag_environment/blob/master/README.md"
    click VolumesJupyter "https://github.com/oscxrojas/rag_environment/tree/master/volumes/jupyter"
    click BasicDemo "https://github.com/oscxrojas/rag_environment/blob/master/volumes/jupyter/demos/basic.ipynb"
    click ToolsDemo "https://github.com/oscxrojas/rag_environment/blob/master/volumes/jupyter/demos/ollama_tools_langfuse.ipynb"
    click VolumesOllama "https://github.com/oscxrojas/rag_environment/tree/master/volumes/ollama"
    click ModelDL "https://github.com/oscxrojas/rag_environment/blob/master/volumes/ollama/model-downloader.sh"
    click Jupyter "https://github.com/oscxrojas/rag_environment/blob/master/requirements.txt"

    %% Styles
    classDef client fill:#D0E8FF,stroke:#4A90E2,color:#004080;
    classDef compute fill:#DFF2D8,stroke:#4BB543,color:#2E5E00;
    classDef data fill:#FFE5CC,stroke:#FF8C1A,color:#663C00;
    classDef infra fill:#F0F0F0,stroke:#A0A0A0,color:#404040;
    classDef obs fill:#F3E5FF,stroke:#B366FF,color:#4B0082;
    classDef doc fill:#F7F7F7,stroke:#CCCCCC,color:#333333;
```
