Modularity without premature microservices
A load's identity, stop sequence, assigned carrier and attached documents need to agree. Splitting those concerns into independent services before their boundaries are understood introduces distributed failure modes without necessarily helping dispatchers. The initial architectural direction is a modular monolith with clear internal interfaces and one coherent transactional model.
Modules should own their rules rather than merely collect screens. Dispatch would operate on eligible loads and assignments; document workflows would link evidence to transportation entities; integration adapters would translate outside contracts without reaching directly into unrelated records. Separating those responsibilities leaves room to extract services later if a measured operational need justifies it.
The load is a shared operational reference
ConceptualOrganization and User / Role establish the proposed access boundary. Customer expresses the commercial relationship; Carrier, Driver and Equipment describe execution partners and resources. Load connects that context to an ordered set of Stops, ShipmentEvents and Documents. Quote, Rate and Invoice belong to later commercial workflows, not a claim that billing is implemented.
A shipment and a truck movement are not always the same thing. The initial point-to-point model should keep references understandable while preserving room for later consolidation, multi-stop and LTL requirements. Entity names here are a conceptual vocabulary, not finalized database tables, foreign keys or an API specification.
Commercial context
Transportation core
Execution partners
Stable references connect the domains. State changes retain actor, source and occurrence time.
{
"reference": "ILLUSTRATION-LOAD-A",
"organizationRef": "EXAMPLE-OPERATOR",
"customerRef": "EXAMPLE-DISTRIBUTOR",
"status": "carrier_assigned",
"stops": [
{ "sequence": 1, "kind": "pickup", "facilityRef": "ORIGIN-DOCK" },
{ "sequence": 2, "kind": "delivery", "facilityRef": "RECEIVING-DOCK" }
],
"documents": [{ "kind": "bill_of_lading", "state": "expected" }]
}State transitions with evidence
A mutable status is useful for an assignment queue, but it cannot explain what happened. The proposed event model retains occurrence time, recording time, event source, related stop and an actor or integration identity. Expected milestones should remain distinct from observed facts: an appointment is not an arrival, and an estimated delivery is not a completed receipt.
This is an auditable event timeline direction, not a commitment to full event-sourced persistence. Relational current state and an append-oriented history can coexist. Corrections should reference the earlier observation and explain the change rather than silently erase a disputed arrival. Transition validation, late events and concurrent edits require explicit design work.
{
"eventRef": "ILLUSTRATION-EVENT-A",
"loadRef": "ILLUSTRATION-LOAD-A",
"type": "stop.arrived",
"stopSequence": 1,
"occurredAt": "2026-01-15T09:00:00Z",
"recordedAt": "2026-01-15T09:04:00Z",
"source": { "kind": "operator", "reference": "EXAMPLE-DISPATCHER" },
"externalReference": null,
"note": "Illustrative observation, not a real shipment"
}API-first means contract-first
PlannedREST-oriented APIs are a proposed interface for transportation resources. The valuable part is not an endpoint list; it is clear semantics for identifiers, authorization, pagination, validation, concurrency and error recovery. A UI action and an external integration should eventually respect the same domain rules.
Webhooks and event subscriptions are planned. They would need versioned payloads, delivery identifiers, explicit retry behavior and consumer-side deduplication. No endpoints, authentication scheme or production API contract are published here. The documentation discusses extension contracts so engineering teams can critique the approach before adapters are promised.
Relational ownership and extension boundaries
PostgreSQL is the proposed relational foundation for core records. Transactions, referential integrity and queryable operational history fit the initial problem better than a collection of unrelated document stores. Object storage for attachments is a design consideration, with metadata and access boundaries remaining part of the domain.
Custom fields should be scoped, typed and validated rather than become an escape hatch that bypasses core relationships. A tenant or organization boundary must apply consistently to loads, documents, events, exports and integration mappings. The choice of tenancy model, migrations, indexing and backup tooling remains unverified until implementation is available.
- Preserve external references separately from internal identifiers.
- Keep module-owned mutations behind explicit interfaces.
- Treat organization scope as an access requirement, not a UI filter.
- Document data export and restore expectations before production use.
Self-hostable by design, secure by deliberate work
PlannedSelf-hosting is the intended deployment model, not something operators can install today. A credible release will need tested configuration, reproducible migrations, upgrade guidance, attachment backups and restore exercises. A container diagram alone is not a deployment guarantee.
Authentication, permission enforcement, secret management, transport security, audit logging and least-privilege integrations are design requirements still to be implemented or verified. Future enterprise security and hosted operation should build on those fundamentals. This website does not certify security, compliance or production readiness.
