# mr-aicoder/ai_trip_planner architecture

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

- Interactive diagram: https://gitdiagram.com/mr-aicoder/ai_trip_planner
- Repository: https://github.com/mr-aicoder/ai_trip_planner

## Overview

##### Project type and purpose
- This is a Python-based “AI Trip Planner” tool that exposes two interfaces:
a) a FastAPI-based HTTP service (main.py launched with uvicorn)
b) an interactive Streamlit UI (streamlit_app.py)
- It uses an agentic workflow to orchestrate calls to various helper “tools” (e.g., currency conversion, weather lookup, place search) and returns trip plans or documents.

##### File structure
Top-level directories and files:
- .devcontainer/ – VS Code dev-container config
- main.py – FastAPI app entry point
- streamlit_app.py – Streamlit front-end entry point
- agent/ – business-logic orchestrator (agentic_workflow.py)
- tools/ – domain-specific tool modules (weather, currency, expenses, place_search, arithmetic)
- utils/ – low-level helper functions (model loading, API wrappers, document saving)
- config/ – YAML configuration loader
- exception/ – custom exception handling
- logger/ – centralized logging
- prompt_library/ – templates for LLM prompts
- notebook/ – Jupyter notebook for experiments
- setup.py, pyproject.toml, requirements.txt – packaging and dependencies

##### README for additional insights
- Uses the “uv” tool to manage virtual environments and dependencies.
- FastAPI is served via uvicorn on port 8000.
- Streamlit is a second front-end.
- No database folder—likely ephemeral in-memory or file-based storage via utils/save_to_document.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        SUI["Streamlit App"]:::frontend
        HTTP["HTTP Client"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        API["FastAPI App"]:::api
    end

    %% Business Logic
    subgraph "Business Logic"
        direction TB
        Agent["Agentic Workflow"]:::business
    end

    %% Tools Layer
    subgraph "Tools"
        direction TB
        WTool["WeatherInfoTool"]:::business
        CTool["CurrencyConversionTool"]:::business
        ETool["ExpenseCalculatorTool"]:::business
        PTool["PlaceSearchTool"]:::business
        ATool["ArithmeticOpTool"]:::business
    end

    %% Utilities Layer
    subgraph "Utilities"
        direction TB
        ConfigLoader["Config Loader"]:::infra
        ModelLoader["Model Loader"]:::infra
        WeatherWrapper["Weather API Wrapper"]:::infra
        CurrencyWrapper["Currency API Wrapper"]:::infra
        PlaceWrapper["Place Search API Wrapper"]:::infra
        ExpenseUtil["Expense Calculation Utility"]:::infra
        DocSaver["Document Saver"]:::infra
        PromptLib["Prompt Library"]:::infra
    end

    %% Cross-Cutting Concerns
    subgraph "Cross-Cutting"
        direction TB
        Logger["Logging Module"]:::infra
        Exception["Exception Handling"]:::infra
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        LLM["LLM API"]:::external
        WeatherService["Weather REST API"]:::external
        CurrencyService["Currency Rates API"]:::external
        MapsService["Maps/Place Search API"]:::external
    end

    %% Relationships
    SUI -->|"User Interaction"| API
    HTTP -->|"HTTP Request"| API
    API -->|"dispatch to"| Agent
    Agent -->|"invoke"| WTool
    Agent -->|"invoke"| CTool
    Agent -->|"invoke"| ETool
    Agent -->|"invoke"| PTool
    Agent -->|"invoke"| ATool

    WTool -->|"calls"| WeatherWrapper
    CTool -->|"calls"| CurrencyWrapper
    PTool -->|"calls"| PlaceWrapper
    ETool -->|"calls"| ExpenseUtil
    ATool -->|"uses"| ModelLoader

    Agent -->|"uses templates from"| PromptLib
    Agent -->|"save docs via"| DocSaver

    ConfigLoader -->|"injects config into"| API
    ConfigLoader -->|"provides config to"| Agent

    WeatherWrapper -->|"REST"| WeatherService
    CurrencyWrapper -->|"REST"| CurrencyService
    PlaceWrapper -->|"REST"| MapsService
    ModelLoader -->|"REST"| LLM

    API -->|"logs via"| Logger
    Agent -->|"logs via"| Logger
    API -->|"errors to"| Exception
    Agent -->|"errors to"| Exception

    %% Click Events
    click SUI "https://github.com/mr-aicoder/ai_trip_planner/blob/main/streamlit_app.py"
    click API "https://github.com/mr-aicoder/ai_trip_planner/blob/main/main.py"
    click Agent "https://github.com/mr-aicoder/ai_trip_planner/blob/main/agent/agentic_workflow.py"
    click WTool "https://github.com/mr-aicoder/ai_trip_planner/blob/main/tools/weather_info_tool.py"
    click CTool "https://github.com/mr-aicoder/ai_trip_planner/blob/main/tools/currency_conversion_tool.py"
    click ETool "https://github.com/mr-aicoder/ai_trip_planner/blob/main/tools/expense_calculator_tool.py"
    click PTool "https://github.com/mr-aicoder/ai_trip_planner/blob/main/tools/place_search_tool.py"
    click ATool "https://github.com/mr-aicoder/ai_trip_planner/blob/main/tools/arthamatic_op_tool.py"
    click ConfigLoader "https://github.com/mr-aicoder/ai_trip_planner/blob/main/utils/config_loader.py"
    click PromptLib "https://github.com/mr-aicoder/ai_trip_planner/blob/main/prompt_library/prompt.py"
    click ModelLoader "https://github.com/mr-aicoder/ai_trip_planner/blob/main/utils/model_loader.py"
    click WeatherWrapper "https://github.com/mr-aicoder/ai_trip_planner/blob/main/utils/weather_info.py"
    click CurrencyWrapper "https://github.com/mr-aicoder/ai_trip_planner/blob/main/utils/currency_converter.py"
    click PlaceWrapper "https://github.com/mr-aicoder/ai_trip_planner/blob/main/utils/place_info_search.py"
    click ExpenseUtil "https://github.com/mr-aicoder/ai_trip_planner/blob/main/utils/expense_calculator.py"
    click DocSaver "https://github.com/mr-aicoder/ai_trip_planner/blob/main/utils/save_to_document.py"
    click Logger "https://github.com/mr-aicoder/ai_trip_planner/blob/main/logger/logging.py"
    click Exception "https://github.com/mr-aicoder/ai_trip_planner/blob/main/exception/exceptiohandling.py"
    click ConfigLoader "https://github.com/mr-aicoder/ai_trip_planner/blob/main/config/config.yaml"

    %% Styles
    classDef frontend fill:#D0E8F2,stroke:#036; 
    classDef api fill:#A8D5E2,stroke:#024; 
    classDef business fill:#C2F0C2,stroke:#070; 
    classDef infra fill:#FCE5CD,stroke:#D65; 
    classDef external fill:#E2E2E2,stroke:#666;
```
