Overview
OptiCargo is a decision support project for maritime logistics. It connects cargo information, vessel capacity, voyage routes, demand, and operational documents so that users can assess options with a more complete view of the situation.
The development focus is explainable recommendations: cargo suitability can be traced, operational constraints remain enforceable, and regulatory answers include supporting references. Transaction decisions remain with the user through the business service.
Problem and objectives
Shipment planning depends on information from several sources. An available vessel may not have suitable capacity, a feasible route may not meet a commodity's requirements, and some decisions require an operational or regulatory review.
OptiCargo brings these concerns together to support:
- Cargo matching against the context of a voyage.
- Review of routes, capacity, locations, and supplier candidates.
- Operational and regulatory information retrieval with supporting documents.
- Demand analysis and anomaly signals for operator review.
System architecture
The Gateway connects the user interface with internal services. It handles authentication, business authorization, transaction persistence, bookings, payments, auditing, and saved recommendations.
Supporting components have separate responsibilities:
- Agents with LangGraph: identify the request type and coordinate the relevant analysis.
- Neo4j knowledge graph: provide vessel, port, route, voyage, supplier, and commodity context.
- Machine learning service: supply matching scores, demand forecasts, and anomaly detection.
- RAG pipeline with Qdrant: retrieve supporting information from indexed documents.
- Redis and object storage: support event processing, document ingestion, and artifact management.
PostgreSQL retains the authoritative business records. The graph is a rebuildable representation used for search and analysis.
Request-specific analysis
The system selects its steps according to the user's need:
| Request | Main process |
|---|---|
| Cargo matching | Graph context, optimization, evidence retrieval, and recommendation synthesis |
| Route review | Graph context and supporting information |
| Regulatory question | Document retrieval and a referenced answer |
| Operational analytics | Graph context and an analytical summary |
| Unclear request | Clarification of the user's requirements |
Conditional workflows limit service calls to the processes that are relevant. Results return to the Gateway for persistence or further review.
Data and document management
Operational documents pass through checksum verification, parsing, chunking, embedding, and indexing. Retrieval preserves document identity, title, version, page information, and the passage supporting an answer.
Graph updates use events with deduplication, bounded retries, and failed-event handling. Reconciliation checks that the graph representation remains consistent with the original business records.
This approach supports recommendation traceability and gives the operator more context than an isolated model output.
Recommendation controls
Mandatory constraints, including capacity suitability and operational requirements, are checked before candidates are ranked. The language model cannot rewrite these constraints.
If the ML service fails, the system can use an explicitly identified heuristic fallback. When required graph context or regulatory evidence is unavailable, the response explains the analytical limitation rather than presenting an incomplete result as fully supported.
Bookings and payments require confirmation through the Gateway. Analytical services have no direct transaction authority.
Development outcomes and evaluation
Development covers conditional workflows, service data contracts, graph context, document ingestion, referenced retrieval, and machine learning baselines.
The initial ML baselines use synthetic data. They support validation of the pipeline and model behavior under designed patterns. Effectiveness in real maritime operations still requires field data and a separate evaluation.
The testing approach covers service contracts, integration, dependency failures, retrieval quality, reference consistency, and compliance with operational constraints.
Status and next steps
OptiCargo remains in development. The next priorities are validation with approved operational data, calibration by route, operator evaluation, and monitoring changes in data distribution.
Field deployment also requires document quality review, infrastructure readiness, and comparison of recommendations with actual decisions and outcomes.
Code and documentation
Project scope
The case study focuses on service orchestration, operational graph context, machine learning baselines, referenced retrieval, and the separation of analysis from transaction authority.