# hoang3072003/hoanghaphone architecture

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

- Interactive diagram: https://gitdiagram.com/hoang3072003/hoanghaphone
- Repository: https://github.com/hoang3072003/hoanghaphone

## Overview

##### Main Components
- User Interface: A client (likely a web-based or chatbot interface) where users submit queries and interact with the system.
- API Server / Backend: Represented primarily by app.py, which acts as the entry point for handling requests.
- Semantic Router: (sematic_router.py) This module likely classifies and routes incoming queries to determine whether to extract additional information from the database.
- Query Processor: (query_process.py) Handles the processing of user queries, including any pre-processing needed before invoking the RAG module.
- RAG Module: (RAG.py) The core component that integrates the original query with the retrieval augmentation; this component merges the search results from the database with the user query.
- External API Integration: (together_api.py) Manages connections to the together.ai API to process the augmented prompt and generate responses.
- Database & Vector Search: While not coded in this repository, the README specifies the use of MongoDB Atlas for vector search (including configuration via environment variables like MONGO_URI, DB_NAME, COLLECTION_NAME). This component should be depicted as an external service.
- Embedding Configuration: The routesEmbedding.json file and the EMBEDDING_MODEL parameter in the .env indicate a mechanism for handling text embeddings, which is an important part of the RAG process.

##### Relationships and Data Flow
- The API Server (app.py) receives the query.
- The query is directed to the Semantic Router (sematic_router.py), which assesses if the query needs database retrieval (e.g., for phone specifications, prices, detailed descriptions).
- The RAG module (RAG.py) then combines the original user query with the search results using the specified syntax (as noted in README), preparing a final prompt.
- The final prompt is forwarded to the together.ai API via together_api.py.
- The together.ai API processes the request and returns the result, which is then sent back through the API Server to the User Interface.
- Additionally, a context management feature (evidenced by the ability to “Làm mới cuộc trò chuyện”) should be noted, showing state/context handling in the system.

##### Architectural Patterns & Design Principles
- Modular Separation: Each Python file represents a distinct module that handles a part of the request lifecycle. This modular design is key to extensibility and maintainability.
- External Services Integration: Clear boundaries between internal processing (query processing, semantic routing) and external services (MongoDB, together.ai API) should be visually emphasized.
- Environment Configuration: Highlight the use of environment variables (.env file) to manage external API keys and database credentials securely.
- RAG Approach: Emphasize the pattern of disambiguating user queries via retrieval, then augmenting the language model’s generation process with external data – a key innovation in the project.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    UI["User Interface"]:::internal

    %% Backend Processing
    API["API Server (app.py)"]:::internal
    SR["Semantic Router (sematic_router.py)"]:::internal
    QP["Query Processor (query_process.py)"]:::internal
    RAG["RAG Module (RAG.py)"]:::internal
    TAPI["External API Integration (together_api.py)"]:::internal

    %% External and Configuration Components
    DB["MongoDB Atlas (Vector Search)"]:::external
    EMB["Embedding Configuration (routesEmbedding.json)"]:::internal

    %% Data Flow
    UI -->|"QueryInput"| API
    API -->|"RouteQuery"| SR
    SR -->|"PreProcessQuery"| QP
    QP -->|"OptionalDBLookup"| DB
    DB -- "ReturnData" --> QP
    QP -->|"AggregateData"| RAG
    RAG -->|"UtilizeEmbedding"| EMB
    RAG -->|"SendFinalPrompt"| TAPI
    TAPI -->|"ReturnResponse"| API
    API -->|"SendAnswer"| UI

    %% Click Events
    click API "https://github.com/hoang3072003/hoanghaphone/blob/main/app.py"
    click SR "https://github.com/hoang3072003/hoanghaphone/blob/main/sematic_router.py"
    click QP "https://github.com/hoang3072003/hoanghaphone/blob/main/query_process.py"
    click RAG "https://github.com/hoang3072003/hoanghaphone/blob/main/RAG.py"
    click TAPI "https://github.com/hoang3072003/hoanghaphone/blob/main/together_api.py"
    click EMB "https://github.com/hoang3072003/hoanghaphone/blob/main/routesEmbedding.json"

    %% Styles
    classDef internal fill:#bbf,stroke:#333,stroke-width:2px;
    classDef external fill:#cfc,stroke:#333,stroke-width:2px;
```
