# qnity001/github-query architecture

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

- Interactive diagram: https://gitdiagram.com/qnity001/github-query
- Repository: https://github.com/qnity001/github-query

## Overview

##### High-Level Architectural Overview
- Two main logical blocks:
a. Frontend (app.py)
b. Backend  (main.py + src/ modules)

##### Main Components and Data Flow
1) Frontend Block (app.py)
- Input Module
- Responsibility: read user input (e.g., repo path), validate it, and hand off to the backend.
- Maps to: return_path.py
- Output Renderer

2) Backend Block (main.py orchestrator)
- Tree Generator
- Modules: src/tree/create_tree_json.py, src/tree/repo_tree.py
- Responsibility: traverse the file system under the repo path, build a JSON representation of the project structure.
- Code Parser & Formatter
- Module: src/tree/display_tree.py (optional view), src/tree/create_mermaid.py
- Chunking Pipeline
- Controller: src/chunking/controller.py
- Processor: src/chunking/processor.py
- Queries: src/chunking/queries/python_queries.py
- Responsibility: walk each source file, extract logical “chunks” (functions, classes, blocks).
- Embedding Service
- Module: src/embedding/embedding.py
- Responsibility: embed each code chunk into vector representations (via a configured embedding model).
- Retrieval Engine
- Modules: src/retrieving/retriever.py, src/retrieving/llm_classifier.py, src/retrieving/intents.joblib
- Responsibility: given a user query, classify intent, find relevant chunk embeddings, rank them.
- LLM Query Module
- Module: src/llm_query/chatbot.py
- Responsibility: formulate prompts combining retrieved chunks and user questions, send to LLM, receive response.
- Module: src/tree/create_mermaid.py

##### Relationships and Interactions (Data Flow Steps)
1) User invokes app.py
→ Input Module (return_path.py) obtains repo path.
2) app.py calls main.py with the path
→ main.py triggers Tree Generator → produces a JSON tree.
4) main.py invokes Chunking Controller
→ reads each file via python_queries → yields code chunks.
5) Each chunk is passed to Embedding Service → vector store.
6) Retrieval Engine consumes the vector store + user query → returns top‐N relevant chunks.
7) LLM Query Module crafts a prompt from retrieved chunks & user query → sends to LLM → gets answer.

##### Architectural Patterns and Principles
- Modular Pipeline: each step (tree generation, chunking, embedding, retrieval, querying, rendering) is a distinct module.
- Single Responsibility: controllers/orchestrators call specific services (processor, embedding, retriever, chatbot).
- Dependency Injection (via config.py): centralize model/API keys and parameters.
- Separation of Concerns: I/O (frontend), business logic (backend orchestrator), and specialized services (chunking, embedding).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Block
    subgraph "Frontend" 
        direction TB
        FFrontend["Frontend – app.py\nCLI Entry & Renderer"]:::frontend
        Input["Input Module – src/return_path.py"]:::frontend
    end

    %% Backend Orchestrator
    subgraph "Backend Orchestrator"
        direction TB
        main["Orchestrator – main.py"]:::orchestrator
    end

    %% Backend Services
    subgraph "Backend Services"
        direction TB
        TreeGenRepo["Repo Traversal – src/tree/repo_tree.py"]:::service
        TreeGenJSON["Tree JSON Builder – src/tree/create_tree_json.py"]:::service
        DisplayTree["Tree Display – src/tree/display_tree.py"]:::service
        MermaidInit["Mermaid Text Creator – src/tree/create_mermaid.py"]:::service
        ChunkController["Chunking Controller – src/chunking/controller.py"]:::service
        ChunkProcessor["Chunk Processor – src/chunking/processor.py"]:::service
        PythonQueries["Python Queries – src/chunking/queries/python_queries.py"]:::service
        EmbeddingService["Embedding Service – src/embedding/embedding.py"]:::service
        Retriever["Retriever – src/retrieving/retriever.py"]:::service
        Classifier["LLM Classifier – src/retrieving/llm_classifier.py"]:::service
        IntentModel["Intent Model – src/retrieving/intents.joblib"]:::static
        Chatbot["LLM Query Module – src/llm_query/chatbot.py"]:::service
        MermaidGen["Mermaid Text Creator – src/tree/create_mermaid.py"]:::service
    end

    %% Data Flow
    FFrontend -->|1 repo path string| Input
    Input -->|2 repo path| main
    main -->|3 trigger tree gen| TreeGenRepo
    TreeGenRepo -->|filesystem data| TreeGenJSON
    TreeGenJSON -->|JSON tree| DisplayTree
    DisplayTree -->|raw mermaid text| MermaidInit
    main -->|4 start chunking| ChunkController
    ChunkController -->|calls processor| ChunkProcessor
    ChunkProcessor -->|extract chunks| PythonQueries
    PythonQueries -->|code chunks| EmbeddingService
    EmbeddingService -->|vectors| Retriever
    Retriever -->|requests classification| Classifier
    Classifier -->|uses model| IntentModel
    Classifier -->|classified intent| Retriever
    Retriever -->|top-N chunks| main
    main -->|7 build prompt| Chatbot
    Chatbot -->|LLM answer| MermaidGen
    MermaidGen -->|Mermaid text| main
    main -->|9 Mermaid diagram| FFrontend

    %% Click events
    click FFrontend "https://github.com/qnity001/github-query/blob/main/app.py"
    click Input "https://github.com/qnity001/github-query/blob/main/src/return_path.py"
    click main "https://github.com/qnity001/github-query/blob/main/main.py"
    click TreeGenRepo "https://github.com/qnity001/github-query/blob/main/src/tree/repo_tree.py"
    click TreeGenJSON "https://github.com/qnity001/github-query/blob/main/src/tree/create_tree_json.py"
    click DisplayTree "https://github.com/qnity001/github-query/blob/main/src/tree/display_tree.py"
    click MermaidInit "https://github.com/qnity001/github-query/blob/main/src/tree/create_mermaid.py"
    click ChunkController "https://github.com/qnity001/github-query/blob/main/src/chunking/controller.py"
    click ChunkProcessor "https://github.com/qnity001/github-query/blob/main/src/chunking/processor.py"
    click PythonQueries "https://github.com/qnity001/github-query/blob/main/src/chunking/queries/python_queries.py"
    click EmbeddingService "https://github.com/qnity001/github-query/blob/main/src/embedding/embedding.py"
    click Retriever "https://github.com/qnity001/github-query/blob/main/src/retrieving/retriever.py"
    click Classifier "https://github.com/qnity001/github-query/blob/main/src/retrieving/llm_classifier.py"
    click IntentModel "https://github.com/qnity001/github-query/blob/main/src/retrieving/intents.joblib"
    click Chatbot "https://github.com/qnity001/github-query/blob/main/src/llm_query/chatbot.py"

    %% Styles
    classDef frontend fill:#E0F7FF,stroke:#00A3E0,stroke-width:2px;
    classDef orchestrator fill:#FFF4C2,stroke:#E1B000,stroke-width:2px;
    classDef service fill:#E8F5E9,stroke:#388E3C,stroke-width:2px;
    classDef static fill:#F5F5F5,stroke:#9E9E9E,stroke-width:2px;
```
