# shubham-chhimpa/lucidity-route-optimizer architecture

> Architecture diagram of the GitHub repository shubham-chhimpa/lucidity-route-optimizer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shubham-chhimpa/lucidity-route-optimizer
- Repository: https://github.com/shubham-chhimpa/lucidity-route-optimizer

## Overview

##### Project type and purpose
- This is a standalone backend microservice (FastAPI) for computing the optimal delivery route.
- It solves a variant of the Traveling Salesperson Problem (TSP) with conditional wait‐time rules.
- Exposed as a `/find-route` HTTP POST endpoint returning the best path and total time.

##### File structure
Top-level:
- Dockerfile, docker-compose.yml, requirements.txt → containerization and deployment
- app/ → the application code
- tests/ → unit and fixture tests
Inside app/:
- main.py → FastAPI app factory, registration of routers & error handlers
- api/
- routers/routes.py → HTTP endpoints (`/find-route`, `/healthz`, `/readyz`)
- deps.py → dependency-injection wiring for services & adapters
- errors.py → centralized exception handling
- schemas/ → Pydantic DTOs (RouteRequest, RouteResponse)
- core/
- domain/entities.py → pure domain entities (Location, Order)
- domain/ports.py → interfaces (DistanceCalculator, SpeedEstimator, PathGenerator, CostCalculator)
- services/ → business logic components (path_generator, cost_calculator, route_optimizer)
- infrastructure/
- distance/ → HaversineCalculator + SpeedConfig adapters
- logging/config.py → logging setup
- settings.py → Pydantic Settings for env vars
- config.py, logging_config.py, models.py, services.py, utils.py → additional wiring & helpers

##### README for additional insights
- Confirms Clean/Hexagonal architecture (domain-services + ports/adapters).
- Highlights Docker usage, environment configuration (`AVERAGE_SPEED_KMPH`, `EARTH_RADIUS_KM`).
- Shows sample requests, expected responses, and project structure.

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Layer
    Client["Client (CLI/Browser)"]:::external
    Tests["Test Suite (pytest)"]:::test

    %% API Layer
    subgraph "API Layer" 
        direction TB
        APIFactory["FastAPI App Factory"]:::api
        Routers["HTTP Routers<br/>(/find-route, /healthz, /readyz)"]:::api
        Errors["Error Handling Module"]:::api
    end

    %% DI Layer
    subgraph "Dependency Injection Layer"
        direction TB
        DI["Dependency Injection (deps.py)"]:::di
    end

    %% Schemas
    Schemas["Pydantic Schemas<br/>(RouteRequest,RouteResponse)"]:::api

    %% Domain Layer
    subgraph "Domain Layer"
        direction TB
        Entities["Domain Entities<br/>(Location,Order)"]:::domain
        Ports["Domain Ports<br/>(DistanceCalculator,SpeedEstimator,PathGenerator,CostCalculator)"]:::domain
        Services["Domain Services"]:::domain
        subgraph "Services"
            direction TB
            PathGen["PathGenerator Service"]:::domain
            CostCalc["CostCalculator Service"]:::domain
            RouteOpt["RouteOptimizer Service"]:::domain
        end
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        InfraDist["HaversineCalculator Adapter"]:::infra
        InfraSpeed["SpeedEstimator Adapter"]:::infra
        LoggingConf["Logging Configuration"]:::logging
        Settings["Application Settings"]:::config
    end

    %% Utilities & Config
    Utilities["Utility Helpers"]:::util
    Models["Misc Services & Models"]:::util
    GlobalConfig["Global Config Wiring"]:::config
    GlobalLogging["Global Logging Setup"]:::logging

    %% Containerization
    subgraph "Containerization & Deployment"
        direction TB
        Docker["Dockerfile"]:::docker
        Compose["docker-compose.yml"]:::docker
    end

    %% Connections
    Client -->|"POST /find-route"| Routers
    Routers -->|uses| APIFactory
    Routers -->|uses| Schemas
    Routers -->|calls| DI
    APIFactory -->|registers| Routers
    APIFactory -->|registers| Errors

    DI -->|provides| PathGen
    DI -->|provides| CostCalc
    DI -->|provides| RouteOpt
    DI -->|injects| InfraDist
    DI -->|injects| InfraSpeed
    DI -->|injects| LoggingConf
    DI -->|injects| Settings

    PathGen -->|depends on| Ports
    CostCalc -->|depends on| Ports
    RouteOpt -->|orchestrates| PathGen
    RouteOpt -->|orchestrates| CostCalc

    Ports -->|port interface| InfraDist
    Ports -->|port interface| InfraSpeed
    InfraDist -->|implements| Ports
    InfraSpeed -->|implements| Ports

    Routers -->|logs via| LoggingConf
    PathGen -->|reads config| Settings
    CostCalc -->|reads config| Settings
    RouteOpt -->|logs via| LoggingConf

    APIFactory -->|reads config| GlobalConfig
    Errors -->|logs via| GlobalLogging

    Utilities -->|helpers for| APIFactory
    Utilities -->|helpers for| DomainLayer
    Models -->|helpers for| DomainLayer

    Docker -->|packages| APIFactory
    Compose -->|orchestrates| Docker

    Tests -->|tests| Routers
    Tests -->|tests| DomainLayer
    Tests -->|tests| InfrastructureLayer

    %% Click Events
    click APIFactory "https://github.com/shubham-chhimpa/lucidity-route-optimizer/blob/main/app/main.py"
    click Routers "https://github.com/shubham-chhimpa/lucidity-route-optimizer/blob/main/app/api/routers/routes.py"
    click DI "https://github.com/shubham-chhimpa/lucidity-route-optimizer/blob/main/app/api/deps.py"
    click Errors "https://github.com/shubham-chhimpa/lucidity-route-optimizer/blob/main/app/api/errors.py"
    click Schemas "https://github.com/shubham-chhimpa/lucidity-route-optimizer/blob/main/app/schemas/route.py"
    click Entities "https://github.com/shubham-chhimpa/lucidity-route-optimizer/blob/main/app/core/domain/entities.py"
    click Ports "https://github.com/shubham-chhimpa/lucidity-route-optimizer/blob/main/app/core/domain/ports.py"
    click PathGen "https://github.com/shubham-chhimpa/lucidity-route-optimizer/blob/main/app/core/services/path_generator.py"
    click CostCalc "https://github.com/shubham-chhimpa/lucidity-route-optimizer/blob/main/app/core/services/cost_calculator.py"
    click RouteOpt "https://github.com/shubham-chhimpa/lucidity-route-optimizer/blob/main/app/core/services/route_optimizer.py"
    click InfraDist "https://github.com/shubham-chhimpa/lucidity-route-optimizer/blob/main/app/infrastructure/distance/haversine_calculator.py"
    click InfraSpeed "https://github.com/shubham-chhimpa/lucidity-route-optimizer/blob/main/app/infrastructure/distance/speed_config.py"
    click LoggingConf "https://github.com/shubham-chhimpa/lucidity-route-optimizer/blob/main/app/infrastructure/logging/config.py"
    click Settings "https://github.com/shubham-chhimpa/lucidity-route-optimizer/blob/main/app/infrastructure/settings.py"
    click GlobalConfig "https://github.com/shubham-chhimpa/lucidity-route-optimizer/blob/main/app/config.py"
    click GlobalLogging "https://github.com/shubham-chhimpa/lucidity-route-optimizer/blob/main/app/logging_config.py"
    click Utilities "https://github.com/shubham-chhimpa/lucidity-route-optimizer/blob/main/app/utils.py"
    click Models "https://github.com/shubham-chhimpa/lucidity-route-optimizer/blob/main/app/services.py"
    click Models "https://github.com/shubham-chhimpa/lucidity-route-optimizer/blob/main/app/models.py"
    click Docker "https://github.com/shubham-chhimpa/lucidity-route-optimizer/tree/main/Dockerfile"
    click Compose "https://github.com/shubham-chhimpa/lucidity-route-optimizer/blob/main/docker-compose.yml"
    click Tests "https://github.com/shubham-chhimpa/lucidity-route-optimizer/tree/main/tests/unit/"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef api fill:#bbf,stroke:#333,stroke-width:1px
    classDef di fill:#bfb,stroke:#333,stroke-width:1px
    classDef domain fill:#afa,stroke:#333,stroke-width:1px
    classDef infra fill:#fec,stroke:#333,stroke-width:1px
    classDef config fill:#ffd,stroke:#333,stroke-width:1px
    classDef util fill:#eee,stroke:#333,stroke-width:1px
    classDef logging fill:#fcc,stroke:#333,stroke-width:1px
    classDef docker fill:#cff,stroke:#333,stroke-width:1px
    classDef test fill:#fcf,stroke:#333,stroke-width:1px
```
