Fix Google Maps API Key Configuration and Add Support for Environment…

[L0rd008]

This pull request addresses several issues with the route optimizer service:

1. Google Maps API Key Configuration:

   • Modified the settings module to handle missing API keys gracefully
   • Added fallback to dummy keys for testing environments
   • Implemented proper environment variable loading

2. Environment Variable Setup:

   • Added support for loading configuration from env_var.env file
   • Created clear documentation for required environment variables

3. Important Note:

   • The Google Maps API key should be added to the env_var.env file in the root directory
   • Format: GOOGLE_MAPS_API_KEY=your_api_key_here
   • The main error in the test output was related to the missing Google Maps API key, which was causing a ValueError in route_optimizer/settings.py

4. What This PR Does Not Change:

   • No modifications to the pathfinding logic or algorithms
   • Core optimization functionality remains the same

[L0rd008]

Route Optimizer Module

Overview

The Route Optimizer module is a comprehensive Django app designed to calculate optimal routes for a fleet of vehicles to make deliveries (or pickups) to a set of locations. It considers various constraints such as vehicle capacities, time windows, traffic conditions, and operational costs. The module can use either local calculations (like Haversine for distance) or external APIs (like Google Maps Distance Matrix API) for more accurate real-world data. It also supports dynamic rerouting in response to real-time events.

---

Core Files (route_optimizer/core/)

The core directory contains the fundamental algorithms, data type definitions, and constants that form the backbone of the route optimization logic.

1. constants.py (Logistics\route_optimizer\core\constants.py)

• Functionality:
  • Defines various constants used throughout the optimization process.
  • Includes scaling factors (e.g., DISTANCE_SCALING_FACTOR, CAPACITY_SCALING_FACTOR, TIME_SCALING_FACTOR) required by OR-Tools to work with integer arithmetic.
  • Specifies safety bounds for distance and time values (e.g., MAX_SAFE_DISTANCE, MAX_SAFE_TIME).
• Important Points:
  • Consistency is Key: Ensure these constants are consistently used and understood across all modules, especially between the main code and tests. Mismatches in values like MAX_SAFE_DISTANCE have caused issues previously.
  • Scaling Factor Impact: The scaling factors directly affect the precision and behavior of the OR-Tools solver. Adjustments might be needed based on the typical range of input values.
  • The commented-out section suggests different scaling strategies might have been considered; the current active set is what's in use.

2. dijkstra.py (Logistics\route_optimizer\core\dijkstra.py)

• Functionality:
  • Provides an implementation of Dijkstra's algorithm.
  • DijkstraPathFinder class offers:
    • calculate_shortest_path(graph, start, end): Finds the shortest path between a single pair of nodes.
    • calculate_all_shortest_paths(graph, nodes): Calculates shortest paths between all specified pairs of nodes.
    • _validate_non_negative_weights(graph): Ensures no negative edge weights.
• Important Points:
  • Negative Weights: Raises a ValueError for negative weights. If negative weights are needed, an alternative like Bellman-Ford would be required.
  • Graph Representation: Expects graph as a dictionary of dictionaries (adjacency list with weights).
  • Use Case: Used by PathAnnotator for detailed path segments when not using external APIs.

3. distance_matrix.py (Logistics\route_optimizer\core\distance_matrix.py)

• Functionality:
  • DistanceMatrixBuilder class for creating and managing distance matrices.
  • Supports Haversine, Euclidean, and Google Maps Distance Matrix API calculations.
  • Includes caching (DistanceMatrixCache model), API request retries, address formatting, response processing, matrix sanitization (_sanitize_distance_matrix), traffic factor application (add_traffic_factors, _apply_traffic_safely), and matrix-to-graph conversion.
• Important Points:
  • API Key: Relies on GOOGLE_MAPS_API_KEY from settings.py.
  • API Quotas: Caching is vital to manage API usage.
  • Fallback Behavior: Falls back to Haversine if API fails.
  • Sanitization: _sanitize_distance_matrix is crucial for clean numerical data, replacing NaN, inf, etc., with MAX_SAFE_DISTANCE or 0.
  • Traffic Application: _apply_traffic_safely includes bounds checking for traffic factors.

4. ortools_optimizer.py (Logistics\route_optimizer\core\ortools_optimizer.py)

• Functionality:
  • ORToolsVRPSolver class for solving Vehicle Routing Problems (VRP) using Google OR-Tools.
  • solve(...): Basic VRP with capacity constraints.
  • solve_with_time_windows(...): VRP with time window constraints.
  • Handles vehicle start/end locations, capacities, and cost minimization.
• Important Points:
  • Integer Scaling: Critical for OR-Tools; uses scaling factors from constants.py.
  • Depot Handling: depot_index is fundamental.
  • Callbacks: Distance, demand, and time callbacks are essential.
  • Solution Interpretation: Output is parsed into OptimizationResult.
  • Time Limits: Configurable time_limit_seconds.
  • Empty Problem: Creates depot-to-depot routes if no deliveries.

5. types_1.py (Logistics\route_optimizer\core\types_1.py)

• Functionality:
  • Defines core Data Transfer Objects (DTOs) using dataclass:
    • Location: Geographic point with coordinates, depot status, time windows, service time.
    • OptimizationResult: Standardized output format.
    • RouteSegment: Details of a path segment.
    • DetailedRoute: Comprehensive vehicle route description.
    • ReroutingInfo: Information for rerouting operations.
  • validate_optimization_result(result): Validates OptimizationResult structure.
• Important Points:
  • Standardization: Ensures consistent data handling.
  • Validation: validate_optimization_result is key for data integrity.
  • Mutability: Dataclasses are mutable by default.

---

Services Files (route_optimizer/services/)

The services directory orchestrates core logic and handles higher-level tasks.

1. depot_service.py (Logistics\route_optimizer\services\depot_service.py)

• Functionality:
  • DepotService class for depot location utilities.
  • get_nearest_depot(locations): Identifies a depot. Defaults to the first depot found or the first location.
  • find_depot_index(locations): Returns index of the depot. Defaults to 0.
• Important Points:
  • Depot Assumption: Simple logic for multiple depots (returns first). Fallback to the first location if no explicit depot.

2. external_data_service.py (Logistics\route_optimizer\services\external_data_service.py)

• Functionality:
  • ExternalDataService for fetching external data (traffic, weather, roadblocks).
  • Currently provides mock data if use_mocks is true or real APIs are unimplemented.
  • Includes helpers for mock data generation and combining factors.
• Important Points:
  • Mock Data: Real API integrations needed for production.
  • API Keys: Would require key management if real APIs were used.

3. optimization_service.py (Logistics\route_optimizer\services\optimization_service.py)

• Functionality:
  • OptimizationService: Main orchestrator for route optimization.
  • optimize_routes(...): Primary method. Validates inputs, creates/sanitizes distance matrix, applies traffic, determines depot, calls VRP solver, converts/enriches result with detailed paths and summary statistics.
  • Helper methods for input validation, path/stats addition, result conversion, matrix sanitization.
• Important Points:
  • Central Orchestrator: Ties many components together.
  • Error Handling: General try-except and specific input validation.
  • API Usage Control: use_api flag and USE_API_BY_DEFAULT setting.
  • Result Enrichment: Multi-step process for detailed results.
  • Backward Compatibility: _add_detailed_paths handles dict and OptimizationResult.

4. path_annotation_service.py (Logistics\route_optimizer\services\path_annotation_service.py)

• Functionality:
  • PathAnnotator class for adding detailed segment-by-segment path information.
  • annotate(result, graph_or_matrix): Uses a path_finder (e.g., DijkstraPathFinder) for segment details.
  • Accepts graph or distance matrix. Handles dict and OptimizationResult.
  • _add_summary_statistics helper ensures detailed_routes structure.
• Important Points:
  • Dependency: Relies on an injected path_finder.
  • Error Handling: Logs errors and adds placeholders for failed path calculations.

5. rerouting_service.py (Logistics\route_optimizer\services\rerouting_service.py)

• Functionality:
  • ReroutingService for dynamic route adjustments.
  • Methods: reroute_for_traffic, reroute_for_delay, reroute_for_roadblock.
  • Helpers: _get_remaining_deliveries, _update_vehicle_positions.
  • Relies on OptimizationService for re-optimization.
• Important Points:
  • State Management: Accurate current state (completed deliveries, vehicle positions) is crucial; current helpers are placeholders.
  • Complexity: Rerouting triggers a new, potentially intensive optimization.

6. route_stats_service.py (Logistics\route_optimizer\services\route_stats_service.py)

• Functionality:
  • RouteStatsService calculates and adds statistics to the optimization result.
  • add_statistics(result, vehicles): Calculates vehicle/total costs, aggregates total stops/distance/vehicles used. Handles OptimizationResult and dict.
• Important Points:
  • Cost Calculation: Uses fixed_cost and cost_per_km from Vehicle objects.
  • Data Dependency: Needs detailed_routes with segment distances for accurate costs.

7. traffic_service.py (Logistics\route_optimizer\services\traffic_service.py)

• Functionality:
  • TrafficService for traffic-related information.
  • apply_traffic_factors(...): Wraps DistanceMatrixBuilder.add_traffic_factors.
  • create_road_graph(locations): Creates a road network graph. Potential integration point for Google Maps API for accurate topology if API key is used. Currently basic.
• Important Points:
  • API Integration: create_road_graph is key for potential Google Maps API use for detailed pathing when OptimizationService's use_api_flag is true.

8. vrp_solver.py (Logistics\route_optimizer\services\vrp_solver.py)

• Functionality:
  • Contains a standalone solve_with_time_windows(...) function, similar to the method in core/ortools_optimizer.py.
• Important Points:
  • Redundancy/Placement: May need refactoring. core/ortools_optimizer.py should be the primary OR-Tools solver implementation. This might be legacy or a specialized helper.

---

Settings File (route_optimizer/settings.py)

• Logistics\route_optimizer\settings.py
• Functionality:
  • Manages app configurations. Loads environment variables from env_var.env.
  • Defines GOOGLE_MAPS_API_KEY, GOOGLE_MAPS_API_URL, USE_API_BY_DEFAULT.
  • API request settings: MAX_RETRIES, BACKOFF_FACTOR, RETRY_DELAY_SECONDS.
  • CACHE_EXPIRY_DAYS.
  • TESTING flag.
• Important Points:
  • Environment Variables: Critical for API keys and sensitive data. env_loader assists local setup.
  • API Key Security: GOOGLE_MAPS_API_KEY is vital; .env file must be in .gitignore.
  • Test Mode: Allows different configurations for testing.

---

Utils Files (route_optimizer/utils/)

1. env_loader.py (Logistics\route_optimizer\utils\env_loader.py)

• Functionality:
  • load_env_from_file(file_path): Loads KEY=VALUE pairs from a file into os.environ.
• Important Points:
  • Local Development: Useful for simulating production env vars locally.
  • Security: The env file itself should be secure and not version-controlled.

2. helpers.py (Logistics\route_optimizer\utils\helpers.py)

• Functionality:
  • Collection of miscellaneous utility functions: time conversions, Haversine calculation, route formatting, basic stats calculation, distance/time matrix creation, isolated node detection, safe JSON dumps, duration formatting.
• Important Points:
  • Redundancy: Some functions might overlap with more specialized classes (e.g., Haversine vs. DistanceMatrixBuilder). Potential for refactoring.
  • Generic Utilities: Small, focused helpers for general use.

---

Other Project Files

• admin.py (Logistics\route_optimizer\admin.py): For Django admin interface. Currently empty.
• api/ directory:
  • serializers.py (Logistics\route_optimizer\api\serializers.py): DRF serializers for API data validation and conversion.
  • urls.py (Logistics\route_optimizer\api\urls.py): API URL patterns.
  • views.py (Logistics\route_optimizer\api\views.py): API views (OptimizeRoutesView, RerouteView) handling HTTP requests and responses.
• apps.py (Logistics\route_optimizer\apps.py): Django app configuration.
• migrations/: Django database migration files (e.g., for DistanceMatrixCache).
• models.py (Logistics\route_optimizer\models.py): Dataclasses for Vehicle and Delivery; Django model for DistanceMatrixCache.
• tests/: Unit and integration tests.
  • conftest.py (Logistics\route_optimizer\tests\conftest.py): Pytest configuration.
  • test_settings.py (Logistics\route_optimizer\tests\test_settings.py): Django settings for tests.
• views.py (root) (Logistics\route_optimizer\views.py): Standard Django views file, currently empty.

---

This comprehensive overview should help in understanding the structure, functionality, and key considerations of the route_optimizer module.

[Ke-vin-S]

Expect few changes

• Update your branch with the main branch, there are so many conflicts
• Do not remove test cases

[L0rd008]

Route Optimizer Module Functionality

Overview

The Route Optimizer module is a Django application engineered to compute optimal routes for a fleet of vehicles tasked with deliveries and/or pickups across a designated set of locations. It is designed to handle a variety of real-world operational constraints and features, including:

• Vehicle Constraints: Accommodates vehicle capacities, ensuring that loads do not exceed limits.
• Time Constraints: Optionally factors in time windows for deliveries and service operations at specific locations.
• Real-world Conditions: Can incorporate traffic data to provide more realistic route plans. External APIs or pre-calculated data can be used for this.
• Cost Optimization: Aims to minimize overall operational costs, which can include travel distance, fixed vehicle costs, and potentially other factors.
• Data Source Flexibility: Supports distance and time calculations through local methods (e.g., Haversine formula for straight-line distances) or by integrating with external APIs (such as the Google Maps Distance Matrix API) for more precise, real-world data.
• Dynamic Adjustments: Features capabilities for dynamic rerouting of vehicles in response to real-time events, such as emergent traffic congestion, service delays at locations, or unexpected roadblocks.

The module is architecturally divided into several key directories:

• core/: Contains fundamental algorithms, core data type definitions (DTOs), and essential constants.
• services/: Houses service classes that orchestrate complex business logic and workflows.
• api/: Manages external communication via RESTful APIs, including request handling, serialization, and response formulation.
• utils/: Provides miscellaneous helper functions and utilities.
  It also includes standard Django components like models.py for data persistence (e.g., caching), settings.py for configurations, and apps.py for app-specific Django settings.

---

Core Functionality & Modules

1. API Layer (route_optimizer/api/)

The API layer serves as the primary interface for external systems to interact with the route optimization capabilities.

• views.py (Logistics\route_optimizer\api\views.py)

  • Functionality: Contains the view logic for handling incoming HTTP requests, delegating tasks to the appropriate services, and formatting responses.
    • OptimizeRoutesView(APIView):
      • Handles POST requests to the /optimize/ endpoint.
      • Uses RouteOptimizationRequestSerializer to validate input data (locations, vehicles, deliveries, constraints).
      • Converts validated data into internal DTOs (Location, Vehicle, Delivery).
      • Invokes OptimizationService.optimize_routes() to perform the core optimization logic.
      • Processes traffic data from the request, converting it from client-friendly formats (e.g., location ID pairs or segment strings) into an index-based format expected by the OptimizationService.
      • Serializes the OptimizationResult DTO returned by the service into an HTTP response using RouteOptimizationResponseSerializer.
      • Returns HTTP 400 for service-level errors (e.g., invalid input caught by the service) or HTTP 500 for unexpected exceptions.
    • RerouteView(APIView):
      • Handles POST requests to the /reroute/ endpoint.
      • Uses ReroutingRequestSerializer to validate input, which includes the current route plan and details about the rerouting event (traffic, delay, roadblock).
      • Converts the JSON current_routes into an OptimizationResult DTO.
      • Calls the relevant method on ReroutingService (e.g., reroute_for_traffic, reroute_for_delay, reroute_for_roadblock) based on the reroute_type specified in the request.
      • Serializes the OptimizationResult DTO from the rerouting service into an HTTP response.
    • health_check(request):
      • A simple function-based view for GET requests to /health/.
      • Returns a JSON response {"status": "healthy"} to indicate the service is operational.
  • Key Methods/Logic:
    • Conversion of request data to DTOs: Location(**loc_data).
    • Service invocation: optimization_service.optimize_routes(...), rerouting_service.reroute_for_traffic(...).
    • Response generation: Response(serializer.data, status=...).
  • Important: API views are decorated with @swagger_auto_schema for automated API documentation generation (integrates with drf-yasg).

• serializers.py (Logistics\route_optimizer\api\serializers.py)

  • Functionality: Defines Django REST Framework (DRF) serializers for data validation, deserialization (request data to Python objects), and serialization (Python objects to JSON for responses).
    • Input Data Serializers:
      • LocationSerializer, VehicleSerializer, DeliverySerializer: Define the expected structure and validation rules for individual location, vehicle, and delivery objects provided in requests.
      • TrafficDataSerializer: Validates traffic data input, supporting formats like lists of location pairs with factors or dictionary of segments.
    • Request Serializers:
      • RouteOptimizationRequestSerializer: Validates the entire payload for the route optimization endpoint, including lists of locations, vehicles, deliveries, and flags like consider_traffic, consider_time_windows.
      • ReroutingRequestSerializer: Validates payloads for rerouting, including the current route plan, event type (reroute_type), and event-specific data (e.g., traffic_data, delayed_location_ids, blocked_segments).
    • Output Data Serializers:
      • RouteSegmentSerializer, VehicleRouteSerializer: Define the structure for detailed route segments and complete vehicle routes within the response.
      • ReroutingInfoSerializer, StatisticsSerializer: Structure additional metadata and statistics included in responses.
      • OptimizationResultSerializer: A base serializer for the OptimizationResult DTO, potentially used for internal representations or as a foundation. It includes a validate method that calls validate_optimization_result from core/types_1.py.
      • RouteOptimizationResponseSerializer: Defines the final structure of successful responses from optimization and rerouting endpoints. It maps the internal OptimizationResult DTO fields to a client-friendly JSON structure (e.g., OptimizationResult.detailed_routes maps to the routes field in the JSON response).
  • Important: Serializers are the first point of validation for incoming API data. They ensure data integrity before it reaches the service layer. Consistent mapping between DTOs and serializer fields is critical.

• urls.py (Logistics\route_optimizer\api\urls.py)

  • Functionality: Defines the URL routing for the API.
    • Maps URL patterns to the respective views in api/views.py.
    • Example patterns:
      • path('optimize/', OptimizeRoutesView.as_view(), name='optimize_routes_create')
      • path('reroute/', RerouteView.as_view(), name='reroute_vehicles_update')
      • path('health/', health_check, name='health_check_get')
  • Important: Uses named URL patterns for easier referencing within the Django application. The operation_id in Swagger documentation often matches these names.

2. Core Logic (route_optimizer/core/)

This directory contains the heart of the optimization engine, including algorithms, data structures, and fundamental constants.

• constants.py (Logistics\route_optimizer\core\constants.py)

  • Functionality: Central repository for global constants.
    • Scaling Factors: DISTANCE_SCALING_FACTOR, CAPACITY_SCALING_FACTOR, TIME_SCALING_FACTOR are crucial for converting floating-point numbers to integers, as required by OR-Tools.
    • Safety Bounds: MAX_SAFE_DISTANCE, MIN_SAFE_DISTANCE, MAX_SAFE_TIME, MIN_SAFE_TIME define valid ranges for distance and time values, used in sanitization and validation.
    • Delivery Priorities: Defines levels like PRIORITY_NORMAL, PRIORITY_HIGH, and a DEFAULT_DELIVERY_PRIORITY.
  • Important: Consistency in using these constants across the application (especially in services and tests) is vital for correctness and stability. The MAX_SAFE_DISTANCE is particularly important for matrix sanitization.

• types_1.py (Logistics\route_optimizer\core\types_1.py)

  • Functionality: Defines core Data Transfer Objects (DTOs) using Python's dataclass. These ensure structured and type-safe data exchange within the application.
    • Location: Represents a geographical point with attributes like id, name, latitude, longitude, is_depot, time_window_start, time_window_end, service_time.
    • OptimizationResult: The standard output format for all optimization and rerouting operations. Contains fields like status, routes (list of location ID lists), total_distance, total_cost, assigned_vehicles, unassigned_deliveries, detailed_routes (list of DetailedRoute-like dictionaries), and statistics. Includes a static method from_dict for creating an instance from a dictionary (e.g., when loading from cache).
    • RouteSegment: Describes a single leg of a route, including from_location, to_location, path (list of intermediate nodes), distance, and estimated_time.
    • DetailedRoute: A comprehensive structure for a vehicle's entire route, including vehicle_id, stops, segments, total_distance, total_time, capacity_utilization, and estimated_arrival_times.
    • ReroutingInfo: Holds metadata about a rerouting event, such as reason, traffic_factors count, completed_deliveries count, delay_locations list, and blocked_segments list.
  • Validation Function:
    • validate_optimization_result(result: Dict[str, Any]): Validates the structure of a dictionary representation of an OptimizationResult, ensuring required fields are present and have correct types. This is used by serializers.
  • Important: These DTOs are fundamental for maintaining data consistency. OptimizationResult.from_dict() is key for handling data from sources like caches or older dictionary-based outputs.

• distance_matrix.py (Logistics\route_optimizer\core\distance_matrix.py)

  • Functionality: Provides the DistanceMatrixBuilder class for creating, caching, and manipulating distance and time matrices.
    • create_distance_matrix(...): Main method to generate matrices.
      • Can use Haversine formula (default) or Euclidean for local distance calculation.
      • Can use Google Maps Distance Matrix API if use_api=True and an api_key is provided, falling back to Haversine on failure.
      • Returns a tuple: (distance_matrix_km, time_matrix_minutes_optional, location_ids_list).
    • create_distance_matrix_from_api(...): Handles Google Maps API interaction, including request construction, sending (_send_request_with_retry), response parsing (_process_api_response), and caching via DistanceMatrixCache model.
    • _sanitize_distance_matrix(matrix): Crucial for cleaning matrices: replaces NaN with MAX_SAFE_DISTANCE, inf with MAX_SAFE_DISTANCE, negative values with 0, and caps excessively large values at MAX_SAFE_DISTANCE.
    • add_traffic_factors(matrix, traffic_data): Applies traffic factors to a copy of the time matrix (or distance matrix if used as a proxy for time/cost). It calls _apply_traffic_safely.
    • _apply_traffic_safely(matrix, traffic_data): Applies traffic factors with bounds checking (e.g., factors < 1.0 are treated as 1.0, very large factors might be capped at a max_safe_factor which defaults to 5.0).
    • distance_matrix_to_graph(matrix, location_ids): Converts a 2D numpy distance matrix into a dictionary-based graph representation (adjacency list).
  • Important: Effective caching (DistanceMatrixCache model) is vital for managing API costs and performance. Matrix sanitization (_sanitize_distance_matrix) ensures robust input for solvers. Fallback mechanisms (API to Haversine) enhance reliability.

• dijkstra.py (Logistics\route_optimizer\core\dijkstra.py)

  • Functionality: Implements Dijkstra's algorithm for finding shortest paths.
    • DijkstraPathFinder class:
      • _validate_non_negative_weights(graph): Ensures graph edges have non-negative weights, raising ValueError otherwise.
      • calculate_shortest_path(graph, start, end): Finds the shortest path and distance between two nodes.
      • calculate_all_shortest_paths(graph, nodes_subset): Calculates all-pairs shortest paths for a given subset of nodes within the larger graph.
  • Important: Standard Dijkstra's algorithm; cannot handle negative edge weights. Used by PathAnnotator for generating detailed path segments when not relying on external map APIs for this.

• ortools_optimizer.py (Logistics\route_optimizer\core\ortools_optimizer.py)

  • Functionality: Contains the ORToolsVRPSolver class, which uses Google OR-Tools to solve Vehicle Routing Problems (VRP).
    • solve(...): Solves the basic Capacitated VRP (CVRP).
      • Sets up RoutingIndexManager and RoutingModel.
      • Defines distance callback (cost of travel between nodes, using scaled distances).
      • Defines demand callback (capacity consumed at each node, using scaled demands).
      • Adds capacity dimension to the model.
      • Configures search parameters (e.g., PATH_CHEAPEST_ARC, GUIDED_LOCAL_SEARCH, time_limit_seconds).
      • Calls routing.SolveWithParameters(search_parameters).
      • Processes the solution into an OptimizationResult DTO, including routes, total distance (solver's objective), assigned vehicles, and unassigned deliveries.
      • Includes logic for load balancing using SetGlobalSpanCostCoefficient on a distance-based dimension.
    • solve_with_time_windows(...): Solves VRP with Time Windows (VRPTW).
      • Similar setup to solve() but adds a time dimension.
      • Time callback includes travel time (derived from distance matrix and speed), service time at locations, and allows for waiting time if arriving before a time window opens.
      • Adds time dimension constraints based on location time windows and vehicle operating times.
      • Also processes the solution into an OptimizationResult DTO, including estimated arrival times in detailed_routes.
      • Includes logic for load balancing on the 'Time' dimension.
  • Important:
    • Integer Arithmetic: OR-Tools requires integer inputs. This class relies heavily on DISTANCE_SCALING_FACTOR, CAPACITY_SCALING_FACTOR, and TIME_SCALING_FACTOR from constants.py.
    • Depot Handling: Assumes a single depot_index is provided for all vehicles' start and end.
    • Solution Quality: Solver behavior and solution quality can be tuned via search parameters and time limits.
    • Empty Problem: If no deliveries are provided, it generates depot-to-depot routes for vehicles.
    • Constants: MAX_ROUTE_DURATION_UNSCALED, MAX_ROUTE_DISTANCE_UNSCALED, COST_COEFFICIENT_FOR_LOAD_BALANCE are defined locally in this file and influence dimension capacities and load balancing.

3. Service Layer (route_optimizer/services/)

The service layer orchestrates the core logic, acting as an intermediary between the API views and the core components.

• optimization_service.py (Logistics\route_optimizer\services\optimization_service.py)

  • Functionality: The primary service for orchestrating route optimization.
    • OptimizationService class:
      • __init__(...): Initializes with an OR-Tools solver (ORToolsVRPSolver) and a pathfinder (DijkstraPathFinder), allowing for dependency injection. Defaults to creating new instances.
      • optimize_routes(...): The main method.
        1. Input Validation: Calls _validate_inputs to check locations, vehicles, and deliveries.
        2. Caching: Generates a _generate_cache_key and attempts to retrieve results from Django's cache. If found, returns cached OptimizationResult.
        3. Matrix Creation: Calls DistanceMatrixBuilder.create_distance_matrix, deciding API vs. local calculation based on use_api flag and settings.
        4. Matrix Sanitization: Calls DistanceMatrixBuilder._sanitize_distance_matrix.
        5. Traffic Application: If consider_traffic is true and traffic_data is provided, applies it using DistanceMatrixBuilder.add_traffic_factors and re-sanitizes.
        6. Depot Identification: Uses DepotService.get_nearest_depot and DepotService.find_depot_index.
        7. VRP Solving: Invokes self.vrp_solver.solve() or self.vrp_solver.solve_with_time_windows() based on consider_time_windows.
        8. Result Conversion: Ensures the solver's output is an OptimizationResult DTO, converting from dict if necessary.
        9. Detailed Path Addition (_add_detailed_paths): If optimization is successful:
           • If use_api_flag was true, it attempts to use TrafficService.create_road_graph (which might use Google Maps API) to get a graph for path annotation.
           • Otherwise, or on API failure, it creates a graph from the distance matrix.
           • Then uses PathAnnotator(self.path_finder).annotate(...) to populate detailed_routes.
        10. Summary Statistics Addition (_add_summary_statistics): Calls RouteStatsService.add_statistics.
        11. Caching: Stores the final OptimizationResult (as a dict) in the cache.
        12. Returns the OptimizationResult DTO.
      • _validate_inputs(...): Checks for empty inputs and valid location coordinates/demands.
      • _generate_cache_key(...): Creates a cache key from input parameters.
  • Important: This service is central to the application's workflow. Error handling within optimize_routes ensures that exceptions lead to an OptimizationResult with status='error'.

• rerouting_service.py (Logistics\route_optimizer\services\rerouting_service.py)

  • Functionality: Handles dynamic adjustments to existing routes.
    • ReroutingService class:
      • __init__(...): Takes an optional OptimizationService instance, or creates one.
      • _get_remaining_deliveries(...): Filters original deliveries against completed ones.
      • _update_vehicle_positions(...): A simplified method to estimate current vehicle locations based on their last completed delivery in the current_routes plan. Updates start_location_id for Vehicle objects.
      • reroute_for_traffic(...):
        1. Updates vehicle positions and determines remaining deliveries.
        2. Calls self.optimization_service.optimize_routes with the new state and provided traffic_data.
        3. Populates ReroutingInfo in the result's statistics.
      • reroute_for_delay(...):
        1. Updates service times for Location objects based on delayed_location_ids and delay_minutes.
        2. Updates vehicle positions and determines remaining deliveries.
        3. Calls self.optimization_service.optimize_routes, typically forcing consider_time_windows=True.
        4. Populates ReroutingInfo.
      • reroute_for_roadblock(...):
        1. Modifies the effective distance matrix by setting distances for blocked_segments to float('inf'). This is done by creating a traffic_data_for_roadblocks dictionary where blocked segments get an infinite factor.
        2. Updates vehicle positions and remaining deliveries.
        3. Calls self.optimization_service.optimize_routes with consider_traffic=True and the traffic_data_for_roadblocks.
        4. Populates ReroutingInfo.
  • Important: The accuracy of rerouting heavily depends on the quality of current_routes input and the logic in _update_vehicle_positions. Rerouting triggers a full re-optimization.

• path_annotation_service.py (Logistics\route_optimizer\services\path_annotation_service.py)

  • Functionality: Enriches routes with detailed path segments.
    • PathAnnotator class:
      • __init__(path_finder): Takes a pathfinding instance (e.g., DijkstraPathFinder).
      • annotate(result, graph_or_matrix):
        1. Iterates through routes in the result (handles dict or OptimizationResult DTO).
        2. If result.detailed_routes is empty but result.routes (simple list of location IDs) exists, it first populates detailed_routes with basic stop information and assigned vehicle IDs.
        3. For each pair of consecutive stops in a route, calls self.path_finder.calculate_shortest_path using the provided graph_or_matrix (if it's a matrix, it's converted to a graph first using DistanceMatrixBuilder.distance_matrix_to_graph).
        4. Constructs RouteSegment like dictionaries and adds them to the segments list of the respective DetailedRoute.
        5. Handles pathfinding errors gracefully by logging and adding placeholder segments.
      • _add_summary_statistics(result, vehicles): This internal helper seems to ensure detailed_routes have a basic structure and then calls RouteStatsService.add_statistics. (Note: OptimizationService also calls RouteStatsService after PathAnnotator.annotate).
  • Important: The level of detail in paths depends on the path_finder and the input graph_or_matrix.

• route_stats_service.py (Logistics\route_optimizer\services\route_stats_service.py)

  • Functionality: Calculates and adds summary statistics to optimization results.
    • RouteStatsService class:
      • add_statistics(result, vehicles) (static method):
        1. Modifies the result (dict or OptimizationResult DTO) in place.
        2. If detailed_routes is empty but simple routes exist, it creates basic detailed_routes entries.
        3. Calculates vehicle_costs (fixed + variable based on cost_per_km and segment distances from detailed_routes).
        4. Calculates total_cost for the entire solution.
        5. Aggregates statistics into result.statistics['summary'] like total_stops, total_distance, total_vehicles_used, total_deliveries_assigned.
  • Important: Accurate cost calculation relies on detailed_routes having segment distances.

• depot_service.py (Logistics\route_optimizer\services\depot_service.py)

  • Functionality: Provides utilities for depot locations.
    • DepotService class:
      • get_nearest_depot(locations) (static method): Returns the first Location object marked as is_depot=True. If none, returns the first location in the list.
      • find_depot_index(locations) (static method): Returns the index of the depot. Defaults to 0 if no depot found.
  • Important: Current logic is simple; assumes the first depot found is the one to use, or the first location overall if no explicit depot.

• external_data_service.py (Logistics\route_optimizer\services\external_data_service.py)

  • Functionality: Designed for fetching external data like traffic, weather, roadblocks.
    • ExternalDataService class:
      • Methods like get_traffic_data, get_weather_data, get_roadblock_data.
      • Currently provides mock data (e.g., _mock_traffic_data) if API keys are not set or use_mocks is true.
      • Includes _make_api_request helper with retry logic for actual API calls (if implemented).
      • combine_traffic_and_weather: Merges factors from different sources.
  • Important: For production, mock implementations need replacement with real API integrations. API key management would be crucial.

• traffic_service.py (Logistics\route_optimizer\services\traffic_service.py)

  • Functionality: Provides traffic-related utilities.
    • TrafficService class:
      • __init__(api_key=None): Can be initialized with an API key.
      • apply_traffic_factors(matrix, traffic_data) (static): A wrapper for DistanceMatrixBuilder.add_traffic_factors.
      • create_road_graph(locations):
        • If an API key is available (passed at init or from settings via DistanceMatrixBuilder), it tries to use Google Maps API (via DistanceMatrixBuilder.create_distance_matrix_from_api) to get distances/times for graph edges.
        • Otherwise, falls back to Haversine distances (_calculate_distance_haversine).
        • Returns a graph as a dict: {'nodes': {}, 'edges': {from_node: {to_node: {'distance': km, 'time': secs}}}}.
  • Important: create_road_graph is key for OptimizationService when use_api=True to get detailed paths from a realistic road network.

• vrp_solver.py (Logistics\route_optimizer\services\vrp_solver.py)

  • Functionality: This file appears to contain a standalone solve_with_time_windows function. This function is very similar in its core logic (OR-Tools setup for VRPTW) to the ORToolsVRPSolver.solve_with_time_windows method found in core/ortools_optimizer.py.
  • Important:
    • Potential Redundancy: Its existence alongside the ORToolsVRPSolver class in core/ortools_optimizer.py suggests a potential area for refactoring to consolidate VRP solving logic into a single, authoritative place (likely the ORToolsVRPSolver class).
    • This standalone function might be a remnant of earlier development stages or intended for a very specific, isolated use case not covered by the main OptimizationService flow. Review its current usage to determine if it can be deprecated or merged.

4. Data Models & Migrations

• models.py (Logistics\route_optimizer\models.py)

  • Functionality: Defines data structures for the application.
    • Dataclasses:
      • Vehicle: Represents a vehicle with id, capacity, start_location_id, end_location_id, cost_per_km, fixed_cost, max_distance, max_stops, available, skills.
      • Delivery: Represents a delivery/pickup task with id, location_id, demand, priority, required_skills, is_pickup.
    • Django Model:
      • DistanceMatrixCache(models.Model): A Django model for caching results from DistanceMatrixBuilder. Fields include cache_key (unique), matrix_data (JSON text), location_ids (JSON text), time_matrix_data (JSON text, nullable), created_at. Has indexes on cache_key and created_at.
  • Important: Dataclasses are used for in-memory data representation, while Django models are for database persistence.

• migrations/0001_initial.py (Logistics\route_optimizer\migrations\0001_initial.py)

  • Functionality: The initial database migration file, automatically generated by Django.
  • Defines the SQL operations to create the DistanceMatrixCache table in the database according to its model definition.
  • Important: This file should generally not be manually edited.

5. Configuration & Utilities

• settings.py (app-level) (Logistics\route_optimizer\settings.py)

  • Functionality: Manages app-specific configurations.
    • Loads environment variables using load_env_from_file (from utils.env_loader).
    • Defines GOOGLE_MAPS_API_KEY, GOOGLE_MAPS_API_URL, USE_API_BY_DEFAULT.
    • API request settings: MAX_RETRIES, BACKOFF_FACTOR, RETRY_DELAY_SECONDS.
    • Caching: CACHE_EXPIRY_DAYS, OPTIMIZATION_RESULT_CACHE_TIMEOUT.
    • TESTING flag, set dynamically based on sys.argv or sys.modules.
  • Important: Centralizes configuration, separating it from code. .env file for secrets should be in .gitignore.

• utils/env_loader.py (Logistics\route_optimizer\utils\env_loader.py)

  • Functionality:
    • load_env_from_file(file_path): Reads a .env file, parses KEY=VALUE pairs, and sets them as environment variables using os.environ. Skips comments and empty lines.
  • Important: Facilitates local development by mimicking production environment variable setup. The .env file itself must be kept secure.

• utils/helpers.py (Logistics\route_optimizer\utils\helpers.py)

  • Functionality: A collection of general-purpose utility functions.
    • Time formatting: convert_minutes_to_time_str, convert_time_str_to_minutes, format_duration.
    • Route display: format_route_for_display.
    • Matrix manipulation: apply_external_factors (potential overlap with DistanceMatrixBuilder).
    • Graph analysis: detect_isolated_nodes.
    • JSON handling: safe_json_dumps for robust serialization of complex objects (handles datetime, numpy types, etc.).
  • Important: Provides reusable helper functions. Review for potential redundancy with more specialized classes.

6. Standard Django Files

• admin.py (Logistics\route_optimizer\admin.py)

  • Functionality: Used to register Django models with the Django admin interface.
  • Currently empty; DistanceMatrixCache could be registered here for admin panel management.

• apps.py (Logistics\route_optimizer\apps.py)

  • Functionality: Django app configuration. Defines RouteOptimizerConfig.
  • ready() method can be used for app initialization tasks (currently empty).

• views.py (root-level) (Logistics\route_optimizer\views.py)

  • Functionality: Standard Django views file for server-rendered pages.
  • Currently empty, as all current views are API views in api/views.py.

• __init__.py files

  • Present in route_optimizer/, api/, core/, migrations/, services/, utils/.
  • Mark directories as Python packages. The main route_optimizer/__init__.py also defines __version__.

• README.md (Logistics\route_optimizer\README.md)

  • Functionality: This document itself, providing an overview and file-by-file explanation of the module.

7. Testing (route_optimizer/tests/)

While not part of the core runtime functionality, the tests/ directory is crucial for ensuring the module's reliability and correctness.

• Structure: Organized mirroring the app structure (api/, core/, services/, utils/).
• Files:
  • test_serializers.py, test_views.py: Test API layer components.
  • test_dijkstra.py, test_distance_matrix.py, test_ortools_optimizer.py, test_types.py: Test core logic.
  • Individual test files for each service: e.g., test_optimization_service.py.
  • test_models.py: Tests Django models and dataclass behavior.
  • test_env_loader.py, test_helpers.py: Test utility functions.
• Configuration:
  • conftest.py (Logistics\route_optimizer\tests\conftest.py): Pytest configuration, sets up Django environment using test_settings.py.
  • test_settings.py (Logistics\route_optimizer\tests\test_settings.py): Django settings specifically for tests (e.g., in-memory database, dummy API keys, disabled external calls, specific SECRET_KEY).
  • __init__.py (Logistics\route_optimizer\tests_init_.py): Ensures test settings are loaded.
• Important: Comprehensive tests cover unit and integration aspects, ensuring individual components and their interactions work as expected. They are essential for maintaining code quality and enabling safe refactoring.