# kitadmin01/farm-financial-rag architecture

> Architecture diagram of the GitHub repository kitadmin01/farm-financial-rag, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kitadmin01/farm-financial-rag
- Repository: https://github.com/kitadmin01/farm-financial-rag

## Overview

##### Project Type and Purpose
- This is a full-stack Retrieval-Augmented Generation (RAG) application for farm financial data.
- Users interact via CLI, REST API (FastAPI + static HTML), or an interactive demo.
- The core logic uses an OpenAI LLM to translate natural-language questions into SQL, executes them against an embedded SQLite database, and returns contextual insights.

##### File Structure
Top-level
- README.md / WINDOWS_README.md – project overview and setup.
- requirements.txt – Python dependencies (FastAPI, OpenAI SDK, SQLite, pandas, etc.).
- start_rag_app.sh, user_setup.bat/ps1 – environment-setup and launch scripts.
- test_db_creation.py – root-level test for DB.
- src/ – main application code and utilities.

src/
- create_database.py, create_simple_db.py, add_sample_data_minimal.py – DB schema creation & data ingestion.
- check_database*.py, check_schema.py, check_table_schema.py – DB verification utilities.
- farm_rag_app.py – CLI interface.
- farm_rag_api.py – FastAPI server exposing /ask, /schema, /examples, /health.
- web_interface.html – simple front-end served by FastAPI.
- quick_test.py, test_rag_app.py, demo.py – smoke tests, full test suite, interactive demo.
- finbin_farm_data.db (created at runtime) – SQLite database file.

##### README Insights
- Architecture overview: User Question → OpenAI LLM → SQL Generation → SQLite Execution → Data Analysis → AI Response.
- Multiple interfaces (CLI, API+web, demo).
- Environment variables: OPENAI_API_KEY, DATABASE_PATH, OPENAI_MODEL, etc.
- Deployment via shell/PowerShell scripts.

##### Diagramming Recommendations
- Use clear, consistent labels for all components (e.g., “OpenAI API,” “SQLite DB,” “FastAPI Server”).
- From clients → API/Core (requests)
- Core → OpenAI API (prompt) → Core (SQL)
- Core → SQLite (SQL execution) → Core (results)
- Core → clients (responses)
- Blue for interfaces
- Green for core logic/processing
- Orange for external services
- Brown for database
- Rectangles for services/modules
- Clouds for external APIs

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients Layer
    subgraph "Clients" 
        direction TB
        CLI["CLI Interface"]:::interface
        Demo["Interactive Demo"]:::interface
        WebUI["Web UI (Static HTML)"]:::interface
    end

    %% API and Core Layer
    subgraph "Backend" 
        direction TB
        API["FastAPI Server<br/>(/ask, /schema, /examples, /health)"]:::core
        subgraph "RAG Engine" 
            direction TB
            Parser["Question Parser & Prompt Builder"]:::core
            OpenAIInt["OpenAI Integration"]:::external
            SQLGen["SQL Generation Module"]:::core
        end
    end

    %% Database Layer
    subgraph "Database" 
        direction TB
        SQLiteDB["SQLite Database<br/>(finbin_farm_data.db)"]:::db
    end

    %% External Services
    OpenAIAPI["OpenAI API"]:::external

    %% Offline Workflow
    subgraph "Offline DB Setup" 
        direction TB
        CreateFullDB["Schema & Full DB Setup"]:::db
        CreateSimpleDB["Simple DB Setup"]:::db
        AddSampleData["Sample Data Loader"]:::db
        CheckDB["General DB Checks"]:::db
        CheckDBWin["Windows DB Checks"]:::db
        CheckSchema["Schema Validation"]:::db
        CheckTable["Table Schema Checks"]:::db
    end

    %% DevOps & Testing
    subgraph "DevOps & Testing" 
        direction TB
        Requirements["Dependency Management<br/>(requirements.txt)"]:::devops
        StartScript["Start RAG App<br/>(start_rag_app.sh)"]:::devops
        UserSetupBat["User Setup (Windows .bat)"]:::devops
        UserSetupPS1["User Setup (PowerShell)"]:::devops
        QuickTest["Quick Smoke Tests"]:::test
        FullTest["Full Application Tests"]:::test
        DBCreateTest["DB Creation Test"]:::test
    end

    %% Connections
    CLI -->|requests| API
    Demo -->|requests| API
    WebUI -->|HTTP calls| API

    API -->|calls| Parser
    Parser -->|builds prompt| OpenAIInt
    OpenAIInt -->|sends prompt| OpenAIAPI
    OpenAIAPI -->|returns SQL| OpenAIInt
    OpenAIInt -->|passes SQL| SQLGen
    SQLGen -->|executes SQL| SQLiteDB
    SQLiteDB -->|returns results| SQLGen
    SQLGen -->|formats results| API
    API -->|responses| CLI
    API -->|responses| Demo
    API -->|responses| WebUI

    %% Offline connections
    CreateFullDB --> SQLiteDB
    CreateSimpleDB --> SQLiteDB
    AddSampleData --> SQLiteDB
    CheckDB --> SQLiteDB
    CheckDBWin --> SQLiteDB
    CheckSchema --> SQLiteDB
    CheckTable --> SQLiteDB

    %% DevOps & Testing connections
    Requirements --> StartScript
    Requirements --> UserSetupBat
    Requirements --> UserSetupPS1
    QuickTest --> API
    QuickTest --> SQLiteDB
    FullTest --> API
    FullTest --> SQLiteDB
    DBCreateTest --> CreateFullDB

    %% Click Events
    click CLI "https://github.com/kitadmin01/farm-financial-rag/blob/main/src/farm_rag_app.py"
    click Demo "https://github.com/kitadmin01/farm-financial-rag/blob/main/src/demo.py"
    click WebUI "https://github.com/kitadmin01/farm-financial-rag/blob/main/src/web_interface.html"
    click API "https://github.com/kitadmin01/farm-financial-rag/blob/main/src/farm_rag_api.py"
    click CreateFullDB "https://github.com/kitadmin01/farm-financial-rag/blob/main/src/create_database.py"
    click CreateSimpleDB "https://github.com/kitadmin01/farm-financial-rag/blob/main/src/create_simple_db.py"
    click AddSampleData "https://github.com/kitadmin01/farm-financial-rag/blob/main/src/add_sample_data_minimal.py"
    click CheckDB "https://github.com/kitadmin01/farm-financial-rag/blob/main/src/check_database.py"
    click CheckDBWin "https://github.com/kitadmin01/farm-financial-rag/blob/main/src/check_database_windows.py"
    click CheckSchema "https://github.com/kitadmin01/farm-financial-rag/blob/main/src/check_schema.py"
    click CheckTable "https://github.com/kitadmin01/farm-financial-rag/blob/main/src/check_table_schema.py"
    click QuickTest "https://github.com/kitadmin01/farm-financial-rag/blob/main/src/quick_test.py"
    click FullTest "https://github.com/kitadmin01/farm-financial-rag/blob/main/src/test_rag_app.py"
    click DBCreateTest "https://github.com/kitadmin01/farm-financial-rag/blob/main/test_db_creation.py"
    click StartScript "https://github.com/kitadmin01/farm-financial-rag/blob/main/start_rag_app.sh"
    click UserSetupBat "https://github.com/kitadmin01/farm-financial-rag/blob/main/user_setup.bat"
    click UserSetupPS1 "https://github.com/kitadmin01/farm-financial-rag/blob/main/user_setup.ps1"
    click Requirements "https://github.com/kitadmin01/farm-financial-rag/blob/main/requirements.txt"
    click README "https://github.com/kitadmin01/farm-financial-rag/blob/main/README.md"
    click WINDOWS_README "https://github.com/kitadmin01/farm-financial-rag/blob/main/WINDOWS_README.md"

    %% Styles
    classDef interface fill:#D0E8FF,stroke:#2C7BE5,color:#2C7BE5,stroke-width:1px;
    classDef core fill:#D4F8E8,stroke:#28A745,color:#28A745,stroke-width:1px;
    classDef external fill:#FFF4E6,stroke:#FD7E14,color:#FD7E14,stroke-width:1px;
    classDef db fill:#FBEEDD,stroke:#A569BD,color:#A569BD,stroke-width:1px;
    classDef devops fill:#EDEFF2,stroke:#6C757D,color:#6C757D,stroke-width:1px;
    classDef test fill:#FCEFEF,stroke:#DC3545,color:#DC3545,stroke-width:1px;
```
