# saad-azi/crewai-trip-planner architecture

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

- Interactive diagram: https://gitdiagram.com/saad-azi/crewai-trip-planner
- Repository: https://github.com/saad-azi/crewai-trip-planner

## Overview

##### Project type and purpose
- This is a Python-based, command-line Trip Planning Assistant. It’s an open-source utility (packaged with Poetry) that orchestrates multiple “agents” to explore countries, explore cities, track expenses, and build a trip itinerary.

##### File structure
- Top-level files:
- pyproject.toml – Poetry configuration & dependencies
- README.md – project overview & usage
- tests/ – unit tests
- Package directory: trip_planner/
- main.py – entry point & CLI parsing
- agents.py – definitions of CountryExplorerAgent, CityExplorerAgent, ExpensesTrackerAgent, TripPlannerAgent
- tasks.py – orchestration logic / workflow controller
- tools.py – utility functions & API‐wrappers (e.g., HTTP clients, data processors)

##### Inspect the README for architecture hints
- The README enumerates four agent types and shows the expected input/output flow: a user issues a command → agents fetch or compute data → consolidated plan is returned.
- No database is listed; state is held in memory or serialized at runtime. External integrations (flight cost APIs, map services) live in tools.py.

##### Detail and coverage
- Every module (main.py, tasks.py, agents.py, tools.py).
- Tests folder as a separate validation layer.
- That new agents or tools can be dropped into the package folder and wired into the Orchestrator with minimal changes.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Code Modules
    CLI["User CLI\n(main.py)"]:::code
    Orchestrator["Orchestrator\n(tasks.py)"]:::code
    Agents["Agent Modules\n(agents.py)"]:::code
    Tools["Utility Layer\n(tools.py)"]:::code

    %% External Services
    External["External Services\n(flight, map, currency APIs)"]:::external

    %% Supporting Components
    Tests["Test Suite\ntests/"]:::tests
    Config["Project Config\n(pyproject.toml)"]:::datastore
    Docs["Project Docs\n(README.md)"]:::datastore

    %% Main Flow
    CLI -->|"trip parameters"| Orchestrator
    Orchestrator -->|"sequence calls"| Agents
    Agents -->|"uses API clients"| Tools
    Tools -->|"HTTP requests"| External
    External -->|"API responses"| Tools
    Tools -->|"returns data"| Agents
    Agents -->|"agent results"| Orchestrator
    Orchestrator -->|"TripPlan"| CLI

    %% Validation Flow
    Tests -->|"validates"| CLI
    Tests -->|"validates"| Orchestrator
    Tests -->|"validates"| Agents
    Tests -->|"validates"| Tools

    %% Documentation & Config
    Config --- CLI
    Config --- Orchestrator
    Config --- Agents
    Config --- Tools
    Docs --- CLI
    Docs --- Orchestrator
    Docs --- Agents
    Docs --- Tools

    %% Click Events
    click CLI "https://github.com/saad-azi/crewai-trip-planner/blob/main/trip_planner/main.py"
    click Orchestrator "https://github.com/saad-azi/crewai-trip-planner/blob/main/trip_planner/tasks.py"
    click Agents "https://github.com/saad-azi/crewai-trip-planner/blob/main/trip_planner/agents.py"
    click Tools "https://github.com/saad-azi/crewai-trip-planner/blob/main/trip_planner/tools.py"
    click External "https://github.com/saad-azi/crewai-trip-planner/blob/main/trip_planner/tools.py"
    click Tests "https://github.com/saad-azi/crewai-trip-planner/tree/main/tests/"
    click Config "https://github.com/saad-azi/crewai-trip-planner/blob/main/pyproject.toml"
    click Docs "https://github.com/saad-azi/crewai-trip-planner/blob/main/README.md"

    %% Styles
    classDef code fill:#D6EAF8,stroke:#21618C,color:#1B4F72;
    classDef external fill:#D5F5E3,stroke:#239B56,color:#196F3D;
    classDef datastore fill:#E5E8E8,stroke:#707B7C,color:#424949;
    classDef tests fill:#FADBD8,stroke:#C0392B,color:#78281F;
```
