00 — Overview

Demonstration prototype. coast_15_finance is a reference application and part of the Coastal Shipping series (catalogue SHP-15, Stage 3). It holds no real chart of accounts, tax rule or ledger connection — every account is a MOCK_ account, the ledger is a simulated adapter and every acknowledgment is a pretend answer. It illustrates the data model and the rules only.

What the Finance & Accounting Interface is

Is each issued invoice, approved supplier cost and committed agency fact posted once, in balance, and acknowledged by the ledger? — it is the adapter and reconciliation register between the shipping applications and an external ledger. It is not a general ledger, an invoice generator or a payment engine.

The chain the model is built around

issued fact → source (immutable, unique key) → batch (period, currency) → document (one balanced journal) → export attempt (simulated) → acknowledgment (per document) → reconciliation

• Only facts are sources. An issued billing document arrives as its complete posting snapshot (the header event is an observation only); an approved port or cartage supplier cost needs its supplier invoice line key (an estimate is never a source); an agency fact is cash, commission or remittance — never a statement, never a cost. A manifest rating or a port estimate is never posted as an actual transaction.
• One source, one key. producer|source type|source id; the same key with the same hash changes nothing, with another hash it is a conflict and nothing is applied. A credit note or cost reversal is a new signed source linked to the original — the cost reversal is its exact negation.
• Agent-paid is not carrier-payable. An agent-paid cost maps agent clearing; a carrier-payable cost maps supplier payable. The agent's cash facts move cash against the same clearing account but never touch a cost expense account, so an approved cost is never duplicated by agency cash (and a mapping that tries is refused).
• Mappings are approved configuration. Effective-dated, one per scope, two different accounts, dimensions from the source; no account is invented and a missing mapping blocks the batch. A positive signed amount posts debit account Dr / credit account Cr, a negative one the opposite sides — so a credit note needs no special case.
• One currency, balanced, exact. One currency per document and no implicit FX; debits equal credits; a reversal is the original's stored lines with debit and credit swapped. The arithmetic equals the pack's reference calculator (cross-check test).
• Approval is independent; the payload is frozen. The person who prepared a batch cannot approve it; approval hashes every document and the batch, and export refuses a payload that changed.
• Accepted is not posted. SIMULATED_ACCEPTED means the pretend transport took the batch. A document is POSTED only when the ledger's acknowledgment names its document key, and its source hash, currency and amount match; otherwise it is MISMATCHED or REJECTED. A partial batch stays exported; an unanswered document becomes UNCERTAIN and is never resent until the ledger was queried.
• Corrections link, they never edit. A posted document is corrected by an exact reversal and a replacement (new documents pointing at the original).
• External payments reconcile. A payment notice from the ledger is routed to coast_05_rating or coast_07_accounts for matching; a fact that originated in the ledger is RECONCILE_ONLY. Neither is ever exported as new cash.
• Cross-application links are strings. source_ref, voyage_ref, port_call_ref, appointment_ref, customer_ref; no foreign key leaves the application.

The 14 models by area

Model names are unique across the whole fleet (hence the Fin prefix). 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, profile PGK-MAIN (legal entity LE-DEMO-CARRIER, connector mock_ledger). PB-26-0001 posts the two issued invoices (INV-26-0001 1 897.50, INV-26-0002 627.66) and is reconciled. PB-26-0002 posts the credit note CN-26-0001 (−948.75) and the Port Moresby port costs: the simulated ledger rejects the agent-paid wharfage (PC-26-0002) and acknowledges the handling cost (PC-26-0003) at 100.00 against 110.00 — a mismatch — so the batch is in exception with two open reconciliation items. PB-26-0003 is approved but not exported (the Lae cartage cost CC-26-0002 and its exact reversal CC-26-0003, the commission and the remittance). PB-26-0004 is a draft that will pick up the agent's three supplier payments; PB-26-0005 is a draft that already holds the replacement of the rejected wharfage document (a linked correction, never an edit). The collection AF-26-0001 originated in the external ledger: it reconciles with payment notice PN-26-0001 and is never exported. The agency statement ST-26-0001 and the INV-26-0001 header are observations that never post; CC-26-0099 repeats a supplier invoice line and is quarantined; PN-26-0002 names nothing and is held unmatched.

How to read it

• Start from Financial Sources, then Postings & Batches; Ledger Exchange shows what the simulated ledger answered; Accounting Configuration holds the profile, the mappings and the periods.
• Amounts are Decimal(18,2); every journal line is a debit or a credit, never both.