Entity System Overview

Introduction

The Entity System is the foundation of CXTMS, providing a comprehensive data model for all business objects in the transportation and logistics domain. With 121 pre-defined entities, the system covers every aspect of freight forwarding operations, from customer management to financial transactions, shipping documentation, and warehouse operations.

Entities in CXTMS are more than just database tables - they are intelligent business objects with built-in behaviors, relationships, validations, and workflow integration capabilities. This low-code approach allows rapid development of complex logistics applications while maintaining data integrity and business rule enforcement.

Core Concepts

What is an Entity?

An entity represents a business object or concept in the TMS system. Each entity:

Has a unique identifier and standardized naming convention
Contains fields (attributes) that store data
Defines relationships with other entities
Includes business rules and validations
Integrates with workflows, permissions, and UI components
Supports custom extensions and configurations
Inherits automatic audit tracking (created/modified timestamps and users)
Publishes domain events for cross-entity communication

Entity Architecture

All entities in the system follow a consistent inheritance hierarchy:

BaseEntity
  ↓
AuditableEntity
  ↓
[All Business Entities]

BaseEntity provides:

Domain events infrastructure for publishing business events
Methods to add, remove, and clear domain events
Foundation for all entity classes

AuditableEntity extends BaseEntity and adds:

CreatedBy - User ID who created the entity
Created - Timestamp when entity was created
LastModifiedBy - User ID who last modified the entity
LastModified - Timestamp of last modification
References to ApplicationUser for created and updated users

All business entities inherit from AuditableEntity, providing automatic audit trail tracking across the entire system.

Architecture Patterns

The entity system implements several Domain-Driven Design patterns:

1. Aggregate Roots

Aggregate roots are entities that serve as the primary entry point for related entities, enforcing consistency boundaries:

Order - Controls order commodities, charges, entities, carriers, documents, and events
Job - Aggregates multiple orders, commodities, and accounting transactions
Commodity - Manages hierarchical commodity containers and tracking
AccountingTransaction - Coordinates charges, payments, and accounting items

2. Hierarchical Entities

Some entities support parent-child relationships for organizational structures:

Division - Organizational hierarchy within a tenant (ParentDivisionId)
Commodity - Container system where commodities can contain other commodities (ContainerCommodityId)
Contact - Hierarchical contact relationships (ParentContactId)

3. Polymorphic Entities

Certain entities represent multiple business concepts through type discrimination:

Contact - Can be Customer, Vendor, Agent, Carrier, Broker, or Employee (via ContactType enum)
AccountingTransaction - Invoice, Bill, Credit Memo, Debit Memo, or Payment (via AccountingTransactionType enum)
Order - Multiple order types including Shipment, Quote, Warehouse Receipt (via OrderTypes enum)

4. Junction Tables

Many-to-many relationships are implemented through junction entities:

OrderCommodity - Links orders to commodities
OrderCarrier - Associates carriers with orders
OrderCharge - Connects charges to orders
JobOrder - Links jobs to orders
AccountingTransactionCharges - Associates charges with accounting transactions
AccountingTransactionPayment - Links payments to transactions

5. Tag System

Flexible tagging across multiple entity types:

Tag - Reusable tag definitions with entity type discrimination
OrderTag, CommodityTag, InventoryItemTag - Entity-specific tag assignments

6. Custom Values & Extensions

Many entities support extensibility through custom values:

Order, Job, Commodity, Contact - Include CustomValues dictionary (Dictionary<string, object?>)
CustomField - System-wide custom field definitions
Enables adding custom properties without schema changes

7. Audit Trail

Comprehensive change tracking across all entities:

All entities inherit CreatedBy, Created, LastModifiedBy, LastModified
AuditChangeLog entity stores detailed change history
Integration with ApplicationUser for user attribution

8. Multi-Tenancy

Data isolation through organizational structures:

Tenant - Top-level tenant isolation
Organization - Primary organizational container
Division - Hierarchical sub-organizations
Most entities include OrganizationId for data partitioning

9. Domain Events

Event-driven architecture for cross-entity communication:

Entities publish events on significant state changes
Examples: OrderStatusChangedEvent, CommodityStatusChangedEvent
Events processed asynchronously for loose coupling

10. Draft Mode

Several entities support draft state before finalization:

Order, Job, AccountingTransaction include IsDraft flag
Enables work-in-progress without affecting operational data

Entity Categories

The 121 entities are organized into 11 logical categories:

1. Core Business Entities (25+ entities)

Primary business objects for operational workflows:

Aggregate Roots:

Order - Shipments, quotes, warehouse bookings, and other order types
Job - Container for multiple related orders and transactions
Contact - Customers, vendors, agents, carriers, brokers, employees

Order Supporting Entities:

OrderCommodity - Junction table linking orders to commodities
OrderCarrier - Carrier assignments to orders
OrderCharge - Charges applied to orders
OrderDocument - Documents attached to orders
OrderEntity - Dynamic entity roles (shipper, consignee, notify party)
OrderEvent - Shipment tracking events
OrderStatus - Order status definitions
OrderTag - Tag assignments for orders
LinkedOrder - Relationships between orders (master/house bills)
TrackingEvent - Detailed tracking information
EventDefinition - Tracking event type definitions

Organization Entities:

Organization - Root organization entity
Division - Hierarchical organizational divisions
OrganizationConfig - Organization configuration settings

Job Supporting Entities:

JobOrder - Junction table for job-order relationships
JobAccountingTransaction - Links jobs to accounting transactions
JobStatus - Job status definitions

2. Financial & Accounting Entities (11 entities)

Complete accounting subsystem for invoicing, billing, and payments:

Core Financial Entities:

AccountingTransaction - Invoices, bills, credit memos, payments
Payment - Customer and vendor payments
Charge - Freight charges, surcharges, fees
AccountingAccount - Chart of accounts
AccountingItem - Accounting item definitions (revenue/expense categories)

Supporting Entities:

AccountingTransactionCharges - Junction table for transaction-charge associations
AccountingTransactionPayment - Payment applications to transactions
AccountingTransactionExtensions - Extended transaction properties
PaymentTerm - Payment terms (Net 30, Net 60, etc.)
SalesTax - Sales tax definitions and rates
Currency - Currency definitions and exchange rates

3. Operational & Logistics Entities (13+ entities)

Commodity management, packaging, and equipment tracking:

Commodity Management:

Commodity - Core commodity entity with container hierarchy support
CommodityType - Commodity classifications
CommodityStatus - Commodity lifecycle statuses
CommodityTag - Tag assignments for commodities
CommodityTrackingNumber - Multiple tracking numbers per commodity

Packaging & Containers:

ContainerType - Shipping container types (20', 40', etc.)
ContainerDescription - Container specifications
PackageType - Package classifications (carton, pallet, etc.)
PackageCategory - Package category groupings

Equipment & Inventory:

EquipmentType - Transportation equipment types
CarrierEquipment - Carrier-owned equipment tracking
InventoryItem - Warehouse inventory/stock management
InventoryItemTag - Tag assignments for inventory

4. Document Management Entities (1 entity)

File and document attachment system:

Attachment - File attachments linked to any entity

note

The Document entity referenced in earlier documentation has been removed from the backend implementation. File management is handled through the Attachment entity.

5. Job & Workflow Entities (9 entities)

Workflow automation and business process management:

Workflow System:

Workflow - YAML-based workflow definitions with triggers and tasks
BusinessRule - Business rule definitions and conditions
ActionEvent - Action event history and tracking

Job System:

Job - Job aggregate root (covered in Core Business)
JobOrder - Job-order junction table
JobAccountingTransaction - Job-transaction junction table
JobStatus - Job status definitions

Notifications & Verification:

VerificationCode - Verification codes for workflows and notifications

6. Geographic & Transportation Entities (12 entities)

Location data, routing, and vessel management:

Geographic Entities:

Country - Country definitions with ISO codes
State - State/province definitions
City - City definitions
PostalCode - Postal code database
Port - Seaports, airports, rail terminals (UN/LOCODE)

Transportation & Routing:

Route - Transportation routes with carrier and transit time
RouteLeg - Individual segments of multi-leg routes
RouteRouteLeg - Junction table for route-leg associations
Lane - Transportation lanes between locations
Vessel - Ship/vessel definitions
ModeOfTransportation - Transport modes (Air, Ocean, Rail, Truck)
ModeOfTransportationDiscount - Mode-specific discount structures

7. Pricing & Rates Entities (4 entities)

Rate management, tariffs, and discounts:

Rate - Pricing rates with route, tariff, and validity support
Tariff - Tariff structures and options
Discount - Discount definitions with workflow integration
ContactDiscount - Customer/vendor-specific discounts

note

Additional discount entities like DiscountCountry and DiscountWorkflow provide geographic and workflow-based discount capabilities.

8. Warehouse & Inventory Entities (4 entities)

Warehouse operations and location management:

WarehouseLocation - Warehouse location hierarchy (aisle, rack, bin)
WarehouseZone - Warehouse zone definitions
InventoryItem - Inventory/stock tracking (covered in Operational)
InventoryItemTag - Inventory tagging

9. App & System Entities (20+ entities)

Low-code platform infrastructure and customization:

App Module System:

AppModule - Low-code app modules with YAML document storage
AppManifest - Application manifest definitions
AppRoute - Application routing configuration
AppComponent - UI component definitions
AppPermission - Permission system with role assignments
AppPermissionRoleAssign, AppPermissionRoleUnassign - Permission-role mappings

Customization:

CustomField - Custom field definitions
CustomCode - Custom code definitions
EntityType - Dynamic entity type definitions
EntityField - Dynamic field definitions

System Features:

SystemFeature - Feature flag definitions
SystemFeatureActivation - Feature activation status
EventDefinition - System event definitions
DocumentTemplate - Document template definitions
KnowledgeAsset - Documentation and knowledge base
AuditChangeLog - Detailed change audit logs
ApiCredential - API credentials and authentication
ChatMessage - In-app messaging

10. Calendar & Events Entities (7 entities)

Scheduling, appointments, and calendar management:

CalendarEntity - Calendar definitions
CalendarEvent - Scheduled events and appointments
CalendarRecurrenceRule - Event recurrence patterns
CalendarExceptionDate - Exceptions to recurrence rules
CalendarBusinessHour - Business hours configuration
CalendarAvailabilityBlock - Availability blocking
CalendarAvailabilityRecurrenceRule - Recurring availability rules

11. User & Security Entities (10 entities)

User management, authentication, and permissions:

User Management:

ApplicationUser (ASP.NET Identity) - User accounts
AspNetUserEmployee - User-employee mapping
AspNetUserGroup - User-group assignments
UserEmployee - Employee contact linkage
UserSetting - User preferences and settings

Security & Permissions:

UserGroup - User group definitions
UserGroupRole - Group-role assignments
Role - Role definitions with permissions
AppPermission - Application permissions (covered in App & System)

Entity Relationships

Aggregate Patterns

Entities are organized into aggregates with clear boundaries:

Order Aggregate:

Order (Root)
├── OrderCommodity → Commodity
├── OrderCharge → Charge
├── OrderEntity (Shipper, Consignee, etc.)
├── OrderCarrier → Contact (Carrier)
├── OrderDocument
├── OrderTag → Tag
└── OrderEvent → TrackingEvent

Job Aggregate:

Job (Root)
├── JobOrder → Order
├── JobAccountingTransaction → AccountingTransaction
└── Commodity (direct association)

AccountingTransaction Aggregate:

AccountingTransaction (Root)
├── AccountingTransactionCharges → Charge
├── AccountingTransactionPayment → Payment
├── AccountingItem
└── AccountingAccount

Relationship Types

One-to-Many:

Order → OrderCommodity
Job → JobOrder
Contact → ContactAddress
Division → Division (parent-child)

Many-to-Many (via Junction Tables):

Order ↔ Commodity (via OrderCommodity)
Order ↔ Charge (via OrderCharge)
Job ↔ Order (via JobOrder)
AccountingTransaction ↔ Charge (via AccountingTransactionCharges)

Hierarchical:

Division (ParentDivisionId → DivisionId)
Commodity (ContainerCommodityId → CommodityId)
Contact (ParentContactId → ContactId)

Polymorphic:

Contact (ContactType enum: Customer, Vendor, Agent, Carrier, Broker, Employee)
AccountingTransaction (TransactionType enum: Invoice, Bill, CreditMemo, Payment)

Working with Entities

Creating Entities in YAML

Entities can be created and configured through YAML in workflows and app modules:

# Creating an Order
- type: createEntity
  entityName: Order
  properties:
    orderNumber: "ORD-2025-001"
    orderType: Shipment
    billToContactId: ${customerId}
    divisionId: ${divisionId}
    customValues:
      customerReference: "REF-12345"
      specialInstructions: "Handle with care"

Querying Entities with Relationships

# Query order with all related data
- type: queryEntity
  entityName: Order
  filter:
    orderId: ${orderId}
  include:
    - OrderCommodity.Commodity
    - OrderCharge.Charge
    - OrderEntity
    - OrderCarrier.Contact
    - BillToContact

Updating Entities

# Update order status
- type: updateEntity
  entityName: Order
  filter:
    orderId: ${orderId}
  properties:
    orderStatusId: ${completedStatusId}
    customValues:
      completedDate: ${now}

Using Custom Values

# Add custom properties to entities
- type: createEntity
  entityName: Commodity
  properties:
    description: "Electronic Components"
    quantity: 100
    customValues:
      sku: "ELECT-001"
      serialNumbers: ["SN001", "SN002"]
      hazmat: false
      lotNumber: "LOT-2025-Q1"

Working with Tags

# Create and assign tags
- type: createEntity
  entityName: Tag
  properties:
    entityName: Order
    name: "Expedited"
    color: "#FF5733"

- type: createEntity
  entityName: OrderTag
  properties:
    orderId: ${orderId}
    tagId: ${expeditedTagId}

Handling Domain Events

# React to entity events in workflows
- trigger: DomainEvent
  eventType: OrderStatusChangedEvent
  actions:
    - type: sendEmail
      when: ${event.newStatus == 'Delivered'}
      to: ${order.billToContact.email}
      subject: "Your shipment has been delivered"

Multi-Tenancy Usage

# Entities automatically filter by organization
- type: queryEntity
  entityName: Contact
  filter:
    contactType: Customer
    # organizationId automatically applied from current user context
    isActive: true

Complete Entity Catalog

Entity Name	Category	Aggregate Root	Key Relationships	Description
Order	Core Business	Yes	OrderCommodity, OrderCharge, JobOrder	Shipments, quotes, warehouse bookings
Job	Core Business	Yes	JobOrder, JobAccountingTransaction	Container for multiple orders
Contact	Core Business	Yes	ContactAddress, Orders, Jobs	Customers, vendors, agents, carriers
Commodity	Operational	Yes	OrderCommodity, CommodityTrackingNumber	Freight items with container hierarchy
AccountingTransaction	Financial	Yes	AccountingTransactionCharges, AccountingTransactionPayment	Invoices, bills, credit memos
OrderCommodity	Core Business	No	Order, Commodity	Junction: Order to Commodity
OrderCharge	Core Business	No	Order, Charge	Junction: Order to Charge
OrderCarrier	Core Business	No	Order, Contact	Junction: Order to Carrier
OrderDocument	Core Business	No	Order, Attachment	Order document attachments
OrderEntity	Core Business	No	Order, Contact	Dynamic entity roles (shipper, consignee)
OrderEvent	Core Business	No	Order, TrackingEvent	Order tracking events
OrderStatus	Core Business	No	Order	Order status definitions
OrderTag	Core Business	No	Order, Tag	Order tagging
LinkedOrder	Core Business	No	Order (parent), Order (child)	Order relationships (master/house)
JobOrder	Core Business	No	Job, Order	Junction: Job to Order
JobAccountingTransaction	Financial	No	Job, AccountingTransaction	Junction: Job to Transaction
JobStatus	Core Business	No	Job	Job status definitions
Division	Core Business	No	Organization, Parent Division	Hierarchical org structure
Organization	Core Business	No	Tenant	Root organization
OrganizationConfig	Core Business	No	Organization	Org configuration
Payment	Financial	No	AccountingTransactionPayment	Customer/vendor payments
Charge	Financial	No	OrderCharge, AccountingTransactionCharges	Freight charges and fees
AccountingAccount	Financial	No	AccountingTransaction	Chart of accounts
AccountingItem	Financial	No	Charge, AccountingTransaction	Revenue/expense categories
AccountingTransactionCharges	Financial	No	AccountingTransaction, Charge	Junction: Transaction to Charge
AccountingTransactionPayment	Financial	No	AccountingTransaction, Payment	Junction: Transaction to Payment
PaymentTerm	Financial	No	Contact, AccountingTransaction	Payment terms (Net 30, etc.)
SalesTax	Financial	No	Charge	Sales tax definitions
Currency	Financial	No	Rate, Charge	Currency definitions
CommodityType	Operational	No	Commodity	Commodity classifications
CommodityStatus	Operational	No	Commodity	Commodity lifecycle statuses
CommodityTag	Operational	No	Commodity, Tag	Commodity tagging
CommodityTrackingNumber	Operational	No	Commodity	Multiple tracking numbers
ContainerType	Operational	No	Commodity	Container types (20', 40')
ContainerDescription	Operational	No	ContainerType	Container specifications
PackageType	Operational	No	Commodity	Package types (carton, pallet)
PackageCategory	Operational	No	PackageType	Package category groupings
EquipmentType	Operational	No	Order, CarrierEquipment	Equipment classifications
CarrierEquipment	Operational	No	Contact (Carrier), EquipmentType	Carrier equipment tracking
InventoryItem	Operational	No	Commodity, WarehouseLocation	Inventory/stock management
InventoryItemTag	Operational	No	InventoryItem, Tag	Inventory tagging
Attachment	Document	No	Order, Job, Contact (any entity)	File attachments
Workflow	Job & Workflow	No	Order, Job	YAML workflow definitions
BusinessRule	Job & Workflow	No	Various entities	Business rule engine
ActionEvent	Job & Workflow	No	Various entities	Action event history
VerificationCode	Job & Workflow	No	Various entities	Verification codes
Country	Geographic	No	State, Port, Route	Country definitions
State	Geographic	No	Country, City	State/province definitions
City	Geographic	No	State, PostalCode	City definitions
PostalCode	Geographic	No	City	Postal code database
Port	Geographic	No	Country, Route	Seaports, airports, terminals
Route	Geographic	Yes	RouteLeg, Rate, Port	Transportation routes
RouteLeg	Geographic	No	Route, Port	Route segments
Lane	Geographic	No	ModeOfTransportation	Transportation lanes
Vessel	Geographic	No	Port	Ship/vessel definitions
ModeOfTransportation	Geographic	No	Lane, Rate	Transport modes
ModeOfTransportationDiscount	Pricing	No	ModeOfTransportation, Discount	Mode-specific discounts
Rate	Pricing	No	Route, Tariff, AccountingItem	Pricing rates
Tariff	Pricing	No	Rate	Tariff structures
Discount	Pricing	No	Contact, ModeOfTransportation	Discount definitions
ContactDiscount	Pricing	No	Contact, Discount	Customer/vendor discounts
WarehouseLocation	Warehouse	No	WarehouseZone, InventoryItem	Warehouse locations
WarehouseZone	Warehouse	No	WarehouseLocation	Warehouse zones
AppModule	App & System	No	AppRoute, AppComponent, AppPermission	Low-code app modules
AppManifest	App & System	No	AppModule	App manifests
AppRoute	App & System	No	AppModule	App routing
AppComponent	App & System	No	AppModule	UI components
AppPermission	App & System	No	AppModule, UserGroup	Permission system
CustomField	App & System	No	EntityType	Custom field definitions
CustomCode	App & System	No	Various	Custom code definitions
EntityType	App & System	No	EntityField	Entity type definitions
EntityField	App & System	No	EntityType	Field definitions
SystemFeature	App & System	No	SystemFeatureActivation	Feature flags
SystemFeatureActivation	App & System	No	SystemFeature	Feature activation
EventDefinition	App & System	No	TrackingEvent	Event type definitions
DocumentTemplate	App & System	No	Workflow	Document templates
KnowledgeAsset	App & System	No	Various	Knowledge base
AuditChangeLog	App & System	No	All entities	Change audit logs
ApiCredential	App & System	No	Organization	API credentials
ChatMessage	App & System	No	ApplicationUser	In-app messaging
CalendarEntity	Calendar	No	CalendarEvent	Calendar definitions
CalendarEvent	Calendar	No	CalendarEntity	Events and appointments
CalendarRecurrenceRule	Calendar	No	CalendarEvent	Recurrence patterns
CalendarExceptionDate	Calendar	No	CalendarRecurrenceRule	Recurrence exceptions
CalendarBusinessHour	Calendar	No	CalendarEntity	Business hours
CalendarAvailabilityBlock	Calendar	No	CalendarEntity	Availability blocking
CalendarAvailabilityRecurrenceRule	Calendar	No	CalendarAvailabilityBlock	Recurring availability
ApplicationUser	User & Security	No	Contact, UserGroup	User accounts (ASP.NET Identity)
AspNetUserEmployee	User & Security	No	ApplicationUser, Contact	User-employee mapping
AspNetUserGroup	User & Security	No	ApplicationUser, UserGroup	User-group assignments
UserEmployee	User & Security	No	ApplicationUser, Contact	Employee linkage
UserSetting	User & Security	No	ApplicationUser	User preferences
UserGroup	User & Security	No	AspNetUserGroup, UserGroupRole	User groups
UserGroupRole	User & Security	No	UserGroup, Role	Group-role assignments
Role	User & Security	No	UserGroupRole	Role definitions
TrackingEvent	Core Business	No	Order, EventDefinition	Tracking events
Tag	App & System	No	OrderTag, CommodityTag, InventoryItemTag	Tag definitions
ContactAddress	Core Business	No	Contact	Contact addresses
ContactLink	Core Business	No	Contact (2 sides)	Contact relationships
ContactPaymentMethod	Core Business	No	Contact	Payment methods
ContactStatus	Core Business	No	Contact	Contact status definitions
SequenceNumber	App & System	No	Various entities	Sequence number generation
Clause	App & System	No	Various entities	Contract clauses
Tenant	Core Business	No	Organization	Multi-tenancy root

Best Practices

Entity Selection

Use Order for individual shipments and quotes
Use Job to group multiple related orders
Use Contact polymorphically for all party types
Use Commodity with container hierarchy for nested items

Custom Values

Store non-critical, variable properties in customValues
Use CustomField for system-wide custom field definitions
Avoid custom values for properties requiring indexes or complex queries

Relationships

Always load related entities explicitly using include in queries
Respect aggregate boundaries - modify children through aggregate roots
Use junction tables for many-to-many relationships

Performance

Load only required relationships using selective include
Use pagination for large entity collections
Consider caching for reference data (countries, ports, statuses)

Multi-Tenancy

OrganizationId automatically filters queries to current tenant
Use Division for sub-organizational data partitioning
Tenant isolation is enforced at the database level

Order Entity - Core shipment and order management
Job Entity - Job aggregation patterns
Commodity Entity - Commodity and container management
Contact Entity - Customer, vendor, and partner management
AccountingTransaction Entity - Financial transactions
Workflow System - YAML-based workflow automation
App Modules - Low-code application development

Entity Documentation

Each entity has detailed documentation with properties, relationships, YAML examples, and best practices. Navigate using the sidebar or the entity catalog table above.

Introduction​

Core Concepts​

What is an Entity?​

Entity Architecture​

Architecture Patterns​

1. Aggregate Roots​

2. Hierarchical Entities​

3. Polymorphic Entities​

4. Junction Tables​

5. Tag System​

6. Custom Values & Extensions​

7. Audit Trail​

8. Multi-Tenancy​

9. Domain Events​

10. Draft Mode​

Entity Categories​

1. Core Business Entities (25+ entities)​

2. Financial & Accounting Entities (11 entities)​

3. Operational & Logistics Entities (13+ entities)​

4. Document Management Entities (1 entity)​

5. Job & Workflow Entities (9 entities)​

6. Geographic & Transportation Entities (12 entities)​

7. Pricing & Rates Entities (4 entities)​

8. Warehouse & Inventory Entities (4 entities)​

9. App & System Entities (20+ entities)​

10. Calendar & Events Entities (7 entities)​

11. User & Security Entities (10 entities)​

Entity Relationships​

Aggregate Patterns​

Relationship Types​

Working with Entities​

Creating Entities in YAML​

Querying Entities with Relationships​

Updating Entities​

Using Custom Values​

Working with Tags​

Handling Domain Events​

Multi-Tenancy Usage​

Complete Entity Catalog​

Best Practices​

Entity Selection​

Custom Values​

Relationships​

Performance​

Multi-Tenancy​

Related Topics​