# ashgen12/aerocraft_rag_chatbot architecture

> Architecture diagram of the GitHub repository ashgen12/aerocraft_rag_chatbot, 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/ashgen12/aerocraft_rag_chatbot
- Repository: https://github.com/ashgen12/aerocraft_rag_chatbot

## Overview

##### Project type and purpose
- This is a Python-based AI chatbot application built with Streamlit.
- Its purpose is to answer questions about the fictional AeroCraft ACE-900 takeoff procedures by combining:
- A Retrieval-Augmented Generation (RAG) pipeline (vector store + embeddings)
- A dynamically built Knowledge Graph (KG) for structured context
- A Large Language Model (LLM) via the OpenRouter API
- An interactive Streamlit frontend, including a KG visualization

##### File structure
- Top-level scripts:
- app.py → Streamlit app / UI orchestration
- rag_chain.py → RAG pipeline setup (LangChain chains, FAISS store)
- kg_builder.py → KG construction & Plotly visualization (NetworkX + regex)
- utils.py → configuration, logging, helper routines
- Data directories:
- data/ace900_takeoff_manual.txt → source text for retrieval
- static/kg_visualization.html → optional saved KG graph
- Config and dependencies:
- .env → API keys for OpenRouter & HuggingFace
- requirements.txt → Python libraries (Streamlit, LangChain, NetworkX, FAISS, Plotly, python-dotenv)

##### README for additional insights
- Confirms architecture components: vector embeddings via Hugging Face, in-memory FAISS store, OpenRouter LLM backend, NetworkX KG, Streamlit UI, real-time logging of pipeline steps.
- Explains how queries traverse retrieval, graph extraction, and LLM synthesis.

##### Main components & their interactions
a. Frontend (Streamlit in app.py)
- Chat interface (user questions / assistant responses)
- Sidebar: KG visualization, processing logs
b. RAG Pipeline (rag_chain.py + FAISS)
- Chunk and embed manual text
- FAISS vector store for similarity search
c. Knowledge Graph Builder (kg_builder.py + NetworkX)
- Parse raw text into nodes & edges
- Provide structured context by querying graph for entities in user query
d. LLM Integration (OpenRouter API)
- Receives combined context (retrieved chunks + KG context) + user question
- Returns final answer
e. Utilities (utils.py)
- Logging each pipeline step
- Loading environment variables
f. Data Storage
- data/ace900_takeoff_manual.txt (source)
- FAISS in-memory index
- Optional static HTML export of KG

##### Architectural patterns and design principles
- Modular separation: UI layer, retrieval layer, knowledge-graph layer, LLM layer
- RAG pattern: decouple retrieval (vector store) from generation (LLM)
- Knowledge-graph enhancement: add structured context to improve grounding
- Dependency injection via utils (e.g., config loader)
- In-memory services: FAISS and NetworkX simplify deployment (no external DB)

1. User question → Streamlit Frontend
2. Frontend invokes RAG Chain & KG Builder in parallel:
- RAG Chain → embed query → search FAISS → retrieve text chunks
3. Combine KG context + text chunks → build LLM prompt via rag_chain.py
4. Send prompt → OpenRouter LLM API → receive answer
5. Streamlit displays answer; logs and interactive KG rendered in sidebar

##### Final checklist
- Components: Streamlit UI, RAG Chain, FAISS, KG Builder, NetworkX, LLM API, Embedding API
- Emphasis on modular separation and pipeline transparency

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1: User & Frontend
    subgraph "Layer 1: User & Frontend"
        User["User"]:::user
        Frontend["Streamlit UI\n(app.py)"]:::frontend
    end

    User -->|"asks question"| Frontend

    %% Layer 2: Backend Modules
    subgraph "Layer 2: Backend Modules"
        RAG["RAG Pipeline\n(rag_chain.py)"]:::backend
        KG["Knowledge Graph Builder\n(kg_builder.py)"]:::backend
        Utils["Utilities\n(utils.py)"]:::backend
    end

    Frontend -->|"invoke retrieval"| RAG
    Frontend -->|"invoke graph build"| KG
    RAG -->|"uses"| Utils
    KG -->|"uses"| Utils

    %% Data Stores
    subgraph "Data Stores"
        FAISS["FAISS Vector Store"]:::datastore
        NetworkX["NetworkX Graph"]:::datastore
        TextData["Source Text\n(data/ace900_takeoff_manual.txt)"]:::datastore
        StaticHTML["KG Static HTML\n(static/kg_visualization.html)"]:::datastore
    end

    RAG -->|"search vectors"| FAISS
    RAG -->|"load chunks"| TextData
    KG -->|"parse manual"| TextData
    KG -->|"build graph"| NetworkX
    KG -->|"export optional"| StaticHTML

    %% Layer 3: External Services
    subgraph "Layer 3: External Services"
        EmbeddingAPI["Hugging Face\nEmbedding API"]:::external
        LLM["OpenRouter LLM API"]:::external
    end

    RAG -->|"embed & query"| EmbeddingAPI
    RAG -->|"combined context"| LLM
    KG -->|"subgraph context"| LLM
    LLM -->|"answer"| Frontend

    %% Config & Documentation
    subgraph "Configuration & Docs"
        Env[".env"]:::config
        Requirements["requirements.txt"]:::config
        README["README.md"]:::config
    end

    Frontend -->|"loads config"| Env
    RAG -->|"loads libs"| Requirements
    KG -->|"docs"| README

    %% Click Events
    click Frontend "https://github.com/ashgen12/aerocraft_rag_chatbot/blob/main/app.py"
    click RAG "https://github.com/ashgen12/aerocraft_rag_chatbot/blob/main/rag_chain.py"
    click KG "https://github.com/ashgen12/aerocraft_rag_chatbot/blob/main/kg_builder.py"
    click Utils "https://github.com/ashgen12/aerocraft_rag_chatbot/blob/main/utils.py"
    click Env "https://github.com/ashgen12/aerocraft_rag_chatbot/blob/main/.env"
    click TextData "https://github.com/ashgen12/aerocraft_rag_chatbot/blob/main/data/ace900_takeoff_manual.txt"
    click StaticHTML "https://github.com/ashgen12/aerocraft_rag_chatbot/blob/main/static/kg_visualization.html"
    click Requirements "https://github.com/ashgen12/aerocraft_rag_chatbot/blob/main/requirements.txt"
    click README "https://github.com/ashgen12/aerocraft_rag_chatbot/blob/main/README.md"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#0366d6,color:#0366d6;
    classDef backend fill:#DDFFDD,stroke:#228B22,color:#228B22;
    classDef datastore fill:#FFE0B2,stroke:#FF8C00,color:#FF8C00;
    classDef external fill:#E1C5FF,stroke:#800080,color:#800080;
    classDef config fill:#F0F0F0,stroke:#666666,color:#333333;
    classDef user fill:#CCCCCC,stroke:#333333,color:#333333;
```
