# rabdulsal/aitinerary architecture

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

- Interactive diagram: https://gitdiagram.com/rabdulsal/aitinerary
- Repository: https://github.com/rabdulsal/aitinerary

## Overview

##### Project Type & Overall Purpose
- This is a full-stack web application designed to generate intelligent, personalized travel itineraries.
- The frontend interacts with users via forms and visualization components (maps, tables, PDF export) while the backend processes data, queries external APIs, and schedules travel plans.

##### Main Components
A. Frontend:
- React application under the “frontend” directory.
- ItineraryForm: Captures user input (location, date range, preferences).
- ItineraryMap: Visualizes routes and locations (integrates with Google Maps API).
- ItineraryTable: Displays the schedule in a time-slot table.
- PDFExport: Handles PDF generation for the itinerary.
- Use of API service calls made from “frontend/src/services/api.js” where the data is sent to/received from the backend.
- Supporting technologies like Vite, Tailwind CSS, and ESLint for configuration.

B. Backend:
- Flask application found in “backend/app.py” and “backend/wsgi.py”.
- Core service modules:
- GoogleService (for handling Google Places, distance calculation, autocomplete etc.)
- YelpService (for restaurant and business recommendations)
- WeatherService (for fetching weather data that influences itinerary planning)
- SchedulerService (for generating optimized daily schedules)
- How these service modules are part of the overall backend processing workflow.

C. External Services/Dependencies:
- External APIs:
- Google Maps/Places API for location details, photos, and distance calculations.
- Yelp API for venue and business recommendations.
- OpenWeather (or weather-based API) for forecast and outdoor activity planning.
- Demonstrate that these APIs are queried by the corresponding backend service modules.

##### Data Flow & Interactions
- User Input goes into ItineraryForm.
- Data is validated and then sent via an API call (using the “frontend/src/services/api.js”) to the Flask backend.
- Within the Backend:
- The backend receives the data then coordinates fetching information from Google, Yelp, and weather APIs.
- The Scheduler service takes these inputs and generates an optimized itinerary.
- Response Flow:
- The backend returns a structured itinerary JSON.
- The frontend receives the data and populates the ItineraryMap, ItineraryTable, and offers PDF export.

##### Architectural Patterns & Principles
- Separation of concerns: clear division between frontend (presentation and user interaction) and backend (business logic and data processing).
- Microservices-like modularization in the backend: each external service (Google, Yelp, Weather) is encapsulated within its own service module.
- Clear API-driven communication (RESTful endpoints).
- Use dependency injection (or similar design patterns in Flask) to keep components decoupled.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User"]:::external

    subgraph "Frontend"
        ITF["ItineraryForm"]:::frontend
        API["API Service"]:::frontend
        ITM["ItineraryMap"]:::frontend
        ITT["ItineraryTable"]:::frontend
        PDF["PDFExport"]:::frontend
    end

    subgraph "Backend"
        FLASK["Flask Application"]:::backend
        WSGI["WSGI Configuration"]:::backend
        GS["GoogleService"]:::backend
        YS["YelpService"]:::backend
        WS["WeatherService"]:::backend
        SS["SchedulerService"]:::backend
    end

    subgraph "External APIs"
        GMAP["Google Maps/Places API"]:::external
        YAP["Yelp API"]:::external
        WAP["Weather API"]:::external
    end

    %% Data Flow
    User -->|"submits"| ITF
    ITF -->|"data"| API
    API -->|"RESTCall"| FLASK

    %% Backend internal calls
    FLASK -->|"calls"| GS
    GS -->|"query"| GMAP
    GMAP -->|"response"| GS

    FLASK -->|"calls"| YS
    YS -->|"query"| YAP
    YAP -->|"response"| YS

    FLASK -->|"calls"| WS
    WS -->|"query"| WAP
    WAP -->|"response"| WS

    FLASK -->|"schedules"| SS
    SS -->|"itinerary"| FLASK

    FLASK -->|"uses"| WSGI
    FLASK -->|"response"| API

    %% Frontend response handling
    API -->|"populates"| ITM
    API -->|"populates"| ITT
    API -->|"populates"| PDF
    ITM -->|"display"| User
    ITT -->|"display"| User
    PDF -->|"download"| User

    %% Click Events for Component Mapping
    click ITF "https://github.com/rabdulsal/aitinerary/blob/main/frontend/src/components/ItineraryForm.jsx"
    click ITM "https://github.com/rabdulsal/aitinerary/blob/main/frontend/src/components/ItineraryMap.jsx"
    click ITT "https://github.com/rabdulsal/aitinerary/blob/main/frontend/src/components/ItineraryTable.jsx"
    click PDF "https://github.com/rabdulsal/aitinerary/blob/main/frontend/src/components/PDFExport.jsx"
    click API "https://github.com/rabdulsal/aitinerary/blob/main/frontend/src/services/api.js"
    click FLASK "https://github.com/rabdulsal/aitinerary/blob/main/backend/app.py"
    click WSGI "https://github.com/rabdulsal/aitinerary/blob/main/backend/wsgi.py"
    click GS "https://github.com/rabdulsal/aitinerary/blob/main/backend/services/google_service.py"
    click YS "https://github.com/rabdulsal/aitinerary/blob/main/backend/services/yelp_service.py"
    click WS "https://github.com/rabdulsal/aitinerary/blob/main/backend/services/weather_service.py"
    click SS "https://github.com/rabdulsal/aitinerary/blob/main/backend/services/scheduler.py"

    %% Styles for clarity
    classDef frontend fill:#a8d5ff,stroke:#333,stroke-width:2px;
    classDef backend fill:#ffcccb,stroke:#333,stroke-width:2px;
    classDef external fill:#c1f2c2,stroke:#333,stroke-width:2px;
```
