javithnaseem-j/laneiq

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.