TranslogiX Data Model and Entity Reference

TranslogiX stores all platform data in a PostgreSQL database managed with Drizzle ORM. This page documents every core entity, its fields, the enumerations used across the schema, and how entities relate to one another. Refer to this page when building integrations, writing queries, or understanding how data flows through the system.

Enumerations

These enums are defined at the database level using pgEnum and are referenced throughout the schema.

`userRoleEnum`

Controls which dashboard section a user can access and what API operations they can perform.

Value	Description
`ADMIN`	Full platform access, no transporter scope restriction
`TRANSPORTER`	Scoped to their linked transporter entity
`DRIVER`	Access to the driver section
`CUSTOMER`	Default role; access to the customer section

`transporterStatusEnum`

Value	Description
`active`	Transporter is operational
`inactive`	Transporter has been deactivated

`vehicleTypeEnum`

Value	Description
`TRUCK`	Standard truck
`DUMPER`	Dumper vehicle
`VAN`	Van
`OTHER`	Any other vehicle type

`vehicleStatusEnum`

Value	Description
`AVAILABLE`	Vehicle is ready to be assigned to a shipment
`BUSY`	Vehicle is currently assigned to an active shipment
`MAINTENANCE`	Vehicle is undergoing maintenance and unavailable

`shipmentStatusEnum`

Value	Description
`CREATED`	Shipment has been created but not yet assigned
`ASSIGNED`	A vehicle and transporter have been assigned
`PICKED_UP`	Cargo has been collected from the source
`IN_TRANSIT`	Shipment is on the way to the destination
`DELIVERED`	Shipment has been delivered successfully
`CANCELLED`	Shipment was cancelled; terminal state

Core entities

Users

The users table represents all authenticated accounts on the platform.

Field	Type	Notes
`id`	`uuid`	Primary key, auto-generated
`email`	`text`	Unique, required
`emailVerified`	`boolean`	Defaults to `false`
`name`	`text`	Required
`image`	`text`	Optional profile image URL
`role`	`userRoleEnum`	Defaults to `CUSTOMER`
`transporterId`	`uuid`	FK → `transporters.id`; set for TRANSPORTER users
`createdAt`	`timestamp`	Auto-set on insert
`updatedAt`	`timestamp`	Auto-set on insert

The transporterId field on a user is what links a TRANSPORTER-role account to a specific transporter entity. Without this link, the user cannot access any transporter-scoped API endpoints.

Transporters

The transporters table represents logistics companies or vendors operating on the platform.

Field	Type	Notes
`id`	`uuid`	Primary key, auto-generated
`name`	`text`	Required
`gstNumber`	`text`	Optional GST registration number
`contactPerson`	`text`	Required
`phone`	`text`	Required
`email`	`text`	Optional contact email
`status`	`transporterStatusEnum`	Defaults to `active`
`createdAt`	`timestamp`	Auto-set on insert
`updatedAt`	`timestamp`	Auto-set on insert

Vehicles

The vehicles table tracks all vehicles registered under a transporter.

Field	Type	Notes
`id`	`uuid`	Primary key, auto-generated
`vehicleNumber`	`text`	Registration/plate number; required
`transporterId`	`uuid`	FK → `transporters.id`; required
`vehicleType`	`vehicleTypeEnum`	Required
`capacityKg`	`integer`	Maximum load capacity in kilograms; required
`currentLocation`	`text`	Optional free-text location
`status`	`vehicleStatusEnum`	Defaults to `AVAILABLE`
`lastMaintenanceDate`	`date`	Optional
`createdAt`	`timestamp`	Auto-set on insert
`updatedAt`	`timestamp`	Auto-set on insert

Routes

The routes table defines predefined origin–destination corridors with associated rates and timing.

Field	Type	Notes
`id`	`uuid`	Primary key, auto-generated
`origin`	`text`	Required
`destination`	`text`	Required
`distanceKm`	`decimal`	Distance in kilometres; required
`estimatedTime`	`text`	Human-readable duration (e.g., “3 days”); required
`billingRate`	`decimal`	Rate charged to the customer; required
`vendorRate`	`decimal`	Rate paid to the transporter; required
`createdAt`	`timestamp`	Auto-set on insert
`updatedAt`	`timestamp`	Auto-set on insert

Shipments

The shipments table is the central entity in TranslogiX. It records cargo details, assignment information, and current status.

Field	Type	Notes
`id`	`uuid`	Primary key, auto-generated
`packageCode`	`text`	Unique identifier for the shipment; required
`source`	`text`	Pickup location; required
`destination`	`text`	Delivery location; required
`materialType`	`text`	Description of the cargo type; required
`grossWeightKg`	`decimal`	Total weight including packaging; required
`tareWeightKg`	`decimal`	Weight of packaging alone; optional
`quantity`	`integer`	Number of units; required
`pickupDate`	`date`	Scheduled pickup date; required
`deliveryDeadline`	`date`	Latest acceptable delivery date; required
`transporterId`	`uuid`	FK → `transporters.id`; optional until assigned
`vehicleId`	`uuid`	FK → `vehicles.id`; optional until assigned
`routeId`	`uuid`	FK → `routes.id`; optional
`status`	`shipmentStatusEnum`	Defaults to `CREATED`
`createdAt`	`timestamp`	Auto-set on insert
`updatedAt`	`timestamp`	Auto-set on insert

TrackingUpdates

The tracking_updates table stores location events appended throughout a shipment’s journey.

Field	Type	Notes
`id`	`uuid`	Primary key, auto-generated
`shipmentId`	`uuid`	FK → `shipments.id`; required
`location`	`text`	Human-readable location name; required
`latitude`	`decimal`	Optional GPS latitude (-90 to 90)
`longitude`	`decimal`	Optional GPS longitude (-180 to 180)
`createdAt`	`timestamp`	Auto-set on insert

Entity relationships

users ──────────────────── transporters
  (transporterId)               │
                         ┌──────┴──────┐
                      vehicles      shipments ──── tracking_updates
                         │               │
                         └───────────────┘ (vehicleId)
                                    │
                                 routes (routeId)

The Drizzle relations are defined as follows:

Users relations

A user belongs to one transporter (via transporterId) and has many sessions and accounts (managed by BetterAuth).

Transporters relations

A transporter has many vehicles and many shipments.

Vehicles relations

A vehicle belongs to one transporter and has many shipments.

Routes relations

A route has many shipments.

Shipments relations

A shipment belongs to one transporter, one vehicle, and one route. It has many tracking updates.

TrackingUpdates relations

A tracking update belongs to one shipment.

Authentication tables

TranslogiX uses BetterAuth for session management. Three additional tables are maintained by the auth library and are not typically queried directly by application code:

Table	Purpose
`sessions`	Active user sessions; cascade-deleted when the user is deleted
`accounts`	OAuth and credential provider account links per user
`verifications`	Short-lived tokens for email verification and similar flows

Get Started

Core Concepts

Configuration

TranslogiX Data Model and Entity Reference

Enumerations

`userRoleEnum`

`transporterStatusEnum`

`vehicleTypeEnum`

`vehicleStatusEnum`

`shipmentStatusEnum`

Core entities

Users

Transporters

Vehicles

Routes

Shipments

TrackingUpdates

Entity relationships

Authentication tables

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Documentation Index

​Enumerations

​userRoleEnum

​transporterStatusEnum

​vehicleTypeEnum

​vehicleStatusEnum

​shipmentStatusEnum

​Core entities

​Users

​Transporters

​Vehicles

​Routes

​Shipments

​TrackingUpdates

​Entity relationships

​Authentication tables

Build docs developers (and LLMs) love

Enumerations

`userRoleEnum`

`transporterStatusEnum`

`vehicleTypeEnum`

`vehicleStatusEnum`

`shipmentStatusEnum`

Core entities

Users

Transporters

Vehicles

Routes

Shipments

TrackingUpdates

Entity relationships

Authentication tables