# javithnaseem-j/laneiq architecture

> Architecture diagram of the GitHub repository javithnaseem-j/laneiq, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/javithnaseem-j/laneiq
- Repository: https://github.com/javithnaseem-j/laneiq

## Overview

1. **What this repo is**
   LANEIQ is an optimization pipeline, not just an API. It takes a free-text freight shipment brief, turns it into structured shipment data, runs a multi-agent planning workflow, solves a vehicle routing problem, checks exceptions, and returns a JSON result plus a dashboard view.

2. **Primary runtime shape**
   The system is split into three user-facing surfaces:
   - **FastAPI backend** in `api/` for programmatic optimization requests and status polling
   - **Streamlit dashboard** in `dashboard/` for human review and analytics
   - **Async task worker** in `src/tasks/` using Celery, with Redis as the queue/broker per the README

3. **Core request flow**
   The main business flow starts with a shipment brief. The brief is parsed by the agent pipeline in `src/agents/`, then passed to routing/optimization in `src/solver/`, then checked for exceptions in `src/agents/exception.py` and related modules, and finally formatted into a response schema in `api/schemas/`. The README’s diagram shows the optimization result as the final output artifact.

4. **Agent orchestration boundary**
   `src/agents/` is the decision-making layer. It contains separate nodes for planning, route construction, exception handling, report generation, and graph/state management. This is the boundary where LLM-driven or rule-driven orchestration happens before the solver is called.

5. **Optimization and solver boundary**
   `src/solver/` is the deterministic optimization layer. It contains:
   - a greedy baseline
   - constraint modeling
   - VRP / CVRPTW solve logic
   - staged optimization helpers
   This is the part that materially affects the architecture because it is the cost-optimization engine and the source of the business metric improvements reported in the README.

6. **Data and external inputs**
   `src/data/` handles synthetic generation, validation, and a vessel ETA/API integration. That implies two kinds of input: generated training/evaluation data and live/external shipping data used during exception checks or route feasibility checks.

7. **API layer and async execution**
   `api/main.py` plus the routers in `api/routers/` expose the service contract. The router split suggests:
   - health/status endpoints for operational checks
   - optimize endpoint for submission
   - status endpoint for async result polling
   `api/middleware/rate_limit.py` adds a request-boundary control, so the API is not just a pass-through; it enforces usage limits and likely protects expensive optimization runs.

8. **Output contracts**
   The Pydantic schemas in `api/schemas/` define the stable architecture boundary between solver/agents and external callers. `shipment.py` and `result.py` indicate a strict input/output contract for shipment briefs and optimization results.

9. **Dashboard role**
   The Streamlit app in `dashboard/` is a separate consumer of the backend, not part of the core optimization path. Its pages are organized around the operational workflow:
   - shipment submission
   - route map
   - cost comparison
   - exception monitoring
   - drift reporting
   `dashboard/utils/api_client.py` shows it talks to the API rather than directly to solver internals.

10. **MLOps and reproducibility**
    This repo has a strong experiment/reproducibility layer:
    - `pipelines/dvc.yaml` and `pipelines/params.yaml` define the data/solve/evaluate pipeline
    - `mlruns/` stores MLflow tracking and model artifacts
    - `.dvc_remote/` is the remote artifact store
    This means optimization runs are tracked as experiments, not just executed ad hoc.

11. **Monitoring and model/data health**
    `src/monitoring/drift.py` plus the README’s Evidently/CloudWatch mention show a monitoring path for detecting data drift after deployment. This is a separate control plane from request processing: it watches the behavior of incoming shipment distributions and feeds alarms/alerts.

12. **Operational deployment boundary**
    The `docker/` directory and GitHub Actions workflows indicate containerized deployment with CI/CD. There are distinct Dockerfiles for API and dashboard, and `docker-compose.yml` ties together the runtime pieces. The README also indicates Redis, ECR, and EC2 as deployment targets/components.

13. **Testing and validation**
    `tests/unit/` and `tests/integration/` reflect two validation layers:
    - unit tests for generator, schemas, state, vessel API, VRP logic
    - integration tests for API and agent graph behavior
    `tests/locustfile.py` adds load testing, which matters because optimization requests can be expensive and asynchronous.

14. **Engineering support modules**
    `config/settings.py` and `config/agents.py` centralize runtime configuration for the app and agents. `benchmarks/performance.py` measures solver/runtime characteristics. Together they support tuning, benchmarking, and environment-specific deployment without changing the core routing logic.

15. **How to draw the architecture**
    A good diagram would show four main zones: 
    - external users and shipment brief input
    - API/dashboard edge layer
    - async agent + solver core
    - MLOps/monitoring/storage sidecar systems
    The most important arrows are: brief submission → async task/API → agent graph → VRP solver → exception/report generation → structured result, with experiment tracking and drift monitoring branching off the solve/eval path.

Main entry points: [`api/main.py`](https://github.com/javithnaseem-j/laneiq/blob/main/api/main.py) (API app), [`dashboard/utils/api_client.py`](https://github.com/javithnaseem-j/laneiq/blob/main/dashboard/utils/api_client.py) (API client), [`src/solver/vrp.py`](https://github.com/javithnaseem-j/laneiq/blob/main/src/solver/vrp.py) (VRP solver), [`src/agents/route.py`](https://github.com/javithnaseem-j/laneiq/blob/main/src/agents/route.py) (Route agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_user_surfaces["User Surfaces"]
  node_shipment_brief["Shipment brief<br/>input brief"]
  node_api_main["API app<br/>FastAPI service<br/>[main.py]"]
  node_api_optimize["Optimize API<br/>endpoint router<br/>[optimize.py]"]
  node_api_status["Status API<br/>polling router<br/>[status.py]"]
  node_api_health["Health API<br/>ops router<br/>[health.py]"]
  node_rate_limit["Rate limit<br/>middleware<br/>[rate_limit.py]"]
  node_dashboard_app["Dashboard<br/>Streamlit app<br/>[app.py]"]
  node_dashboard_client["API client<br/>backend client<br/>[api_client.py]"]
  node_submit_page["Submit page<br/>dashboard page"]
  node_route_page["Route map<br/>dashboard page<br/>[02_route_map.py]"]
  node_cost_page["Cost compare<br/>dashboard page"]
  node_exception_page["Exception monitor<br/>dashboard page"]
  node_drift_page["Drift report<br/>dashboard page<br/>[05_drift_report.py]"]
end

subgraph group_core_pipeline["Optimization Core"]
  node_task_worker["Task worker<br/>Celery worker<br/>[celery_app.py]"]
  node_planner["Planner<br/>[planner.py]"]
  node_route_agent["Route agent<br/>agent route<br/>[route.py]"]
  node_state_graph(("State graph<br/>agent state<br/>[graph.py]"))
  node_exception_agent{{"Exception agent<br/>agent exception<br/>[exception.py]"}}
  node_report_agent["Report agent<br/>agent report<br/>[report.py]"]
  node_baseline_solver["Baseline<br/>greedy solver<br/>[baseline.py]"]
  node_constraints["Constraints<br/>constraint model<br/>[constraints.py]"]
  node_vrp_solver[("VRP solver<br/>vrp/cvrptw<br/>[vrp.py]")]
  node_optimize_stage["Optimize stage<br/>staged optimize<br/>[optimise.py]"]
  node_solve_stage["Solve stage<br/>solve helper<br/>[solve_stage.py]"]
end

subgraph group_data_ops["Data & Ops"]
  node_generator["Generator<br/>synthetic data<br/>[generator.py]"]
  node_validator["Validator<br/>data validation<br/>[validator.py]"]
  node_vessel_api["Vessel API<br/>external input<br/>[vessel_api.py]"]
  node_transform["Transform<br/>[transform.py]"]
  node_drift_monitor["Drift monitor<br/>monitoring<br/>[drift.py]"]
  node_eval_stage["Eval stage<br/>task eval<br/>[eval_stage.py]"]
  node_settings["Settings<br/>runtime config<br/>[settings.py]"]
  node_agent_config["Agent config<br/>[agents.py]"]
end

subgraph group_contracts["Contracts"]
  node_shipment_schema["Shipment schema<br/>request schema<br/>[shipment.py]"]
  node_result_schema["Result schema<br/>response schema<br/>[result.py]"]
end

node_shipment_brief -->|"submit"| node_api_optimize
node_api_optimize -->|"guard"| node_rate_limit
node_rate_limit -->|"enter"| node_api_main
node_api_main -->|"validate"| node_shipment_schema
node_api_main -->|"enqueue"| node_task_worker
node_api_status -->|"poll"| node_task_worker
node_api_health -.->|"check"| node_api_main
node_task_worker -->|"orchestrate"| node_planner
node_planner -->|"manage"| node_state_graph
node_state_graph -->|"drive"| node_route_agent
node_route_agent -->|"compare"| node_baseline_solver
node_route_agent -->|"bound"| node_constraints
node_route_agent -->|"solve"| node_vrp_solver
node_baseline_solver -->|"seed"| node_optimize_stage
node_constraints -->|"constrain"| node_vrp_solver
node_optimize_stage -->|"stage"| node_solve_stage
node_solve_stage -->|"run"| node_vrp_solver
node_vrp_solver -->|"check"| node_exception_agent
node_exception_agent -->|"summarize"| node_report_agent
node_report_agent -->|"format"| node_result_schema
node_vrp_solver -->|"emit"| node_result_schema
node_generator -->|"verify"| node_validator
node_validator -->|"prepare"| node_transform
node_vessel_api -->|"feed"| node_exception_agent
node_transform -->|"evaluate"| node_eval_stage
node_eval_stage -.->|"observe"| node_drift_monitor
node_settings -.->|"configure"| node_api_main
node_settings -.->|"configure"| node_task_worker
node_agent_config -.->|"configure"| node_planner
node_dashboard_app -->|"uses"| node_dashboard_client
node_dashboard_client -->|"call"| node_api_main
node_submit_page -->|"submit"| node_dashboard_client
node_route_page -->|"fetch"| node_dashboard_client
node_cost_page -->|"fetch"| node_dashboard_client
node_exception_page -->|"fetch"| node_dashboard_client
node_drift_page -->|"display"| node_drift_monitor

click node_api_main "https://github.com/javithnaseem-j/laneiq/blob/main/api/main.py"
click node_api_optimize "https://github.com/javithnaseem-j/laneiq/blob/main/api/routers/optimize.py"
click node_api_status "https://github.com/javithnaseem-j/laneiq/blob/main/api/routers/status.py"
click node_api_health "https://github.com/javithnaseem-j/laneiq/blob/main/api/routers/health.py"
click node_rate_limit "https://github.com/javithnaseem-j/laneiq/blob/main/api/middleware/rate_limit.py"
click node_dashboard_app "https://github.com/javithnaseem-j/laneiq/blob/main/dashboard/app.py"
click node_dashboard_client "https://github.com/javithnaseem-j/laneiq/blob/main/dashboard/utils/api_client.py"
click node_submit_page "https://github.com/javithnaseem-j/laneiq/blob/main/dashboard/pages/01_submit_shipment.py"
click node_route_page "https://github.com/javithnaseem-j/laneiq/blob/main/dashboard/pages/02_route_map.py"
click node_cost_page "https://github.com/javithnaseem-j/laneiq/blob/main/dashboard/pages/03_cost_comparison.py"
click node_exception_page "https://github.com/javithnaseem-j/laneiq/blob/main/dashboard/pages/04_exception_monitor.py"
click node_drift_page "https://github.com/javithnaseem-j/laneiq/blob/main/dashboard/pages/05_drift_report.py"
click node_task_worker "https://github.com/javithnaseem-j/laneiq/blob/main/src/tasks/celery_app.py"
click node_planner "https://github.com/javithnaseem-j/laneiq/blob/main/src/agents/planner.py"
click node_route_agent "https://github.com/javithnaseem-j/laneiq/blob/main/src/agents/route.py"
click node_state_graph "https://github.com/javithnaseem-j/laneiq/blob/main/src/agents/graph.py"
click node_exception_agent "https://github.com/javithnaseem-j/laneiq/blob/main/src/agents/exception.py"
click node_report_agent "https://github.com/javithnaseem-j/laneiq/blob/main/src/agents/report.py"
click node_baseline_solver "https://github.com/javithnaseem-j/laneiq/blob/main/src/solver/baseline.py"
click node_constraints "https://github.com/javithnaseem-j/laneiq/blob/main/src/solver/constraints.py"
click node_vrp_solver "https://github.com/javithnaseem-j/laneiq/blob/main/src/solver/vrp.py"
click node_optimize_stage "https://github.com/javithnaseem-j/laneiq/blob/main/src/solver/optimise.py"
click node_solve_stage "https://github.com/javithnaseem-j/laneiq/blob/main/src/solver/solve_stage.py"
click node_shipment_schema "https://github.com/javithnaseem-j/laneiq/blob/main/api/schemas/shipment.py"
click node_result_schema "https://github.com/javithnaseem-j/laneiq/blob/main/api/schemas/result.py"
click node_generator "https://github.com/javithnaseem-j/laneiq/blob/main/src/data/generator.py"
click node_validator "https://github.com/javithnaseem-j/laneiq/blob/main/src/data/validator.py"
click node_vessel_api "https://github.com/javithnaseem-j/laneiq/blob/main/src/data/vessel_api.py"
click node_transform "https://github.com/javithnaseem-j/laneiq/blob/main/src/features/transform.py"
click node_drift_monitor "https://github.com/javithnaseem-j/laneiq/blob/main/src/monitoring/drift.py"
click node_eval_stage "https://github.com/javithnaseem-j/laneiq/blob/main/src/tasks/eval_stage.py"
click node_settings "https://github.com/javithnaseem-j/laneiq/blob/main/config/settings.py"
click node_agent_config "https://github.com/javithnaseem-j/laneiq/blob/main/config/agents.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_shipment_brief,node_api_main,node_api_optimize,node_api_status,node_api_health,node_rate_limit,node_dashboard_app,node_dashboard_client,node_submit_page,node_route_page,node_cost_page,node_exception_page,node_drift_page toneBlue
class node_task_worker,node_planner,node_route_agent,node_state_graph,node_exception_agent,node_report_agent,node_baseline_solver,node_constraints,node_vrp_solver,node_optimize_stage,node_solve_stage toneAmber
class node_generator,node_validator,node_vessel_api,node_transform,node_drift_monitor,node_eval_stage,node_settings,node_agent_config toneMint
class node_shipment_schema,node_result_schema toneRose
```

## Components

### User Surfaces

External entrypoints for submission, review, and polling.

- **Shipment brief**: input brief · Free-text freight shipment request provided by a user or client.
- [API app](https://github.com/javithnaseem-j/laneiq/blob/main/api/main.py): FastAPI service · Main backend application entrypoint for optimization requests. · `api/main.py`
- [Optimize API](https://github.com/javithnaseem-j/laneiq/blob/main/api/routers/optimize.py): endpoint router · Submits shipment briefs into the async optimization workflow. · `api/routers/optimize.py`
- [Status API](https://github.com/javithnaseem-j/laneiq/blob/main/api/routers/status.py): polling router · Exposes async job status and result retrieval. · `api/routers/status.py`
- [Health API](https://github.com/javithnaseem-j/laneiq/blob/main/api/routers/health.py): ops router · Operational health and readiness checks for the backend. · `api/routers/health.py`
- [Rate limit](https://github.com/javithnaseem-j/laneiq/blob/main/api/middleware/rate_limit.py): middleware · Request-boundary control protecting expensive optimization runs. · `api/middleware/rate_limit.py`
- [Dashboard](https://github.com/javithnaseem-j/laneiq/blob/main/dashboard/app.py): Streamlit app · Human-facing review and analytics interface. · `dashboard/app.py`
- [API client](https://github.com/javithnaseem-j/laneiq/blob/main/dashboard/utils/api_client.py): backend client · Dashboard helper that talks to the FastAPI service. · `dashboard/utils/api_client.py`
- [Submit page](https://github.com/javithnaseem-j/laneiq/blob/main/dashboard/pages/01_submit_shipment.py): dashboard page · Shipment submission workflow in the dashboard. · `dashboard/pages/01_submit_shipment.py`
- [Route map](https://github.com/javithnaseem-j/laneiq/blob/main/dashboard/pages/02_route_map.py): dashboard page · Route visualization and operational review page. · `dashboard/pages/02_route_map.py`
- [Cost compare](https://github.com/javithnaseem-j/laneiq/blob/main/dashboard/pages/03_cost_comparison.py): dashboard page · Compares baseline and optimized routing cost. · `dashboard/pages/03_cost_comparison.py`
- [Exception monitor](https://github.com/javithnaseem-j/laneiq/blob/main/dashboard/pages/04_exception_monitor.py): dashboard page · Monitors detected exceptions and operational issues. · `dashboard/pages/04_exception_monitor.py`
- [Drift report](https://github.com/javithnaseem-j/laneiq/blob/main/dashboard/pages/05_drift_report.py): dashboard page · Shows data drift and monitoring signals. · `dashboard/pages/05_drift_report.py`

### Optimization Core

Agent orchestration and deterministic routing engine.

- [Task worker](https://github.com/javithnaseem-j/laneiq/blob/main/src/tasks/celery_app.py): Celery worker · Async execution boundary for optimization and evaluation tasks. · `src/tasks/celery_app.py`
- [Planner](https://github.com/javithnaseem-j/laneiq/blob/main/src/agents/planner.py): agent planner · Orchestrates the agent workflow from brief to route plan. · `src/agents/planner.py`
- [Route agent](https://github.com/javithnaseem-j/laneiq/blob/main/src/agents/route.py): agent route · Constructs candidate routes and coordinates routing decisions. · `src/agents/route.py`
- [State graph](https://github.com/javithnaseem-j/laneiq/blob/main/src/agents/graph.py): agent state · Shared workflow state and graph management for the agent pipeline. · `src/agents/graph.py`
- [Exception agent](https://github.com/javithnaseem-j/laneiq/blob/main/src/agents/exception.py): agent exception · Checks feasibility and flags exceptions after optimization. · `src/agents/exception.py`
- [Report agent](https://github.com/javithnaseem-j/laneiq/blob/main/src/agents/report.py): agent report · Formats the final optimization narrative and summary output. · `src/agents/report.py`
- [Baseline](https://github.com/javithnaseem-j/laneiq/blob/main/src/solver/baseline.py): greedy solver · Greedy reference solution used for comparison and staging. · `src/solver/baseline.py`
- [Constraints](https://github.com/javithnaseem-j/laneiq/blob/main/src/solver/constraints.py): constraint model · Business and route constraints used by the solver. · `src/solver/constraints.py`
- [VRP solver](https://github.com/javithnaseem-j/laneiq/blob/main/src/solver/vrp.py): vrp/cvrptw · Deterministic vehicle routing optimization engine. · `src/solver/vrp.py`
- [Optimize stage](https://github.com/javithnaseem-j/laneiq/blob/main/src/solver/optimise.py): staged optimize · Staged optimization helpers and solve orchestration. · `src/solver/optimise.py`
- [Solve stage](https://github.com/javithnaseem-j/laneiq/blob/main/src/solver/solve_stage.py): solve helper · Pipeline stage wrapper around the core solve logic. · `src/solver/solve_stage.py`

### Data & Ops

Data generation, monitoring, tracking, and deployment support.

- [Generator](https://github.com/javithnaseem-j/laneiq/blob/main/src/data/generator.py): synthetic data · Synthetic shipment and routing data generation. · `src/data/generator.py`
- [Validator](https://github.com/javithnaseem-j/laneiq/blob/main/src/data/validator.py): data validation · Data and shipment validation boundary. · `src/data/validator.py`
- [Vessel API](https://github.com/javithnaseem-j/laneiq/blob/main/src/data/vessel_api.py): external input · Live vessel ETA or shipping data integration. · `src/data/vessel_api.py`
- [Transform](https://github.com/javithnaseem-j/laneiq/blob/main/src/features/transform.py): feature transform · Feature preparation for downstream solve or evaluation steps. · `src/features/transform.py`
- [Drift monitor](https://github.com/javithnaseem-j/laneiq/blob/main/src/monitoring/drift.py): monitoring · Data drift detection for deployed shipment distributions. · `src/monitoring/drift.py`
- [Eval stage](https://github.com/javithnaseem-j/laneiq/blob/main/src/tasks/eval_stage.py): task eval · Asynchronous evaluation and benchmarking stage. · `src/tasks/eval_stage.py`
- [Settings](https://github.com/javithnaseem-j/laneiq/blob/main/config/settings.py): runtime config · Central application and environment settings. · `config/settings.py`
- [Agent config](https://github.com/javithnaseem-j/laneiq/blob/main/config/agents.py): agent config · Central configuration for agent behavior and prompts. · `config/agents.py`

### Contracts

Stable request and response schemas exposed by the API.

- [Shipment schema](https://github.com/javithnaseem-j/laneiq/blob/main/api/schemas/shipment.py): request schema · Pydantic contract for shipment brief inputs. · `api/schemas/shipment.py`
- [Result schema](https://github.com/javithnaseem-j/laneiq/blob/main/api/schemas/result.py): response schema · Pydantic contract for optimization results. · `api/schemas/result.py`

## Connections

- Shipment brief → Optimize API: submit · User submits a freight brief to the optimization endpoint.
- Optimize API → Rate limit: guard · Requests are filtered before expensive execution.
- Rate limit → API app: enter · Accepted requests reach the backend application.
- API app → Shipment schema: validate · Incoming payloads are validated against request contracts.
- API app → Task worker: enqueue · Optimization jobs are dispatched to async execution.
- Status API → Task worker: poll · Clients poll worker-backed job status and results.
- Health API → API app: check · Health endpoints expose service readiness.
- Task worker → Planner: orchestrate · The worker starts the agent planning workflow.
- Planner → State graph: manage · Planning updates the shared workflow state.
- State graph → Route agent: drive · Workflow state guides route construction.
- Route agent → Baseline: compare · Constructed plans are compared against a greedy baseline.
- Route agent → Constraints: bound · Route generation is constrained by business rules.
- Route agent → VRP solver: solve · Candidate routing problems are sent to the VRP engine.
- Baseline → Optimize stage: seed · Baseline output seeds staged optimization and comparison.
- Constraints → VRP solver: constrain · Constraint model shapes the routing solve.
- Optimize stage → Solve stage: stage · Higher-level optimization delegates into solve stages.
- Solve stage → VRP solver: run · Solve stage executes the deterministic routing solver.
- VRP solver → Exception agent: check · Solved routes are reviewed for operational exceptions.
- Exception agent → Report agent: summarize · Exceptions are incorporated into the final narrative.
- Report agent → Result schema: format · Final outputs are normalized to the response contract.
- VRP solver → Result schema: emit · Optimized routes are serialized as structured results.
- Generator → Validator: verify · Generated data is validated for experiments and tests.
- Validator → Transform: prepare · Validated records are transformed into model-ready features.
- Vessel API → Exception agent: feed · External vessel data informs exception and feasibility checks.
- Transform → Eval stage: evaluate · Prepared features feed evaluation and benchmark tasks.
- Eval stage → Drift monitor: observe · Evaluation outputs help monitor behavior changes over time.
- Settings → API app: configure · Runtime settings configure the backend.
- Settings → Task worker: configure · Worker behavior is driven by shared configuration.
- Agent config → Planner: configure · Agent orchestration uses centralized agent settings.
- Dashboard → API client: uses · The dashboard accesses backend services through a client.
- API client → API app: call · Dashboard pages call the API rather than solver internals.
- Submit page → API client: submit · Shipment submission page invokes the backend client.
- Route map → API client: fetch · Route view pulls optimization results from the backend.
- Cost compare → API client: fetch · Cost comparison reads structured result data.
- Exception monitor → API client: fetch · Exception monitoring consumes backend output.
- Drift report → Drift monitor: display · Drift reporting surfaces monitoring signals.