Conceptual specifications

Domain entities & data modeling

Conceptual relationships among organizations, partners, loads, stops, events, documents and later commercial records.

Educational / conceptual specification · Not a released implementation contract

Isometric truck surrounded by scattered emails, spreadsheets and paper forms — Illustrative

Identity, movement and evidence

Organization and User / Role are proposed scope and access concepts. Customer identifies commercial context. Carrier, Driver and Equipment identify the organization and resources executing a movement. A Load holds the shared transportation reference and connects ordered Stops, ShipmentEvents and Documents.

Quote, Rate and Invoice are later commercial concepts. Point-to-point freight is the first modeling focus; multi-stop, LTL and consolidation may require clearer distinctions between shipment and movement. This vocabulary is not a set of finalized PostgreSQL tables or migrations.

CONCEPTUAL DOMAIN RELATIONSHIPS / NOT FINALIZED TABLES

OrganizationUser / Role · Proposed access boundary

Commercial context

Customer

Quote · Rate

Invoice (future)

Transportation core

Load → Stop

ShipmentEvent

Document / BOL / POD

Execution partners

Carrier

Driver

Equipment

Stable references connect the domains. State changes retain actor, source and occurrence time.

References must survive handoffs

Internal identity should remain distinct from a customer's order, a WMS shipment and a carrier's own reference. Proposed external mappings need organization scope and source identity so the same outside value cannot be accidentally interpreted as another partner's shipment.

Stops should preserve requested windows, appointment agreements and actual observations separately. Documents should identify their kind, related entity and review state. Custom fields need types and validation; they should not substitute for a core relationship that the domain needs to understand.

ILLUSTRATIVE CONCEPTUAL SCHEMA — NOT AN IMPLEMENTED API CONTRACT

{
  "reference": "ILLUSTRATION-LOAD-A",
  "externalReferences": [
    { "source": "example-wms", "kind": "shipment", "value": "EXAMPLE-SHIPMENT" }
  ],
  "stops": [{ "sequence": 1, "kind": "pickup", "facilityRef": "EXAMPLE-DOCK" }],
  "documents": [{ "kind": "pod", "reviewState": "expected" }]
}

Access follows the relationship

A proposed organization boundary must cover related stops, events, attachments, exports and mappings, not only the load list. A guessed document reference should not bypass the access rules applied to its parent. Those requirements belong in both contracts and future tests.

No access-control implementation or production schema is claimed by this guide. The next design work is to validate ownership, indexing, uniqueness and lifecycle rules against real anonymized scenarios, then document the implemented contracts when public source is available.

Explore secure-operation requirements