00 — Overview

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

What the Voyage Accounts & Agency Settlement Manager is

Settle with the carrier's port agent on actual cash — agency appointments, who collects each customer charge, the receipts and payments the agent actually made, commission, remittances, and the settlement statement that is issued and never edited.

The rules the model is built around

• Invoiced is not collected. A customer charge from coast_05_rating is a source obligation, never cash. Only an approved, evidenced AgentCollection counts as a collection.
• The settlement balance (positive = the agent owes the carrier): closing = opening + confirmed collections − confirmed payments − approved earned commission − confirmed remittances to carrier + confirmed advances from carrier + approved signed adjustments.
• Carrier-direct is excluded. A charge the carrier collects directly (for example prepaid freight) and a cost the carrier pays directly (for example berthage) are recorded as EXCLUDED sources and never touch the agent balance.
• Exact signed reversal. A collection, payment, commission or remittance is corrected by a second row with the negated stored amounts and reverses_ref; the original stays. Nothing is overwritten.
• Statements are immutable after issue. A late credit or cost produces a new revision linked to the previous one.
• One currency per account. A foreign-currency amount enters only with an approved AccountExchangeConversion that states the settlement-currency amount; there are no automatic rates.
• Independent approval. The person who prepares or submits is never the person who approves.
• Cross-application links are strings. voyage_ref, port_call_ref, manifest_line_ref, billing_document_ref, customer_ref are references to records other applications own; every record has a hidden canonical_ref.

The 17 models by area

Model names are unique across the whole fleet (hence the prefixes), 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 same voyage, customers, manifest lines and invoices as the Stage 1 applications). The Port Moresby agent's account VA-26-0001 holds the discharge-port charges of INV-26-0001 and its credit note, and the agent-paid wharfage, handling and cartage. Cash: receipt PGK 1 000.00, payments PGK 240.00, commission PGK 50.00 (5 % of collections), remittance PGK 600.00 to the carrier: closing PGK 110.00 due to the carrier (statement ST-26-0001 rev 1, issued). Carrier-direct berthage PGK 275.00 is excluded. The account was settled with an authorised carry-forward and then reopened for a late bank charge (PGK −12.50): revision 2 is a draft, revision 1 is untouched. PGK 106.25 was received against a line that credit note CN-26-0001 later cancelled: the credit note does not refund it (open dispute). The Madang account VA-26-0002 shows charge responsibility: prepaid freight is carrier-direct (excluded), and one handling charge waits for its collection assignment (exception AX-0001).

How to read it

• Start from the first menu group; it holds the records people work in.
• Money is Decimal (amounts to 2 places, rates and exchange rates to 6) — see docs/coastal_shipping/BACKLOG.md for the Decimal trial.