00 — Overview

Demonstration prototype. coast_08_portcosts is a reference application and part of the Coastal Shipping series (catalogue SHP-08, Stage 2). It holds no real port tariff, supplier invoice or cost data — everything in the demo is fictional and illustrates the data model and the rules only. The service catalogue and the rates are placeholders, not official tariffs.

What the Port Costs & Disbursement Manager is

What did the port services for this call cost, who pays, and what was the money for? — the port supplier rates, the service orders and the evidence that each service was performed, the supplier invoices, the approved costs and their internal allocation to cargo.

The chain the model is built around

requirement → service order → evidence (verified quantity) → estimate (approved rate) → supplier invoice → approved cost (one per invoice line) → allocation

• An estimate is not payable. It uses the approved rate for the service, port and date (an exact provider beats a general rate; a tie is an error), rounds the quantity up to the rate's increment, applies the minimum and rounds to the cent: 2.25 hours at 100.00 with a 0.5 hour increment is 2.5 hours, 250.00 + 25.00 tax = 275.00.
• Actual cost is the invoice, checked against the verified service. A line that differs from its estimate needs a variance reason and the authority of a supervisor, or the invoice is disputed.
• One immutable cost per supplier invoice line. The line key (provider, normalised invoice number, currency, line) is unique, so the same supplier line can never become a second payable; a correction is a linked signed reversal from a credit note, the exact negation of the original.
• One responsible payer per cost. AGENT costs go to the agent's account in coast_07_accounts with their appointment and port call; CARRIER costs are paid direct and never reach an agent.
• Allocation is internal attribution. Net and tax are allocated separately, to the cent, by the largest remainder, and each sums exactly to the cost; it creates no payment and no customer charge. What is not allocated stays as call overhead.
• Supplier cost is not customer charge. Wharfage billed to a customer by coast_05_rating is a different fact from the supplier's wharfage here; cartage contractor costs belong to coast_09_cartage only.
• Cross-application links are strings. voyage_ref, port_call_ref, port_ref, agent_appointment_ref, manifest_line_ref are canonical strings; no foreign keys leave the application.

The 17 models by area

Model names are unique across the whole fleet (hence the Port prefix) because network tests load many applications into one process. Every model has a hidden canonical_ref (assigned by the runtime, shown in the collapsed Identifiers & integration section).

The demo scenario

Voyage V26-014 ex Lae, the Port Moresby call of 10 November. Berthage (carrier direct, 275.00), wharfage (agent-paid, 176.00) and handling (agent-paid, 110.00) are invoiced, matched to the verified activity of coast_06_voyage and approved as three costs; the wharfage is allocated 10:10 to the two cargo lines discharged at Port Moresby and the handling is prepared 10:1 by package count (90.91 / 9.09 net, 9.09 / 0.91 tax). The tug invoice PTS-0451 bills two movements for one verified: it is disputed, an exception is open, and no cost is approved. Lae berthage is performed and awaiting its invoice, a Madang towage order is approved, and a Lae port dues order is still a draft.

How to read it

• Start from the first menu group; it holds the records people work in.
• From the Network shows what coast_06_voyage and coast_07_accounts sent (versions, hashes and payloads); those rows are never edited by hand.
• Quantities and measures are Decimal (amounts to 2 places, quantities to 3, rates to 4) — see docs/coastal_shipping/BACKLOG.md.