# bshraman/codebase-qna-search architecture

> Architecture diagram of the GitHub repository bshraman/codebase-qna-search, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bshraman/codebase-qna-search
- Repository: https://github.com/bshraman/codebase-qna-search

## Overview

##### Main Components
- Configuration & Environment Setup:
- Configuration file (core/config.py) and note that environment variables (such as API keys and path settings) drive the behavior of the application.
- Core Processing Modules:
- Nodes:
- document_embedding.py (handles code/document embedding via LlamaIndex)
- query.py (handles query processing)
- vector_db.py (interfaces with ChromaDB for create/query operations)
- Graph and State:
- state_graph.py (constructs a state graph to represent workflows/interactions using LangGraph)
- state.py (manages overall state tracking)
- Routing:
- route.py (defines the workflow by checking conditions in the vector database and directing processing accordingly)
- External Services & Databases:
- ChromaDB for vector database operations.
- OpenAI API for natural language processing and interpreting queries.
- Entry Point:
- main.py: the application’s entry point that initializes and orchestrates various components.
- Documentation:
- docs folder for storing visual aids such as the compiled graph and output screenshots.

##### Relationships and Data Flow
- Creation and flow between various Nodes:
- Document Embedding Node uses LlamaIndex to process input documents.
- Query Node receives user queries and interacts with the Vector Database Node.
- Vector Database Node communicates with ChromaDB to either create a new collection or query an existing one.
- That once the nodes are prepared, the State Graph (build in state_graph.py using LangGraph) captures these interactions and workflows.
- The routing module (route.py) directs the process flow based on the state of the vector database (existence/absence of a collection).

##### Architectural Patterns and Design Principles
- Separation of Concerns: Each file in the core module (nodes, graph, routes, state) is responsible for a distinct part of the overall workflow.
- Modular Design: The project modules (configuration, nodes, routing, state graph) are well-separated which facilitates testing, maintenance, and potential expansion.
- Data Flow and State Management: The use of a state graph demonstrates a directed and managed flow. Also, using environment variables gives flexibility across deployment contexts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Initialization Layer
    subgraph "Initialization"
        main("Entry Point (main.py)"):::backend
        config("Configuration (core/config.py)"):::config
        main -->|"initializes"| config
    end

    %% Processing Modules Layer
    subgraph "Processing Modules"
        docEmbed("Document Embedding Node (LlamaIndex)"):::backend
        query("Query Node"):::backend
        vectorDB("VectorDB Node (ChromaDB interface)"):::backend
        route("Routing Module"):::backend
        state("State Management"):::backend
        stateGraph("State Graph (LangGraph)"):::backend
    end

    %% External Services Layer
    subgraph "External Services"
        openai("OpenAI API"):::external
        chroma("ChromaDB"):::external
    end

    %% Documentation
    docs("Documentation (docs)"):::docs

    %% Data Flow Connections
    config -->|"sets_up"| docEmbed
    config -->|"sets_up"| query
    config -->|"sets_up"| vectorDB
    config -->|"sets_up"| state

    docEmbed -->|"calls"| openai
    query -->|"calls"| openai

    query -->|"queries"| vectorDB
    vectorDB -->|"communicates"| chroma

    query -->|"triggers"| route
    route -->|"directs"| vectorDB

    docEmbed -->|"updates"| stateGraph
    query -->|"updates"| stateGraph
    route -->|"updates"| stateGraph
    state -->|"updates"| stateGraph

    main -->|"orchestrates"| docs

    %% Click Events
    click main "https://github.com/bshraman/codebase-qna-search/blob/main/main.py"
    click config "https://github.com/bshraman/codebase-qna-search/blob/main/core/config.py"
    click docEmbed "https://github.com/bshraman/codebase-qna-search/blob/main/core/nodes/document_embedding.py"
    click query "https://github.com/bshraman/codebase-qna-search/blob/main/core/nodes/query.py"
    click vectorDB "https://github.com/bshraman/codebase-qna-search/blob/main/core/nodes/vector_db.py"
    click route "https://github.com/bshraman/codebase-qna-search/blob/main/core/route.py"
    click state "https://github.com/bshraman/codebase-qna-search/blob/main/core/state.py"
    click stateGraph "https://github.com/bshraman/codebase-qna-search/blob/main/core/graph/state_graph.py"
    click docs "https://github.com/bshraman/codebase-qna-search/tree/main/docs"

    %% Styles
    classDef backend fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef config fill:#FFD700,stroke:#000,stroke-width:1px;
    classDef external fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef docs fill:#DDA0DD,stroke:#000,stroke-width:1px;
```
