Laytime and demurrage claim workspace for chartering ops

Build me an app my chartering operations team opens to work laytime and demurrage claims, instead of running them out of a spreadsheet. It is a working surface for the claims desk: the exposure ranking, the statement of facts, the claim status, and an agent that drafts the actual claim.

The main screen is a voyage board showing every voyage we have on the books. The fixture list comes from a Google Sheets tab read with Get Values, one row per voyage carrying the vessel IMO, vessel name, load port, discharge port, laytime allowed in hours, demurrage rate per day, the charterparty terms or notes for that fixture, the counterparty name and the counterparty email. Treat the sheet as read only. The app never writes back to it.

Each fixture row is joined to what actually happened using MarineTraffic, addressed by the IMO on the row. Use Single Vessel Port Calls for arrival and departure timestamps and Single Vessel Berth Calls for the docking and undocking timestamps. Every board row should show the vessel, the load and discharge ports, arrival, berthed, sailed, actual time in port, the laytime allowed from the fixture, hours over or under that allowance, and the money at risk, calculated as hours over divided by 24 and multiplied by the demurrage rate per day. Sort the board by money at risk, biggest exposure first, and make rows that have run over their laytime visually obvious. Each row also carries its current claim status.

Clicking a voyage opens a detail page built around a statement of facts timeline: every arrival, departure, docking and undocking event for that vessel in that port window, in order, each one labelled with what it is and where it came from. The header carries the ship's details pulled from MarineTraffic Vessel Particulars, so name, IMO, MMSI, vessel type, flag, deadweight, year built and dimensions. Below the timeline, show the fixture terms from the sheet and the laytime calculation broken out step by step, so someone can see how the app got from the timestamps to the hours over and to the money figure.

All timestamps are UTC and must be labelled as UTC everywhere they appear, on the board and in the timeline. The app also has to make clear which times came from AIS-derived vessel tracking, meaning the MarineTraffic port call and berth call records, and which came from an agent's report or a human entry. Tag every event with its source, show a short legend explaining the difference, and never let the two sit unmarked in the same column. That provenance is what the claim rests on, so it is a first-class part of the interface rather than a footnote.

Claim status lives in the app's own database, one record per voyage keyed to the fixture row and the vessel IMO. The status is one of draft, sent, disputed or settled, and it is editable inline straight from the board and from the voyage detail page, with the change saved immediately and the time of the change recorded. The database also holds the claim narratives the agent writes, so the sheet stays a plain fixture list and everything the desk produces stays in the app.

Put a "Build claim pack" button on each voyage that kicks off a background agent. The agent re-pulls the port call and berth call timestamps for that vessel over the fixture window with Single Vessel Port Calls and Single Vessel Berth Calls, lays them against the charterparty terms on that fixture row, works out how the laytime allowance was consumed and what demurrage is owed, and writes a claim narrative in plain prose: when the vessel arrived, when it berthed, how the allowed hours were used up, when it sailed, and exactly how the demurrage figure was reached. It saves the narrative, the timestamp table it used and the computed figures onto the voyage record in the app database so the app can display them, and then it creates a Gmail draft to the counterparty using Create a Draft, containing the narrative and the timestamp table. The agent never sends anything. The draft exists so a human reviews it before anything goes out.

While the agent is working, show its status on the voyage so the desk knows a pack is being built. When it finishes, show the narrative on the voyage page along with a note that a Gmail draft is waiting. Keep previous claim packs in a history list on the voyage rather than overwriting, so the team can see what was drafted before and when.

One setup detail that matters: each MarineTraffic API service carries its own separate 40 character key, so this app needs distinct MarineTraffic credentials for Port Calls, Berth Calls and Vessel Particulars rather than a single shared key. Also, berth call history is only available from July 2017 and port call history from January 2015. If a fixture window predates that, say so plainly on the row instead of rendering an empty cell that looks like the vessel never called.

Handle the thin cases honestly rather than guessing. If a vessel has no matching port call in the fixture window, if a port reports no berth-level calls, or if a fixture row is missing a laytime allowance or a demurrage rate, show that on the row and skip the calculation rather than computing a number the desk might quote in a claim.