Merge pull request 'backend/better-README' (#53) from backend/better-README into main

Reviewed-on: #53

README.md

@@ -15,7 +15,7 @@ This project is divided into two main components: a frontend and a backend. The
 See the [frontend README](frontend/README.md) for more information. The application is centered around its map view, which displays the user's itinerary. This is based on the Google Maps API. 
 
 ### Backend
-See the [backend README](backend/README.md) for more information. The backend is responsible for generating the itinerary based on the user's preferences and constraints. Rather than using google maps, we use the OpenStreetMap API, which is much more flexible.
+See the [backend README](backend/README.md) for more information. The backend is responsible for generating the itinerary based on the user's preferences and constraints. Rather than using google maps, we use the OpenStreetMap database through the Overpass API, which is much more flexible.
 
 
 ## Getting Started
@@ -24,6 +24,8 @@ Refer to the READMEs in the `frontend` and `backend` directories for instruction
     - `google_maps_flutter` plugin
 - Python 3
     - `fastapi`
+    - `numpy`
+    - `pydantic`
 - Docker
 
 

backend/README.md

@@ -38,7 +38,19 @@ To deploy the backend docker container, we use kubernetes. Modifications to the
 
 The deployment configuration is included as a submodule in the `deployment` directory. The standalone repository is under [https://git.kluster.moll.re/anydev/anyway-backend-deployment/](https://git.kluster.moll.re/anydev/anyway-backend-deployment/).
 
-
 ## Development
-TBD
 
+The backend application is structured around the `src` directory, which contains the core components for handling route optimization and API logic. Development generally involves working with key modules such as the optimization engine, Overpass API integration, and utilities for managing landmarks and trip data.
+
+### Key Areas:
+- **API Endpoints**: The main interaction with the backend is through the endpoints defined in `src/main.py`. FastAPI simplifies the creation of RESTful services that manage trip and landmark data.
+- **Optimization Logic**: The trip optimization and refinement are handled in the `src/optimization` module. This is where the core algorithms are implemented.
+- **Landmark Management**: Fetching and prioritizing points of interest (POIs) based on user preferences happens in `src/utils/LandmarkManager`. 
+- **Testing**: The `src/tests` directory includes tests in various scenarii, ensuring that the logic works as expected.
+
+For detailed information, refer to the [src README](backend/src/README.md).
+
+### Running the Application:
+To run the backend locally, ensure that the virtual environment is activated and all dependencies are installed as outlined in the "Getting Started" section. You can start the FastAPI server with:
+```bash
+uvicorn src.main:app --reload

backend/src/README.md

@@ -0,0 +1,65 @@
+# 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 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.

backend/src/utils/landmarks_manager.py

@@ -168,7 +168,6 @@ class LandmarkManager:
             bbox (tuple[float, float, float, float]): The bounding box coordinates (around:radius, center_lat, center_lon).
             amenity_selector (dict): The Overpass API query selector for the desired landmark type. 
             landmarktype (str): The type of the landmark (e.g., 'sightseeing', 'nature', 'shopping').
-            score_function (callable): The function to compute the score of the landmark based on its attributes.
 
         Returns:
             list[Landmark]: A list of Landmark objects that were fetched and filtered based on the provided criteria.
@@ -177,7 +176,6 @@ class LandmarkManager:
             - Landmarks are fetched using Overpass API queries.
             - Selectors are translated from the dictionary to the Overpass query format. (e.g., 'amenity'='place_of_worship')
             - Landmarks are filtered based on various conditions including tags and type.
-            - Scores are assigned to landmarks based on their attributes and surrounding elements.
         """
         return_list = []