# dmquan1105/travel_chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/dmquan1105/travel_chatbot
- Repository: https://github.com/dmquan1105/travel_chatbot

## Overview

##### Project type and purpose
- This is a full-stack travel chatbot application.
- Frontend: React single-page app for chat UI.
- Backend: Python (FastAPI/uvicorn) exposing REST/WebSocket endpoints.
- Core logic: LangChain + Gemini AI for planning, rewriting, synthesizing responses.
- Data: MongoDB for conversation/message storage, a vector store for travel knowledge, Scrapy crawler for raw travel data, and external APIs (weather, Tavily/web search).

##### File structure
- Top-level:
- README.md, .env.example, requirements.txt, main.py, prompt.py
- Agents folder: base_agent, orchestrator, planner, rewriter, responder, response_synthesizer, travel_bot
- backend/: server.py (FastAPI app), conversation.py, message.py, database.py
- frontend/: React app (components, assets, config files)
- crawl/: Scrapy project to crawl travel data → produces data/travel_data.jsonl
- travel_vectorstore/: loader.py (ingest), storage.py (persist vector embeddings)
- tools/: wrappers for external APIs (get_weather, web_search, search_travel_info)
- scripts/preload_models.py: preloads vectorstore and models
- utils/: misc scripts for data handling

##### README for additional insights
- Tech stack: Python 3.8+, Node.js 16+, MongoDB Atlas
- Dependencies: LangChain, Gemini API, WeatherAPI, Tavily API
- Run sequence: crawl → preprocess/load data → start backend → start frontend
- Runtime: frontend on Vite dev server, backend by `uvicorn server:app`

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Frontend (Presentation)" 
        direction TB
        FE_ENTRY["main.jsx"]:::internal
        CHAT_APP["ChatApp"]:::internal
        CHAT_SIDEBAR["ChatSideBar"]:::internal
        CHAT_WINDOW["ChatWindow"]:::internal
        FE_ENTRY -->|renders| CHAT_APP
        CHAT_APP -->|contains| CHAT_SIDEBAR
        CHAT_APP -->|contains| CHAT_WINDOW
    end

    %% Backend API Layer
    subgraph "Backend (API Layer)"
        direction TB
        SERVER["FastAPI Server"]:::internal
        CONV_MODEL["conversation.py"]:::internal
        MSG_MODEL["message.py"]:::internal
        DB_CONN["database.py"]:::internal
        SERVER -->|uses| CONV_MODEL
        SERVER -->|uses| MSG_MODEL
        SERVER -->|connects to| DB_CONN
    end

    %% Domain Logic Layer
    subgraph "Domain Logic (Agents & Tools)"
        direction TB
        ORCH["Agent Orchestrator"]:::internal
        BASE_AGENT["BaseAgent Interface"]:::internal
        PLANNER["Planning Agent"]:::internal
        REWRITER["Rewriting Agent"]:::internal
        RESPONDER["Responding Agent"]:::internal
        SYNTHESIZER["ResponseSynthesizer"]:::internal
        TRAVEL_BOT["TravelBot Composition"]:::internal
        PROMPT["prompt.py"]:::internal

        ORCH -->|calls| PLANNER
        ORCH -->|calls| REWRITER
        ORCH -->|calls| RESPONDER
        ORCH -->|calls| SYNTHESIZER
        ORCH -->|aggregates| TRAVEL_BOT
        PLANNER -->|implements| BASE_AGENT
        REWRITER -->|implements| BASE_AGENT
        RESPONDER -->|implements| BASE_AGENT
        SYNTHESIZER -->|implements| BASE_AGENT
        ORCH -->|loads templates| PROMPT
    end

    %% Tool Adapters
    subgraph "Tool Adapters"
        direction TB
        WEATHER_TOOL["Weather API Adapter"]:::internal
        WEB_SEARCH_TOOL["Web Search Adapter"]:::internal
        TRAVEL_SEARCH_TOOL["Travel Info Adapter"]:::internal
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        MONGO["MongoDB"]:::data
        VECTOR_STORE["Vector Store"]:::data
    end

    %% External Services
    subgraph "External Services"
        direction TB
        LLM_API["Google Gemini API"]:::external
        WEATHER_API["WeatherAPI"]:::external
        TAVILY_API["Tavily API"]:::external
        WEB_SEARCH_API["Web Search API"]:::external
    end

    %% Ingestion Pipeline
    subgraph "Offline Ingestion Pipeline"
        direction TB
        CRAWLER["Scrapy Crawler"]:::internal
        RAW_DATA["travel_data.jsonl"]:::data
        LOADER["loader.py"]:::internal
        STORAGE["storage.py"]:::data
        PRELOAD["preload_models.py"]:::internal

        CRAWLER -->|produces| RAW_DATA
        RAW_DATA -->|ingest| LOADER
        LOADER -->|persists| STORAGE
        PRELOAD -->|preloads| STORAGE
        PRELOAD -->|initializes| PROMPT
    end

    %% Interactions
    CHAT_APP -->|sends requests| SERVER
    SERVER -->|forwards to| ORCH
    ORCH -->|queries| VECTOR_STORE
    ORCH -->|calls| WEATHER_TOOL
    ORCH -->|calls| WEB_SEARCH_TOOL
    ORCH -->|calls| TRAVEL_SEARCH_TOOL
    WEATHER_TOOL -->|calls| WEATHER_API
    WEB_SEARCH_TOOL -->|calls| WEB_SEARCH_API
    TRAVEL_SEARCH_TOOL -->|calls| TAVILY_API
    ORCH -->|invokes| LLM_API
    SERVER -->|reads/writes| MONGO

    %% Click Events
    click CHAT_APP "https://github.com/dmquan1105/travel_chatbot/blob/main/frontend/src/components/ChatApp.jsx"
    click CHAT_SIDEBAR "https://github.com/dmquan1105/travel_chatbot/blob/main/frontend/src/components/ChatSideBar.jsx"
    click CHAT_WINDOW "https://github.com/dmquan1105/travel_chatbot/blob/main/frontend/src/components/ChatWindow.jsx"
    click FE_ENTRY "https://github.com/dmquan1105/travel_chatbot/blob/main/frontend/src/main.jsx"
    click SERVER "https://github.com/dmquan1105/travel_chatbot/blob/main/backend/server.py"
    click CONV_MODEL "https://github.com/dmquan1105/travel_chatbot/blob/main/backend/conversation.py"
    click MSG_MODEL "https://github.com/dmquan1105/travel_chatbot/blob/main/backend/message.py"
    click DB_CONN "https://github.com/dmquan1105/travel_chatbot/blob/main/backend/database.py"
    click PROMPT "https://github.com/dmquan1105/travel_chatbot/blob/main/prompt.py"
    click ORCH "https://github.com/dmquan1105/travel_chatbot/blob/main/agents/orchestrator.py"
    click BASE_AGENT "https://github.com/dmquan1105/travel_chatbot/blob/main/agents/base_agent.py"
    click PLANNER "https://github.com/dmquan1105/travel_chatbot/blob/main/agents/planner.py"
    click REWRITER "https://github.com/dmquan1105/travel_chatbot/blob/main/agents/rewriter.py"
    click RESPONDER "https://github.com/dmquan1105/travel_chatbot/blob/main/agents/responder.py"
    click SYNTHESIZER "https://github.com/dmquan1105/travel_chatbot/blob/main/agents/response_synthesizer.py"
    click TRAVEL_BOT "https://github.com/dmquan1105/travel_chatbot/blob/main/agents/travel_bot.py"
    click WEATHER_TOOL "https://github.com/dmquan1105/travel_chatbot/blob/main/tools/get_weather.py"
    click WEB_SEARCH_TOOL "https://github.com/dmquan1105/travel_chatbot/blob/main/tools/web_search.py"
    click TRAVEL_SEARCH_TOOL "https://github.com/dmquan1105/travel_chatbot/blob/main/tools/search_travel_info.py"
    click CRAWLER "https://github.com/dmquan1105/travel_chatbot/tree/main/crawl/travel"
    click RAW_DATA "https://github.com/dmquan1105/travel_chatbot/blob/main/data/travel_data.jsonl"
    click LOADER "https://github.com/dmquan1105/travel_chatbot/blob/main/travel_vectorstore/loader.py"
    click STORAGE "https://github.com/dmquan1105/travel_chatbot/blob/main/travel_vectorstore/storage.py"
    click PRELOAD "https://github.com/dmquan1105/travel_chatbot/blob/main/scripts/preload_models.py"

    %% Styles
    classDef internal fill:#BDD7EE,stroke:#333,stroke-width:1px
    classDef data fill:#C6E0B4,stroke:#333,stroke-width:1px
    classDef external fill:#FCD5B4,stroke:#333,stroke-width:1px
```
