# Core Concepts

Transportial is built on the **OTM5** (Open Trip Model 5) standard — an open data model for logistics. This page explains the key entities and how they relate.

## Entity Hierarchy

The core transport flow is built around four entities:


```
Platform
  └── Business (your company, customers, carriers)
        └── TransportOrder (a request to move goods)
              └── Consignment (a line-item grouping of goods)
                    └── Trip (the execution plan)
                          └── Action (atomic tasks: load, move, unload)
```

## Platform

A **Platform** is your workspace — the top-level container for all data. When you register, a platform is created for your organization. Platforms have configurable settings for UI, billing, pricing, translations, and alerts.

Every entity belongs to a platform. Users and businesses are scoped to their platform.

## Business

A **Business** represents a company or organization. You'll create businesses for:

- Your own company
- Your customers (shippers)
- Your carriers and subcontractors
- Receivers and other parties


Businesses have contact details, locations, tax identifiers (VAT, EORI, CoC), and can be organized hierarchically with `partOf` relationships.

## Transport Order

A **TransportOrder** is the starting point of any transport operation — a request to move goods between locations. It tracks the full lifecycle from initial request through planning, execution, and invoicing.

### Statuses

| Status | Description |
|  --- | --- |
| `concept` | Draft, not yet submitted |
| `requested` | Submitted, awaiting acceptance |
| `accepted` | Confirmed by the carrier |
| `calculated_trip` | Route has been calculated |
| `partially_planned` | Some consignments are planned |
| `planned` | All consignments have trips assigned |
| `actual` | Currently in execution |
| `realized` | Completed successfully |
| `cancelled` | Cancelled before completion |
| `declined` | Rejected by the carrier |


### Key Fields

- **name** — Human-readable identifier
- **customer** — The business requesting the transport
- **consignments** — The line items (goods to be moved)
- **expectedRevenue / expectedCost** — Financial estimates
- **administration** — Linked invoicing and billing info


## Consignment

A **Consignment** is a logical grouping of goods within a transport order. A single transport order can have multiple consignments — for example, one pickup going to multiple destinations.

### Statuses

| Status | Description |
|  --- | --- |
| `draft` | Being composed |
| `requested` | Submitted |
| `confirmed` | Accepted and ready for planning |
| `planned` | Trip assigned |
| `in_transit` | Currently moving |
| `completed` | Delivered |
| `cancelled` | Cancelled |


Consignments also support partial statuses: `partially_planned`, `partially_in_transit`, `partially_completed`.

### Key Fields

- **goods** — List of cargo items (pallets, packages, containers, etc.)
- **trip** — The execution plan assigned to this consignment
- **actions** — Events that have occurred (loading, unloading, etc.)


## Goods

**Goods** represent the physical cargo. They use polymorphism — the two main types are:

- **Items** — General cargo with quantity, weight, dimensions
- **TransportEquipment** — Containers, trailers, and other transport equipment


## Trip

A **Trip** is the execution plan for moving consignments. It defines the route, assigns a vehicle and chauffeur, and contains an ordered sequence of actions.

Trips support multi-modal transport:

- **Road** — Route calculation via GraphHopper
- **Maritime** — Route calculation via SeaRoute
- **Rail** and **Air** — Supported in the data model


### Key Fields

- **vehicle** — The assigned vehicle
- **chauffeur** — The assigned driver(s)
- **actions** — Ordered list of tasks to execute
- **route** — Calculated route geometry


## Action

An **Action** is an atomic task within a trip. Actions are polymorphic — each type represents a different operation:

| Type | Description |
|  --- | --- |
| `load` | Load goods onto the vehicle |
| `unload` | Unload goods at destination |
| `move` | Drive between locations |
| `stop` | Scheduled stop |
| `break` | Driver rest break |
| `wait` | Waiting time (at dock, border, etc.) |
| `handOver` | Transfer goods to another party |
| `customs` | Customs clearance |
| `attachChauffeur` | Assign a driver mid-trip |
| `attachTransportEquipment` | Attach trailer or container |


Actions have constraints (time windows, location requirements) and track their lifecycle through events.

## Events

**Events** record what happens during transport execution. They are also polymorphic:

- **ArrivalEvent / DepartureEvent** — Vehicle arrives or departs a location
- **LocationUpdateEvent** — GPS position update
- **GateInEvent / GateOutEvent** — Enters or exits a facility
- **SensorUpdateEvent** — Temperature, humidity, or other sensor data
- **StartMovingEvent / StopMovingEvent** — Motion detection
- **CapacityChangeEvent** — Loading/unloading changes cargo capacity


## Supporting Entities

### Location

Geographic points or areas. Locations have addresses, coordinates, and can be linked to businesses (warehouses, offices, etc.).

### Vehicle

Vehicles in your fleet. Tracked for planning, GPS monitoring, and compliance. Linked to chauffeurs through activity scheduling.

### Chauffeur

Drivers with schedules, activity tracking, and availability management. Chauffeurs are linked to users and can be assigned to trips.

### Invoice & Quote

Financial documents generated from transport orders. Invoices track charges per consignment line. Quotes provide pricing before acceptance.

## Authentication & Permissions

The API uses JWT bearer tokens. Each user session carries a set of permissions that control access to specific operations. Common permissions include:

- `create:transportOrder`, `get:transportOrders` — Transport order management
- `create:business`, `get:businesses` — Business management
- `browse:app-store`, `install:app` — App store access
- `create:chauffeur:activity` — Driver scheduling


See the [Quickstart](/guides/quickstart) for authentication details.