Port Billing System

01Business problem

Port billing combines many operational inputs: the type of cargo, arrival and delivery dates, weight, free time, where the goods were stored, and the rules that turn all of that into charges. The port’s own billing system creates permanent entries, so customs & freight-forwarding (C&F) agents had no way to estimate charges before committing to them.

That led to billing disputes, longer cargo dwell time (how long goods wait in port) and repeat trips to the counter just to check a number. The tool is built around these practical workflows, not around a generic invoicing template.

• Wharf rent: port facility usage charges
• C&F agent: customs & freight-forwarding stakeholder
• CLD: common landing date, when the storage clock starts

02Existing workflow

How a bill is built up. Estimating meant working through steps 03–05 by hand before the official record in step 06 existed.

1. Operational dataLanding date, delivery date, weight and storage area.
2. Cargo / vehicle detailsCar, general cargo or re-export.
3. Applicable chargesWharf rent plus river dues, landing, removal, weighment and hoisting.
4. Business rulesFree time, slab rates, inside / outside storage, rate change date.
5. CalculationVAT and levy applied on top of the charges.
6. Billing recordThe official bill in the port’s own system.
7. ReportingBills checked against the printed bill.

03Business rules

The rules run in a fixed order, and the same inputs always give the same bill. The car module is shown; general cargo and re-export use their own tariff tables and steps. Rates are configurable, so none are quoted here.

1. Billing moduleCar, general cargo or re-export. Each has its own rate table.
2. Dates and weightLanding date (CLD) and delivery date; weight in tons, always rounded up.
3. Free timeThe storage clock starts at the CLD; the free days are configurable.
4. Wharf-rent daysThe days from the end of free time to delivery.
5. Tariff slabs1st 7 days, 8th to 14th day, 15th day onwards: rate × days × weight. A rate-change date splits the bill into old-rate and new-rate days.
6. Payable chargesRiver dues, landing, removal, weighment and hoisting are added to the base before VAT.
7. VATApplied to the base (wharf rent plus payable charges), rounded by the port’s convention.
8. LevyAdded after VAT, only when the levy option is ticked.
9. Final estimateInside and outside storage are totalled separately, then printed as an A4 bill.

04My approach

I started from how the billing desk and agents actually work: which inputs matter, which rules apply in which order, and what a valid bill looks like. Each slab, VAT and levy combination was written down as a rule first, then encoded and checked against real bills. The interface came last. Every step is a plain function with no hidden state, so the same inputs always produce the same bill; that is also what makes the rules testable.

1. Real operational workflowHow the desk and agents work today.
2. Business rulesFree time, slabs, VAT, levy, split rates.
3. Structured dataDates, weights, storage areas, charges.
4. Calculation logicRules encoded as tested functions.
5. Web interfaceThree billing modules with a live preview.
6. ReportsPrint-ready A4 invoice and saved bills.

05System design

Sized to the problem: the calculation runs entirely in the browser, so estimates work offline. Saved bills sync through a small Cloudflare Worker, with admin-only changes locked behind a secret.

1. UserBilling desk or agent, on any device.
2. Web interfaceCar, general cargo and re-export billing modules.
3. Business rules and calculationRuns in the browser, so it works offline.
4. Saved billsKept on the device and synced to GitHub through a Cloudflare Worker.
5. OutputPrint-ready A4 invoice.

06Key features

• Three billing modulesCar, general cargo and re-export bills.
• Slab-based wharf rentWith configurable free time.
• VAT and levyCalculated per the port’s rules.
• Inside / outside storageTwo independent totals per bill.
• Split billingApplies old and new rates across a rate change.
• Payable chargesRiver dues, landing, removal, weighment, hoisting.
• Saved billsWith live search by bill number, dates, agent or amount.
• DashboardRead-only overview of saved-bill activity.
• Date validationPrinting is blocked while dates conflict.
• Print-ready invoiceA4 layout, because agents still work from paper.
• Draft autosaveRestores work after a reload.
• Offline PWAInstallable, works after the first load.

07Technology

Frontend

HTML, CSS and JavaScript with no runtime dependencies; installable PWA.

Backend

Cloudflare Worker for saved-bill sync and admin-gated writes.

Data

Browser storage; GitHub repository through the Worker.

Deployment

Cloudflare Pages; source on GitHub.

Quality

Automated tests for rounding, slabs, tonnage, VAT and amount-in-words; ESLint, Stylelint and GitHub Actions CI.

Development

Git, GitHub, AI-assisted development.

08Validation

• Automated testsFive suites cover VAT rounding, tonnage rounding, slab progression (including the rate-change split), money rounding and the amount in words. They run together in CI on every change.
• Checked against real billsSlab, VAT and levy combinations were compared with real bills before the tool was relied on.
• No accuracy figureNo percentage is claimed. The claim is narrower: the rules are written down, tested and checked.

09My role

1. Operations Specialist
2. Business Analyst
3. System Designer
4. AI-Assisted Developer
5. Tester
6. Deployer

• IdentifiedThe gap: agents could not estimate charges before committing to them.
• StudiedHow the billing desk and agents actually work.
• DefinedThe rules: free time, slabs, VAT, levy and the rate-change date.
• DesignedThe workflow, the calculation structure and the A4 layout.
• BuiltThe web app, with AI-assisted implementation under my direction.
• TestedAutomated tests over rounding, slabs and VAT, plus real bills.
• DeployedAs an installable web app on Cloudflare.
• IteratedRefined from how it is used at the billing counter.

Built with AI-assisted implementation under my direction. I own the requirements, business rules, validation, testing and deployment; I did not hand-write every line, and AI did not decide what the system should do.

10Outcome

• In daily useUsed at the billing counter to check charges before final submission.
• Rules made reusableTurned a manual, rule-heavy calculation into a reusable web-based system.
• Designed for fewer disputesCharges can be verified before committing, designed to reduce disputes and repeat counter visits.
• A foundation to build onSaved bills, search and a dashboard give operational data a structure for further automation.