anyway/backend/src/README.md

Overview of backend/src

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 (POI) or landmark in the context of a trip. It stores various attributes like the landmark's name, type, location (latitude and longitude), and its OpenStreetMap (OSM) details such as OSM type and ID.
  • It also includes other optional fields like image URLs, website links, and descriptions. Additionally, the class has properties to track if the landmark is a "must-visit" or "must-avoid," its attractiveness score, and whether it is a secondary or less significant attraction.
  • Each Landmark has a unique identifier (UUID), making it possible to track and link landmarks in different trip plans.

• 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, and additional fields such as max_time_minute and detour_tolerance_minute allow customization of the trip's duration and allowed detours.

• Trip:

  • The Trip class represents the complete travel plan generated by the system. It holds key information like the trip's total time, a unique trip identifier (UUID), and the first landmark's unique ID.
  • The class also includes a method, from_linked_landmarks, which allows creating a Trip from a LinkedLandmarks object (an optimized sequence of landmarks).

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

This folder includes utility functions and helper modules that provide commonly used functionality across the project. These utilities streamline processes like logging, formatting, and error handling.

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.