Port congestion watchlist for chartering and voyage desks

I want an app for our chartering and voyage planning desk that answers one question fast: which of the ports we route through is actually congested right now. Today a planner has to open MarineTraffic port by port in five browser tabs, and there is no side by side view when we are comparing candidate discharge ports. Build me a watchlist board instead.

The main screen is a watchlist of the ports we route through, stored in the app's own database so it persists between visits. Each row is one port and shows the latest weekly figures from the MarineTraffic Port Congestion service: average waiting time at anchorage, average time in port, and vessel counts. Beside those numbers show the previous several weeks as a compact trend (a sparkline or small bar row, plus a change indicator against the prior week) so a planner can see at a glance whether the port is getting worse or easing. Each row also carries a live count of inbound traffic from Expected Port Arrivals. Let me sort the board by waiting time and by week over week change so the worst ports float to the top.

Put a vessel class filter at the top of the watchlist. Port congestion is aggregated by market or ship class, so a dry bulk planner should be able to switch the whole board to dry bulk and stop looking at container numbers. The filter should apply to the congestion figures and to the arrival queue counts, and it should be remembered between visits.

A planner can add a port to the watchlist by MarineTraffic port id or by UN/LOCODE, and remove one at any time. Store each port in the app database with the port id, the locode, a display name and the date added. When someone adds a port, fetch its current congestion figures straight away so the row lands populated rather than blank.

Clicking a port opens a detail view for that port. Show the congestion history as a week by week chart going back as far as the data allows; the arrival queue from Expected Port Arrivals broken down by vessel type and size band so a planner can see what kind of tonnage is stacking up; recently completed calls from Port Calls with arrival and departure times; and berth level turnaround from Berth Calls, showing how long ships actually spent alongside at each berth or terminal. If a forward looking queue is useful, Predictive Port Arrivals can supplement the expected arrivals list, but expected arrivals is the primary source. This page also lists the memos written by the assessment agent, newest first, with the date each was written.

On the port detail view add an "Assess this port" button that kicks off a background agent. The agent reads the congestion trend for that port, the current arrival queue and the recent berth turnaround times, then writes a short practical memo: how much waiting time to expect, what a realistic berthing window looks like, and whether the situation is deteriorating or clearing. It saves the memo against the port in the app database so it appears on the detail page and as a "last assessed" note on the watchlist row, and it posts the same memo to a Slack channel using Slack Bot Send a Message so the wider ops team is working off the same call. Let the planner pick the Slack channel, and include the port name, the headline numbers and the recommendation in the message. Show the run status in the app while the agent is working.

MarineTraffic notes for the build: ports are addressed by MarineTraffic port id (the number in the port page URL) or by UN/LOCODE, so accept either on the add form. Congestion is calculated per port per ISO week, so the trend axis is weeks and not days, and the points should be labelled with the ISO week. Each MarineTraffic API service is a separately purchased product with its own 40 character key, so declare a separate credential slot for each service the app uses (Port Congestion, Expected Port Arrivals, Port Calls, Berth Calls) rather than assuming one key covers everything, and show a clear message on the affected panel if the key for one service is missing instead of failing the whole page. Speed values come back in knots times ten, so divide before displaying. All timestamps are UTC.

Nothing here runs on a schedule. The watchlist is a surface a planner opens, and the agent only runs when someone presses the button. Cache the congestion responses in the app database so reopening the board does not burn API credits, and give me a refresh control to force a re-fetch for a port.