# awcodify/ragnarock architecture

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

- Interactive diagram: https://gitdiagram.com/awcodify/ragnarock
- Repository: https://github.com/awcodify/ragnarock

## Overview

##### Project’s Purpose and Type
- This project is a full-stack analytical service that performs real-time infrastructure analysis using a Retrieval Augmented Generation (RAG) approach.
- It collects Prometheus metrics, performs vector similarity search to find historical patterns, leverages an analysis service that interacts with an LLM via TensorZero, and finally exposes an API using FastAPI to deliver structured JSON responses.

##### Main Components
- Data Collection:
- The file src/data/prometheus_client.py likely implements the logic of fetching metrics.
- RAG Service and Data Processing:
- Components where metrics are processed include:
- Collect Metrics (collector logic)
- Vector Store (implemented in src/data/vector_store.py, potentially with Qdrant integration)
- Analysis (core logic in src/services/analysis.py)
- Interaction with TensorZero (located in the tensorzero/ directory) which acts as a gateway to various LLM providers.
- LLM Providers:
- API Layer:
- The REST API built with FastAPI (in src/api/main.py) exposes endpoints like /analyze.
- This layer handles incoming HTTP requests and returns JSON responses based on the analysis.

##### Architectural Patterns and Technologies
- Separation of Concerns: The clear split between data collection (Prometheus), processing components (vector store search and analysis), and API delivery.
- Microservice Elements: Although this is a single project, there’s modularity between services such as analysis, health check (src/services/health.py), and LLM interactions.
- Async Operations: FastAPI is async-friendly.
- Integration with External Tools: Docker, docker-compose, and Prometheus; plus the integration with tensorzero for LLM provider abstraction.

a. A high-level layout:
b. Main Components to Include:
- Prometheus (Data Source)
- Data Collection Module (fetching metrics)
- Historical Data Search module (searching in vector store)
- Vector Store (e.g., Qdrant, as inferred by tests and service naming)
- Analysis Service (computing similar patterns and producing analysis)
- TensorZero Gateway (to interface with the LLM providers)
- LLM Providers (Claude, Ollama, and possibly others)
- API endpoints served by FastAPI (for the REST API)
- Flow from "Collect Metrics" to "Search Historical".
- Then a loop between "Search Historical" and "Vector Store" (for storing new metrics).
- From "Vector Store" to "Analysis" which then leads into the "TensorZero Gateway".
- From TensorZero, data flows to the various "LLM Providers", whose outputs feed back into the analysis.
- Finally, the aggregated processed data is exposed via the "API Endpoint" to the client.
- Use clear labels for each component.
- Rectangles for modules (e.g., Data Collector, Analysis Service)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Data Source
    P["Prometheus (Data Source)"]:::dataSource

    %% Data Collection Layer
    subgraph "Data Collection"
        CM["Collect Metrics"]:::module
    end

    %% RAG Processing Layer
    subgraph "RAG Processing"
        HS["Historical Search"]:::module
        VS["Vector Store"]:::vector
        AS["Analysis Service"]:::analysis
        TG["TensorZero Gateway"]:::llm
        LP["LLM Providers"]:::llm
    end

    %% API Layer
    subgraph "API Layer"
        API["REST API"]:::api
        HC["Health Check"]:::module
    end

    %% Data Flow
    P -->|"MetricsData"| CM
    CM -->|"SearchHistorical"| HS
    HS <-->|"DataSync"| VS
    VS -->|"ProvideData"| AS
    AS -->|"AnalysisRequest"| TG
    TG -->|"LLMQueryResponse"| LP
    AS -->|"AggregatedResponse"| API
    API -->|"HealthCheck"| HC

    %% Click Events
    click CM "https://github.com/awcodify/ragnarock/blob/main/src/data/prometheus_client.py"
    click VS "https://github.com/awcodify/ragnarock/blob/main/src/data/vector_store.py"
    click AS "https://github.com/awcodify/ragnarock/blob/main/src/services/analysis.py"
    click TG "https://github.com/awcodify/ragnarock/tree/main/tensorzero/"
    click LP "https://github.com/awcodify/ragnarock/blob/main/src/services/llm.py"
    click API "https://github.com/awcodify/ragnarock/blob/main/src/api/main.py"
    click HC "https://github.com/awcodify/ragnarock/blob/main/src/services/health.py"

    %% Styles
    classDef dataSource fill:#e3f2fd,stroke:#2196f3,stroke-width:2px;
    classDef module fill:#fce4ec,stroke:#e91e63,stroke-width:2px;
    classDef vector fill:#e8f5e9,stroke:#4caf50,stroke-width:2px;
    classDef analysis fill:#fff3e0,stroke:#ff9800,stroke-width:2px;
    classDef llm fill:#ede7f6,stroke:#673ab7,stroke-width:2px;
    classDef api fill:#e0f7fa,stroke:#00acc1,stroke-width:2px;
```
