This project is structured into several components that handle different aspects of the application's functionality. Below is a high-level overview of each folder and the key Python files in the |src| directory.

Folders

src/optimization

This folder contains modules related to the optimization algorithm used to compute the optimal trip. It comprises the optimizer for the first rough trip and a refiner to include less famous landmarks as well.

src/overpass

This folder handles interactions with the Overpass API, including constructing and sending queries, caching responses, and parsing results from the Overpass database.

src/parameters

The modules in this folder define and manage parameters for various parts of the application. This includes configuration values for the optimizer or the list of selectors for Overpass queries.

src/structs

This folder defines the commonly used data structures used within the project. The models leverage Pydantic's BaseModel to ensure data validation, serialization, and easy interaction between different components of the application. The main classes are:

Landmark:
- Represents a point of interest in the context of a trip. It stores various attributes like the landmark's name, type, location (latitude and longitude), and its OSM details.
- It also includes other optional fields like image URLs, website links, and descriptions. Additionally, the class has properties to track its attractiveness score or elative importance.
Preferences:
- This class captures user-defined preferences needed to personalize a trip. Preferences are provided for sightseeing (history and culture), nature (parks and gardens), and shopping. These preferences guide the trip optimization process.
Trip:
- The Trip class represents the complete travel plan generated by the system. It holds key information like the trip's total time and the first landmark's UUID.

src/tests

This folder contains unit tests and test cases for the application's various modules. It is used to ensure the correctness and stability of the code.

src/utils

The utils folder contains utility classes and functions that provide core functionality for the application. The main component in this folder is the LandmarkManager, which is central to the process of fetching and organizing landmarks.

LandmarkManager:
- The LandmarkManager is responsible for fetching landmarks from OpenStreetMap (via the Overpass API) and managing their classification based on user preferences. It processes raw geographical data, filters landmarks into relevant categories (such as sightseeing, nature, shopping), and prioritizes them for trip planning.

Files

src/cache.py

This file manages the caching mechanisms used throughout the application. It defines the caching strategy for storing and retrieving data, improving the performance of repeated operations by avoiding redundant API calls or computations.

src/constants.py

This module defines global constants used throughout the project. These constants may include API endpoints, fixed configuration values, or reusable strings and integers that need to remain consistent.

src/logging_config.py

This file configures the logging system for the application. It defines how logs are formatted, where they are output (e.g., console or file), and the logging levels (e.g., debug, info, error).

src/main.py

This file contains the main application logic and API endpoints for interacting with the system. The application is built using the FastAPI framework, which provides several endpoints for creating trips, fetching trips, and retrieving landmarks or nearby facilities. The key endpoints include:

POST /trip/new:
- This endpoint allows users to create a new trip by specifying preferences, start coordinates, and optionally end coordinates. The preferences guide the optimization process for selecting landmarks.
- Returns: A Trip object containing the optimized route, landmarks, and trip details.
GET /trip/{trip_uuid}:
- This endpoint fetches an already generated trip by its unique identifier (trip_uuid). It retrieves the trip data from the cache.
- Returns: A Trip object corresponding to the given trip_uuid.
GET /landmark/{landmark_uuid}:
- This endpoint retrieves a specific landmark by its unique identifier (landmark_uuid) from the cache.
- Returns: A Landmark object containing the details of the requested landmark.
POST /toilets/new:
- This endpoint searches for public toilets near a specified location within a given radius. The location and radius are passed as query parameters.
- Returns: A list of Toilets objects located within the specified radius of the provided coordinates.