# aryangupta1211/agentic-trip-planner architecture

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

- Interactive diagram: https://gitdiagram.com/aryangupta1211/agentic-trip-planner
- Repository: https://github.com/aryangupta1211/agentic-trip-planner

## Overview

##### Project type and purpose
- This is a full-stack AI-driven travel planner.
- Frontend: Streamlit UI for user interaction.
- Backend: FastAPI service exposing REST endpoints.
- Core: A LangChain/LangGraph “agentic workflow” that orchestrates multiple sub-agents and real-time tools to build itineraries.

##### File structure
Top level:
- streamlit_app.py – entry point for Streamlit frontend
- main.py – entry point for FastAPI backend
- agent/ – defines the agentic_workflow (multi-agent orchestration)
- prompt_library/ – templates and prompt management
- tools/ – wrappers around each external data source (weather, currency, hotels, places, expense calc, arithmetic)
- utils/ – low-level API callers, config loader, model loader, save/output utilities
- config/ – configuration definitions (config.yaml)
- logger/, exception/ – cross-cutting concerns (logging, error handling)
- notebook/ – experimental prototyping

##### Extra clues from README
- Decoupled Streamlit ↔ FastAPI architecture
- Agentic workflow built on LangChain & LangGraph
- Two LLMs: Groq (fast) and OpenAI GPT-4 (reasoning)
- Real-time external services via tools (weather, hotel pricing, currency, places)
- Modular, Python-based, no database (stateless, all external data)

##### Diagramming conventions
- Use rectangles for internal modules (Streamlit, FastAPI, Agents, Tools, Utils).
- Blue for Presentation/API
- Green for Orchestration/Agents
- Orange for Tools/Utils
- Gray for cross-cutting concerns (config, logging, exceptions)
- User → Streamlit → FastAPI → Agent → Tools → External → back up the chain → Streamlit

##### Detailed capturing of essential elements
- Every directory’s responsibility: config, prompt_library, exception, logger, utils.
- How prompt_library feeds prompts into the agentic workflow.
- Model_loader’s role in connecting to LLMs.
- Demonstrate how save_to_document util outputs the final itinerary (e.g., PDF or markdown).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    User["User"]:::external
    Streamlit["Streamlit App"]:::frontend
    User -->|"inputs trip request"| Streamlit
    click Streamlit "https://github.com/aryangupta1211/agentic-trip-planner/blob/master/streamlit_app.py"

    %% API Layer
    FastAPI["FastAPI Service"]:::api
    Streamlit -->|"HTTP POST /plan"| FastAPI
    click FastAPI "https://github.com/aryangupta1211/agentic-trip-planner/blob/master/main.py"

    %% Orchestration Layer
    subgraph "Orchestration Layer" 
        direction TB
        Agentic["Agentic Workflow"]:::orchestration
        Planning["Planning Agent"]:::orchestration
        ToolAgent["Tool-Using Agent"]:::orchestration
        Agentic --> Planning
        Planning --> ToolAgent
        click Agentic "https://github.com/aryangupta1211/agentic-trip-planner/blob/master/agent/agentic_workflow.py"
        click Planning "https://github.com/aryangupta1211/agentic-trip-planner/blob/master/agent/agentic_workflow.py"
        click ToolAgent "https://github.com/aryangupta1211/agentic-trip-planner/blob/master/agent/agentic_workflow.py"
    end
    FastAPI -->|"calls agentic_workflow"| Agentic

    %% Prompt Library
    PromptLib["Prompt Library"]:::prompt
    Agentic -->|"loads prompts"| PromptLib
    click PromptLib "https://github.com/aryangupta1211/agentic-trip-planner/blob/master/prompt_library/prompt.py"

    %% Model Loader & LLMs
    ModelLoader["Model Loader (LLMs)"]:::util
    Agentic -->|"LLM call"| ModelLoader
    click ModelLoader "https://github.com/aryangupta1211/agentic-trip-planner/blob/master/utils/model_loader.py"

    subgraph "LLM Services"
        direction TB
        Groq["Groq LLM"]:::external
        GPT4["OpenAI GPT-4"]:::external
    end
    ModelLoader -->|"inference"| Groq
    ModelLoader -->|"inference"| GPT4

    %% Tool Layer
    subgraph "Tools Layer"
        direction TB
        WeatherTool["Weather Tool"]:::tools
        HotelTool["Hotel Pricing Tool"]:::tools
        CurrencyTool["Currency Conversion Tool"]:::tools
        PlaceTool["Place Search Tool"]:::tools
        ArithmeticTool["Arithmetic Tool"]:::tools

        click WeatherTool "https://github.com/aryangupta1211/agentic-trip-planner/blob/master/tools/weather_info_tool.py"
        click HotelTool "https://github.com/aryangupta1211/agentic-trip-planner/blob/master/tools/expense_calculator_tool.py"
        click CurrencyTool "https://github.com/aryangupta1211/agentic-trip-planner/blob/master/tools/currency_conversion_tool.py"
        click PlaceTool "https://github.com/aryangupta1211/agentic-trip-planner/blob/master/tools/place_search_tool.py"
        click ArithmeticTool "https://github.com/aryangupta1211/agentic-trip-planner/blob/master/tools/arithematic_op_tool.py"
    end
    ToolAgent -->|"invokes"| WeatherTool
    ToolAgent -->|"invokes"| HotelTool
    ToolAgent -->|"invokes"| CurrencyTool
    ToolAgent -->|"invokes"| PlaceTool
    ToolAgent -->|"invokes"| ArithmeticTool

    %% Utility Layer
    subgraph "Utils Layer"
        direction TB
        ConfigLoader["Config Loader"]:::util
        WeatherUtil["Weather API Caller"]:::util
        CurrencyUtil["Currency Converter Utility"]:::util
        PlaceUtil["Place Info Search Utility"]:::util
        ExpenseUtil["Expense Calculator Utility"]:::util
        SaveUtil["Save/Output Utility"]:::util

        click ConfigLoader "https://github.com/aryangupta1211/agentic-trip-planner/blob/master/utils/config_loader.py"
        click WeatherUtil "https://github.com/aryangupta1211/agentic-trip-planner/blob/master/utils/weather_info.py"
        click CurrencyUtil "https://github.com/aryangupta1211/agentic-trip-planner/blob/master/utils/currency_converter.py"
        click PlaceUtil "https://github.com/aryangupta1211/agentic-trip-planner/blob/master/utils/place_info_search.py"
        click ExpenseUtil "https://github.com/aryangupta1211/agentic-trip-planner/blob/master/utils/expense_calculator.py"
        click SaveUtil "https://github.com/aryangupta1211/agentic-trip-planner/blob/master/utils/save_to_document.py"
    end
    WeatherTool -->|"uses"| WeatherUtil
    CurrencyTool -->|"uses"| CurrencyUtil
    PlaceTool -->|"uses"| PlaceUtil
    HotelTool -->|"uses"| ExpenseUtil
    ArithmeticTool -->|"uses"| ExpenseUtil
    Agentic -->|"save output"| SaveUtil

    %% Configuration Definitions
    ConfigFile["config.yaml"]:::config
    click ConfigFile "https://github.com/aryangupta1211/agentic-trip-planner/blob/master/config/config.yaml"
    ConfigLoader --> ConfigFile
    ConfigLoader --> Agentic
    ConfigLoader --> FastAPI
    ConfigLoader --> Streamlit

    %% Cross-Cutting Concerns
    Logger["Logging Module"]:::cross
    Exception["Exception Handler"]:::cross
    click Logger "https://github.com/aryangupta1211/agentic-trip-planner/blob/master/logger/logging.py"
    click Exception "https://github.com/aryangupta1211/agentic-trip-planner/blob/master/exception/exception_handling.py"
    Logger --> Streamlit
    Logger --> FastAPI
    Logger --> Agentic
    Logger --> WeatherTool
    Exception --> Streamlit
    Exception --> FastAPI
    Exception --> Agentic
    Exception --> WeatherTool

    %% External APIs
    subgraph "External APIs"
        direction TB
        WeatherAPI["Weather API"]:::external
        HotelAPI["Hotel Pricing API"]:::external
        CurrencyAPI["Currency Exchange API"]:::external
        PlacesAPI["Places API"]:::external
    end
    WeatherUtil -->|"HTTP Request"| WeatherAPI
    CurrencyUtil -->|"HTTP Request"| CurrencyAPI
    PlaceUtil -->|"HTTP Request"| PlacesAPI
    ExpenseUtil -->|"simulated pricing"| HotelAPI
    WeatherAPI -->|"JSON Response"| WeatherUtil
    CurrencyAPI -->|"JSON Response"| CurrencyUtil
    PlacesAPI -->|"JSON Response"| PlaceUtil
    HotelAPI -->|"JSON Response"| ExpenseUtil

    %% Response back to user
    SaveUtil --> FastAPI
    Agentic --> FastAPI
    FastAPI -->|"JSON Response"| Streamlit

    %% Experimental Notebook
    Notebook["Notebook Prototypes"]:::external
    click Notebook "https://github.com/aryangupta1211/agentic-trip-planner/blob/master/notebook/experiments.ipynb"

    %% Styles
    classDef frontend fill:#cfe2f3,stroke:#0b5394,color:#0b5394;
    classDef api fill:#d9ead3,stroke:#38761d,color:#38761d;
    classDef orchestration fill:#d0e0e3,stroke:#1155cc,color:#1155cc;
    classDef prompt fill:#ead1dc,stroke:#a64d79,color:#a64d79;
    classDef tools fill:#f9cb9c,stroke:#b45f06,color:#b45f06;
    classDef util fill:#ffe599,stroke:#b37300,color:#b37300;
    classDef config fill:#eeeeee,stroke:#666666,color:#666666;
    classDef cross fill:#cccccc,stroke:#666666,color:#666666;
    classDef external fill:#ffffff,stroke:#999999,color:#555555,stroke-dasharray: 5 5;
```
