Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/plantasur-dev/ship-quote/llms.txt

Use this file to discover all available pages before exploring further.

Ship Quote is a shipping rate comparison platform built on Node.js, Express 5, and MongoDB. It solves the problem of querying multiple freight carriers one-by-one by acting as a single orchestration layer — your application sends one request describing the shipment, and Ship Quote fans out to every configured carrier simultaneously, normalises the results, and returns a unified array of quotes you can present directly to a user or use programmatically to select the cheapest or fastest option.

​
How It Works

Dual Provider Architecture

Rates are sourced from two complementary pools in parallel: static providers read pre-loaded tariff tables stored in MongoDB, while API providers call live external carrier endpoints in real time. Both pools are normalised to the same response shape before being returned.

Automatic Scope Detection

Every request carries a countryCode. Ship Quote compares it to the DEFAULT_COUNTRY environment variable and automatically classifies the shipment as national or international. Only carriers that support the detected scope are queried, preventing irrelevant results.

Pallets & Parcels

Two shipment types are supported natively. Pallets are validated against per-carrier dimension and weight constraints and matched to the closest pallet category (e.g. quarter, half, full). Parcels use a lighter validation path for standard packages.

Resilient Error Handling

A failure from one external carrier API never blocks the rest. Each provider is called independently; errors are captured per-provider and surfaced in the response incidents field so callers can see exactly what went wrong without losing quotes from healthy providers.

O(1) In-Memory Cache

On startup the server loads zones, rates, provinces, and countries into Map structures keyed for direct lookup. This eliminates repeated database round-trips on the hot path and keeps median response times low even under concurrent load.

Dynamic Surcharge Engine

Carriers can be configured with fuel surcharges (percentage or fixed), excess-weight blocks, and dimensional penalties. The engine calculates and itemises every surcharge in the response breakdown array so consumers know exactly what drives the final price.

​
Supported Carriers

Ship Quote ships with bootstrap data and adapter support for the following carriers:
CarrierProvider TypeShipment Types
CaycoStatic (DB rates)Pallets
TecumStatic (DB rates)Pallets
MRWStatic (DB rates)Parcels
CorreosexpressStatic (DB rates)Parcels
DachserExternal APIPallets
Dachser is queried via its live API and requires a valid DACHSER_API_KEY in your environment. If the key is absent, Dachser is skipped and no error is raised for the other carriers.

​
Scope Detection

The scope system is the foundation of carrier filtering. When a rate comparison request arrives, the getScope helper compares the request’s countryCode to the DEFAULT_COUNTRY environment variable: 
// api/src/lib/constants/scopes.zone.js
export const SCOPE_TYPES = {
    NATIONAL: 'national',
    INTERNATIONAL: 'international'
};

export function getScope(countryCode) {
    return countryCode === process.env.DEFAULT_COUNTRY
        ? SCOPE_TYPES.NATIONAL      // 'national'
        : SCOPE_TYPES.INTERNATIONAL; // 'international'
}
Each agency in the database carries a rules.coverage array (e.g. ["national", "international"]). Ship Quote filters the active agency list to those whose coverage includes the detected scope before dispatching any provider calls. This means adding international carriers in the future requires only a database record change — no code modifications.

​
Agency Types

Agencies are typed as one of three values defined in api/src/lib/constants/type.agency.js:
  • static — rates are read entirely from MongoDB (zones, pallet types, rate tables)
  • api — rates are fetched from an external carrier API via a carrier adapter
  • hybrid — both sources are combined for a single agency

​
Project Structure

ship-quote/
├── api/          # Node.js + Express 5 backend
│   └── src/
│       ├── api/
│       │   ├── controllers/   # Route handlers
│       │   ├── middlewares/   # Validation & error handling
│       │   ├── services/      # Rate engine, caching, agencies
│       │   │   └── rates/
│       │   │       ├── providers/   # Static & API provider logic
│       │   │       ├── domains/     # Result construction
│       │   │       └── presenters/  # Response formatting
│       │   └── docs/          # OpenAPI specification
│       └── lib/
│           ├── models/        # Mongoose schemas
│           ├── constants/     # Scope types, agency types, units
│           ├── configs/       # DB & server bootstrap
│           └── logger/        # Winston + Morgan (Loki-compatible)
└── web/          # React + Vite frontend

​
Next Steps

Quickstart

Clone the repo, seed the database, and make your first rate comparison request in under five minutes.

Configuration

Full reference for every environment variable in the API and web frontend.

Architecture Overview

Deep dive into the rate engine, provider model, caching strategy, and request lifecycle.

API Reference

Interactive endpoint documentation for all routes, request schemas, and response shapes.

Build docs developers (and LLMs) love

Get started for freeTalk to us