Application Overview

PortCalls — Coastal Voyage, Cargo & Port-Call Management. 38 models covering the operational execution of an Australian coastal shipping service, from the commercial commitment through to the reconciled, evidenced voyage.

The core operating chain

The whole app hangs off one spine. Read it top to bottom:

ServiceContract  →  Voyage  (over a Route, with a Vessel and Master)
   Voyage  →  VoyageLeg / VoyageParty            the plan and who is on it
   Voyage  →  CargoBooking  →  CargoConsignment  →  CargoTransportUnit
                 CargoConsignment → DangerousGoodsDeclaration
                 CargoBooking     → CargoDocument / CargoReadiness
   Voyage  →  StowagePlan  →  StowagePosition
                 Voyage → CargoSecuringInspection
   Voyage  →  PortCall  (at a Port / Terminal / Berth)
                 PortCall → PortCallDeclaration / PortServiceRequest
                 PortCall → BerthWindow / PortCallMilestone
                 PortCall → LoadingOperation → LoadingTally
                 PortCall → StatementOfFacts
   Voyage  →  VoyageReadiness / VoyagePosition
   Voyage  →  OperationalEvent  →  Delay
   Voyage  →  VoyagePerformance                   reconciliation and review

The point of the model is traceability across streams: a departed voyage is traceable through cargo readiness, berth readiness, vessel readiness and voyage authority, and a failure in any one stream changes the voyage-readiness result, names the responsible party, records evidence and moves the forecast departure and arrival.

The nine areas (they mirror the sidebar)

  1. Commercial — the ServiceContract (charter type, scope, performance and demurrage terms), the Voyage that executes it, and the VoyageParty records that attach owner, operator, charterer, shipper, consignee, agent, terminal and stevedore to it.
  2. Fleet & Routes — Vessel and its statutory VesselCertificates, Ports with their authorities, Terminals and Berths (with LOA, draft and crane limits), and the Routes joining ports with nominal distance and transit.
  3. Cargo — the Commodity catalogue, the CargoBooking against a voyage, the CargoConsignments and their CargoTransportUnits, the DangerousGoodsDeclaration, the CargoDocuments, and the CargoReadiness assessment that gates loading.
  4. Stowage & Handling — the versioned StowagePlan with its stability and segregation checks, the StowagePositions within it, the CargoSecuringInspections, and the CargoHandlingEquipment with safe working loads and inspection dates.
  5. Port Calls — the PortCall with ETA/ATA/ETD/ATD and berth, its PortCallDeclarations, the requested PortServiceRequests, the BerthWindow allocations and the PortCallMilestone timeline.
  6. Cargo Operations — the LoadingOperation, the LoadingTally records that build up the actual figure unit by unit, and the StatementOfFacts.
  7. Voyage Execution — the VoyageLeg actuals, the VoyageReadiness gate, the VoyagePosition reports, the OperationalEvents and the Delays they cause.
  8. Performance & Records — the VoyagePerformance reconciliation, the Evidence register and the operational Notifications.
  9. Administration — the Organisations and the Persons who act for them.

Key concepts and boundaries the app models

  • Readiness is a gate, not a status flag. CargoReadiness and VoyageReadiness are point-in-time assessments with a boolean per stream and an overall result (READY / READY_WITH_CONDITIONS / NOT_READY). A voyage reaches READY only when every readiness flag is true. Assessments accumulate — a NOT_READY and a later READY both stay on the record.
  • Verified gross mass (VGM) rides on the transport unit. A container CargoTransportUnit carries its verified_gross_mass, method, verifier and timestamp — the check that lets it be loaded.
  • The stowage plan is versioned, not overwritten. When cargo changes, the plan is superseded (SUPERSEDED) and a new version approved (IN_USE); the positions and securing inspections point at the version in force.
  • Delay attaches to an event and names a party. A Delay links to the OperationalEvent that caused it, records its category, the responsible_party_organisation, whether it is excusable and whether demurrage_applicable — the commercial hook.
  • Performance is derived and reconciled. VoyagePerformance holds planned vs actual distance and transit, port and delay hours, capacity utilisation, cargo tonne-nm and schedule variance. In this prototype those derived figures are computed in the seed, not by a live rules engine.

What is Phase 2 (documented, not enforced)

The proforma pack shipped state machines (workflows.yaml), assertions and derivations (business_rules.yaml), dashboard/report definitions and integration adapters. These are process documentation recorded in the DSL header and in app_config.yaml business_rules: {}. The demo data is consistent with them rather than validated against them — nothing in the running app enforces the VGM, DG-segregation, berth-fit, readiness-gate or derived-quantity rules yet.

What this app is not

It is the operational layer. It references, rather than duplicates, the coastal-trading licence and voyage-notification system, the vessel safety-management and crewing systems, navigation/ECDIS, the terminal operating systems, financial/charter-party accounting and demurrage settlement, and customs/international cargo reporting. The *_reference / *_uri columns and the Evidence model carry the handles to those source systems. It is a prototype data and workflow model, not legal advice — requirements must be verified for each vessel, cargo, port, terminal, route and operating arrangement.