# dodarshancode/rag_now architecture

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

- Interactive diagram: https://gitdiagram.com/dodarshancode/rag_now
- Repository: https://github.com/dodarshancode/rag_now

## Overview

##### Project type and purpose
- This is a production-ready, full-stack offline RAG (Retrieval-Augmented Generation) system.
- Purpose: take NL descriptions, retrieve relevant docs/examples, run ML inference on local GPU cluster, validate output DSL via py-osc2, and serve via a modern Web UI with metrics.

##### File structure
- Top level
- app.py – Flask API entry point
- config/openscenario_config.yaml – system settings (paths, GPU count, models)
- requirements.txt, setup.sh – install/runtime scripts
- src/core/ – modular pipeline components (config_manager, cache_manager, document_processor, retrieval_engine, vector_store, model_inference, osc_validator)
- src/openscenario_rag_system.py – orchestrator tying all core modules
- templates/index.html – single-page UI
- Implicit directories (created at runtime)
- data/{models,docs,examples,processed,embeddings,cache} – persistent storage
- logs/ – logs
- Optional services: Redis (production caching), Prometheus (metrics)

##### README for additional insights
- Offline-only: all models, docs, embeddings are on local disk
- Multi-GPU, high-performance: FAISS on GPU, mixed precision, model sharding
- Hybrid retrieval: dense (FAISS) + sparse (BM25)
- Multi-model inference engine with automatic switching
- Validation pipeline with py-osc2, retry logic
- Web UI + Flask API + Prometheus health/stats endpoints

##### Details without overthinking
- Break the monolith into its 8–10 logical components
- Both control flow (HTTP, function calls) and data flow (documents, embeddings, model weights)
- Don’t omit the caching and validation loops—they’re core to performance and correctness
- Configuration driving paths (config_manager reads YAML → sets model paths/GPU count)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend"
        direction TB
        UI["User Interface\n(Browser)"]:::frontend
    end

    %% API Layer
    subgraph "API Server"
        direction TB
        API["Flask API Server\n(app.py)"]:::api
    end

    %% Orchestration
    subgraph "Orchestrator"
        direction TB
        Orch["Core Orchestrator\n(src/openscenario_rag_system.py)"]:::orchestrator
        Config["Configuration Manager\n(config_manager.py\nopenscenario_config.yaml)"]:::config
    end

    %% GPU Cluster: ML Components
    subgraph "GPU Cluster"
        direction TB
        subgraph "Retrieval Layer"
            direction TB
            Sparse["Sparse Search (BM25)\n(src/core/retrieval_engine.py)"]:::ml
            Dense["Dense Vector Store (FAISS GPU)\n(src/core/vector_store.py)"]:::ml
        end
        Inference["Model Inference\n(src/core/model_inference.py)"]:::ml
        Validation["Validation\n(py-osc2)\n(src/core/osc_validator.py)"]:::ml
    end

    %% Caching & Storage
    subgraph "Data & Cache"
        direction TB
        Cache["Cache Manager\n(src/core/cache_manager.py)"]:::storage
        Storage["Local Data Storage\n(models/,docs/,examples/,embeddings/,cache/)"]:::storage
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Redis["Redis (optional)"]:::external
        Prom["Prometheus\n(metrics endpoint)"]:::external
    end

    %% Connections
    UI -->|"HTTP (generate)"| API
    API -->|"calls generate()"| Orch
    Orch -->|"load config"| Config
    Orch -->|"check/load"| Cache
    Orch -->|"retrieval request"| Sparse
    Orch -->|"retrieval request"| Dense
    Sparse -->|"docs/examples"| Orch
    Dense -->|"embeddings"| Orch
    Orch -->|"inference request"| Inference
    Inference -->|"raw DSL"| Orch
    Orch -->|"validate DSL"| Validation
    Validation -->|"valid/ retry"| Orch
    Orch -->|"cache results"| Cache
    Orch -->|"read/write"| Storage
    API -->|"read metrics"| Prom
    API -->|"optional cache"| Redis

    %% Click Events
    click UI "https://github.com/dodarshancode/rag_now/blob/develop/templates/index.html"
    click API "https://github.com/dodarshancode/rag_now/blob/develop/app.py"
    click Orch "https://github.com/dodarshancode/rag_now/blob/develop/src/openscenario_rag_system.py"
    click Config "https://github.com/dodarshancode/rag_now/blob/develop/src/core/config_manager.py"
    click Config "https://github.com/dodarshancode/rag_now/blob/develop/config/openscenario_config.yaml"
    click Sparse "https://github.com/dodarshancode/rag_now/blob/develop/src/core/retrieval_engine.py"
    click Dense "https://github.com/dodarshancode/rag_now/blob/develop/src/core/vector_store.py"
    click Inference "https://github.com/dodarshancode/rag_now/blob/develop/src/core/model_inference.py"
    click Validation "https://github.com/dodarshancode/rag_now/blob/develop/src/core/osc_validator.py"
    click Cache "https://github.com/dodarshancode/rag_now/blob/develop/src/core/cache_manager.py"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#004AAD,color:#004AAD
    classDef api fill:#DFF7DF,stroke:#1A7F00,color:#1A7F00
    classDef orchestrator fill:#E8F0D7,stroke:#6B8E23,color:#6B8E23
    classDef config fill:#FFF3CC,stroke:#D4A017,color:#D4A017
    classDef ml fill:#FFE4CC,stroke:#FF8C00,color:#A45A00
    classDef storage fill:#F2F2F2,stroke:#4D4D4D,color:#333333
    classDef external fill:#E5E5FF,stroke:#4B0082,color:#4B0082
```
