00 — Overview

Demonstration prototype. coast_06_voyage is a reference application and part of the Coastal Shipping series (catalogue SHP-06, Stage 2). It holds no real vessel, voyage, cargo or customer data — everything in the demo is fictional and illustrates the data model only.

What the Vessel, Voyage & Port Call Manager is

The authority for voyage identity and the ordered calls of a voyage, and the record of what physically happened at each call — vessel and voyage, port calls, berth visits, services, and the loading and discharge tally against the frozen manifest.

The rules the model is built around

• A port call is not a port. A voyage may call at the same port twice; each call has its own number and identity (VoyagePortCall). The freeze in the manifest application stays by voyage and load port; this application maps each cargo line to an explicit load call and discharge call (CargoCallAllocation). A line is matched automatically only when each of its ports appears once on the voyage — never an implicit first match — otherwise it stays UNMAPPED until a person chooses.
• The manifest is the commercial plan, the tally is the fact. A manifest correction supersedes a cargo line; the loading and discharge facts already recorded are never changed or deleted. A difference is a disputed fact, a line in VARIANCE and a CARGO_TALLY_VARIANCE exception.
• Cargo facts do not move containers. Tally records are evidence; coast_03_tracking owns the container's state.
• Departure is guarded. A call departs only with a supervisor's authority, a frozen manifest snapshot for loaded cargo and a reconciled tally (or an explicit no-cargo declaration), and with no berth visit open. Operational completion of a voyage is separate from financial settlement.
• Agents are approved appointments. A call is confirmed only against an APPROVED agent appointment for its port that is valid at its ETA (the agency application, coast_07_accounts, publishes it; this application keeps a projection).
• Versioned snapshots. Every change that matters to others bumps the voyage's or call's version and snapshot_hash and publishes voyage.snapshot / voyage.portcall_snapshot; the receivers reject stale versions.
• No price here. Rates, charges and agent cash belong to coast_05_rating and coast_07_accounts; a verified service fact (voyage.activity_verified) is not a payable.
• Cross-application links are strings. manifest_canonical_ref, manifest_line_canonical_ref, agent_appointment_ref are canonical strings with their *_cid partners; every record has a hidden canonical_ref.

The 15 models by area

Model names are unique across the whole fleet (hence the prefixes), because network tests load many applications into one process. The pack's S715_ExternalSnapshot became two typed projections, ManifestCargoSnapshot and AgentAppointmentRef; its outbox and inbox are the integration runtime's.

Messages

The demo scenario

Voyage V26-014 ex Lae on Coastal Trader I (the same story as the Stage 1 applications): calls Lae (reconciled), Port Moresby (reconciled; berthage 2.25 hours and wharfage and handling for 20 RT verified) and Madang (arrived 12 Nov, berth visit open). The frozen manifest MF-26-014-LAE has two revisions — revision 2 replaced line 3 with an excavator, so its first allocation is superseded and the replacement is mapped, and the physical load fact stays. At Madang 13 of 14 packages were counted: a disputed fact, line CCA-26-0002 in VARIANCE and an open CARGO_TALLY_VARIANCE exception VX-0001. Voyage V26-015 is confirmed with Lae confirmed and Port Moresby planned.

How to read it

• Start from the first menu group; it holds the records people work in.
• Reference copies (ports, vessels) are this application's own records; vessels and voyages are the network's authority.
• Quantities and measures are Decimal (amounts to 2 places, measures to 3) — see docs/coastal_shipping/BACKLOG.md for the Decimal trial.