# harsh-vardhhan/ai-agent-flight-scanner architecture

> Architecture diagram of the GitHub repository harsh-vardhhan/ai-agent-flight-scanner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harsh-vardhhan/ai-agent-flight-scanner
- Repository: https://github.com/harsh-vardhhan/ai-agent-flight-scanner

## Overview

##### Project type and purpose
- This is a full-stack, retrieval-augmented generation (RAG) service for flight-price queries.
- It consists of a dedicated backend (FastAPI + LangChain + LLMs + SQLite + Chroma) plus a separate frontend repo.
- Purpose: accept natural-language flight queries, retrieve policy and flight data, generate/verify SQL via LLMs, fetch results, and return an answer.

##### File structure
Top-level:
- app/
– main.py: REST entry point
– config.py: environment & API-key management
– database.py & models.py: ORM + connection to SQLite
– vector_db.py: Chroma vector store wrapper
– llm.py: LLM client abstractions (Groq, Ollama, Qwen, Llama)
– query_chain.py: LangChain agent orchestrator
– *.py (prompts, validators, extractors): modular prompt‐engineering
- data/
– flight_data.json: seed flight records
– indigo_policy.txt, vietjet_policy.txt: airline policy docs
- README + requirements.txt: dep list & architecture spec

##### README for additional insights
- Tech stack table: details on LLM platforms, vector & SQL DBs, REST framework.
- Architecture image: shows flow from frontend → FastAPI → LangChain chain → LLMs & DBs → response.
- Environment variables: GROQ_API_KEY, OPENAI_API_KEY, DEEPSEEK_API_KEY.

##### Main components & interactions
a. Components
1. Client / Frontend
2. API Layer (FastAPI server; main.py)
3. Orchestration Layer (LangChain QueryChain)
4. LLM Services
– Groq (large LLM)
– Ollama (small LLM for embeddings)
– Qwen (SQL generation/verification)
– Llama (vector embedding model)
5. Data Stores
– SQLite (flight_data & query logs)
– Chroma Vector DB (embedding index over policies & flights)
6. Configuration / Secrets (.env)
b. Relationships & data flow
1. User → Frontend → HTTP request → FastAPI
2. FastAPI loads config → passes prompt → QueryChain
3. QueryChain splits work:
- Runs embedding retriever → Chroma → returns context
- Runs SQL‐generation LLM → generates SQL
- Runs SQL‐verification LLM → validates SQL
4. Verified SQL → SQLite → result rows
5. Results + context → LLM response prompt → final answer
6. FastAPI → JSON response → Frontend → User
c. Architectural patterns
- Layered (API / orchestration / data)
- Modular prompt‐engineering
- LLM‐as‐service (polyglot LLM strategy)
- Retrieval + generation pipeline (RAG)
d. Key technologies
- FastAPI
- LangChain
- Groq, Ollama, Qwen, Llama
- SQLite (+ SQLAlchemy models)
- Chroma

## Diagram (Mermaid)

```mermaid
flowchart TD
    direction TB

    Client["Client / Frontend"]:::infra

    subgraph Backend
        FastAPI["FastAPI API Layer"]:::infra
        Config["Configuration / Secrets"]:::infra
        DBConn["DB Connection"]:::infra
        Models["ORM Models"]:::infra
        VectorWrapper["Vector Store Wrapper"]:::infra
        LC["LangChain QueryChain"]:::orchestration
        LLMcl["LLM Client Abstractions"]:::orchestration
        subgraph "SQL Modules"
            Gen["Generate SQL"]:::orchestration
            Val["Validate SQL"]:::orchestration
        end
        subgraph "Prompt Engineering"
            SP["SQL Prompt"]:::orchestration
            VSP["Verify SQL Prompt"]:::orchestration
            RP["Final Response Prompt"]:::orchestration
            LP["Luggage Prompt"]:::orchestration
        end
        Util["Utility & Pre-/Post-processing"]:::infra
    end

    subgraph Data_Stores
        SQLDB[(SQLite DB)]:::db
        VectorDB[(Chroma Vector DB)]:::db
    end

    subgraph "Seed Data / Policies"
        FlightData["Flight Data"]:::db
        Indigo["Indigo Policy"]:::db
        Vietjet["Vietjet Policy"]:::db
    end

    subgraph "External LLM Services"
        Groq["Groq LLM"]:::ai
        Ollama["Ollama LLM"]:::ai
        Qwen["Qwen LLM"]:::ai
        Llama["Llama Model"]:::ai
    end

    Client -->|JSON request| FastAPI
    FastAPI --> Config
    FastAPI --> LC
    LC --> VectorWrapper
    VectorWrapper --> VectorDB
    LC --> LLMcl
    LLMcl --> Groq
    LLMcl --> Ollama
    LLMcl --> Qwen
    LLMcl --> Llama
    LC --> SP
    LC --> VSP
    LC --> RP
    LC --> LP
    LC --> Gen
    LC --> Val
    Gen -->|SQL query| SQLDB
    Val -->|validation queries| SQLDB
    SQLDB --> RP
    VectorDB --> RP
    RP -->|response data| FastAPI
    FastAPI -->|JSON response| Client

    FlightData --> SQLDB
    Indigo --> VectorDB
    Vietjet --> VectorDB

    FastAPI --> DBConn
    FastAPI --> Models
    Config -.-> LC
    Util -.-> LC
    Util -.-> SP
    Util -.-> VSP
    Util -.-> RP
    Util -.-> LP

    click FastAPI "https://github.com/harsh-vardhhan/ai-agent-flight-scanner/blob/main/app/main.py"
    click Config "https://github.com/harsh-vardhhan/ai-agent-flight-scanner/blob/main/app/config.py"
    click DBConn "https://github.com/harsh-vardhhan/ai-agent-flight-scanner/blob/main/app/database.py"
    click Models "https://github.com/harsh-vardhhan/ai-agent-flight-scanner/blob/main/app/models.py"
    click VectorWrapper "https://github.com/harsh-vardhhan/ai-agent-flight-scanner/blob/main/app/vector_db.py"
    click LC "https://github.com/harsh-vardhhan/ai-agent-flight-scanner/blob/main/app/query_chain.py"
    click LLMcl "https://github.com/harsh-vardhhan/ai-agent-flight-scanner/blob/main/app/llm.py"
    click Gen "https://github.com/harsh-vardhhan/ai-agent-flight-scanner/blob/main/app/generate_and_verify_sql.py"
    click Val "https://github.com/harsh-vardhhan/ai-agent-flight-scanner/blob/main/app/query_validator.py"
    click SP "https://github.com/harsh-vardhhan/ai-agent-flight-scanner/blob/main/app/sql_prompt.py"
    click VSP "https://github.com/harsh-vardhhan/ai-agent-flight-scanner/blob/main/app/verify_sql_prompt.py"
    click RP "https://github.com/harsh-vardhhan/ai-agent-flight-scanner/blob/main/app/response_prompt.py"
    click LP "https://github.com/harsh-vardhhan/ai-agent-flight-scanner/blob/main/app/luggage_prompt.py"
    click Util "https://github.com/harsh-vardhhan/ai-agent-flight-scanner/blob/main/app/strip_think_tags.py"
    classDef infra fill:#80B3FF,stroke:#333,stroke-width:1px
    classDef orchestration fill:#a3d977,stroke:#333,stroke-width:1px
    classDef ai fill:#f9c846,stroke:#333,stroke-width:1px
    classDef db fill:#5FB3B3,stroke:#333,stroke-width:1px
```
