CLIENT: Mchanga Bay Clearing & Forwarding Ltd🇹🇿Tanzania

Kivuko - Customs Documentation Workspace with Agent-Confirmed HS Classification

Customs Declaration Workspace for a Tanzanian Broker

Designed and built a clickable customs documentation workspace for a licensed broker in Dar es Salaam: every consignment on one board from first invoice to release, an HS classification workbench where a licensed agent confirms each suggested code, and a declaration builder that blocks lodgement until every check passes.

Scope of Work
Product design, UI build and clickable demo
Industry
Logistics / Customs Documentation
EnterpriseTaxAI
Compliance & Certifications
EAC Customs Management Act 2004EAC Common External TariffWCO Harmonized SystemTanzania PDPA 2022TRA EFD/VFD fiscal receipts

Most of our work is under NDA. Per agreement, we can share the work but not the company details - all names and identifying information shown here have been changed.

Impact

5 Screens
Clickable end to end

Dashboard, jobs board and table, job detail with 7 tabs, the classification workbench and the six-step declaration builder. Every job opens its own workbench, and every classified job its own declaration.

6 Checks
Before Lodge unlocks

All lines confirmed by a licensed agent, required documents checked, permits present and valid, a valuation reason where needed, client approval received and the importer's agency authority valid.

Up to 3
HS suggestions per line

Each with the heading path, the reasons, the General Interpretative Rule relied on, a confidence level and the configured duty rate, under a banner that says suggestions are not a ruling.

24 Jobs
Realistic demo data

12 importers across machinery, textiles and food, 10 staff users, 16 declarations and 17 goods lines with tariff suggestions, spread across all 9 clearance stages plus on hold.

The Problem

Mchanga Bay's declarants worked from email attachments, WhatsApp photos of invoices and a spreadsheet per client. Invoice lines were retyped into the customs system, HS codes came from memory or last year's file, and nobody could see which consignments were waiting on a TBS certificate, a client approval or a duty payment. Port storage charges piled up while documents were chased, and two misclassification penalties in one year cost the firm a key textile client.

Our Solution

Kivuko takes a consignment from the first commercial invoice to the release order. Jobs move across a board of clearance stages with days in stage and missing items on every card, invoice lines are classified with reasoned suggestions that only a licensed agent can confirm, and the declaration builder works out the CIF value and a duty and tax estimate before checking that the declaration is ready to lodge.

The Challenge: Clearing Goods Without Guesswork

Mchanga Bay files import and export declarations for about 350 importers under the EAC Customs Management Act, 2004, as applied by the Tanzania Revenue Authority. Each declaration depends on a correct tariff line, a correct customs value, the right permits and the client's say-so, and a mistake in any one shows up as a query, a penalty or storage days at the port.

Classification From Memory

Goods are classified under the WCO Harmonized System and the EAC Common External Tariff, applying the General Interpretative Rules, down to the national tariff line. Declarants chose codes from memory with no record of why, and the tariff itself is revised from time to time.

Valuation and Estimates Done by Hand

Customs value is generally the transaction value plus freight and insurance to the port of entry, converted at the customs exchange rate in force. Freight and insurance had to be shared across lines by hand, and duty and VAT were worked out in spreadsheets.

Permits Nobody Could See

Some goods need a certificate or permit from another agency before release, such as TBS for standards and food safety or TMDA for medicines. Whether a job was waiting on one was buried in an email thread.

Authority and Accountability

A licensed agent lodges under the firm's customs agent licence and acts for each importer under written authority. The firm needed to know who confirmed every code and value, that the authority was valid, and that the client had approved before anything reached TANCIS.

Our Approach: From Customs Rules to a Clickable Workspace

01

Spec and Rules Research

Mapped 10 roles, from documentation clerk and licensed agent to the importer's approver, 35 screens across the broker console and a bilingual importer portal, and the data model for jobs, documents, invoice lines, classifications, versioned tariff tables, declarations, customs events, permits, disbursements and invoices. Wrote down the rules the design follows: the EAC Customs Management Act, the CET and HS, CIF valuation, preferential origin, agent licensing, other-agency permits, the Personal Data Protection Act, 2022 and fiscal receipts.

02

Clickable Demo on a Production UI Kit

Built 5 key screens on a production dashboard kit: the dashboard with KPIs, the pipeline by stage and My work for five roles, the jobs board with stage targets and a job quick view, job detail with checklists and a stage progress rail, the classification workbench with an HS code explorer, and the declaration builder with valuation build-up and a duty calculation breakdown. Suggestions and rates are seeded demo data, and all actions run on local state.

03

What a Production Build Adds

Lodgement and status through TANCIS, with a manual mode until TRA access for licensed agents is confirmed, TeSWS permits, GePG control numbers, OCR with Google Document AI or AWS Textract, the classification model, a TRA-approved VFD provider, Selcom or DPO Pay, and Africa's Talking and WhatsApp notices. Role-based auth that lets only licensed agents confirm and lodge, an append-only audit trail, and the remaining screens: document intake and check, queries, permits, billing, reports, settings and the importer portal.

Why It Works: The Agent Decides, the Screen Shows Why

Suggestions With Their Reasons

Each candidate code shows the path from section to tariff line, the matching words or item library history behind it, the rule relied on and a confidence level. Picking anything but the top suggestion needs a reason, and Confirm is reserved for a licensed agent, whose name and licence are shown beside it.

Lodge Stays Locked Until Ready

The builder's right rail lists six checks with pass or fail and keeps Lodge disabled while any one fails. Sending for client approval and recording the approval come first, so nothing is lodged on a version the importer has not seen.

Every Figure Opens Its Working

The valuation build-up shows invoice total, freight, insurance and CIF, with estimated figures marked. Each tax opens a breakdown with base, rate, tariff table version and formula, and the footer says the customs assessment is final and the estimate is not legal or tax advice.

Delays Visible Before They Cost Money

Days in stage turn amber past the stage target and red past twice the target, cards count missing documents, permits and approvals, and the dashboard lists consignments whose free port storage ends within 3 days with the reason they are not yet released.

Logo
Oceanlab

Enterprise Software Engineering - Human + AI

Languages

Locations

Global Headquarters

21 Merchant Road, 3rd Floor, Singapore 058267

Main corporate office and leadership operations

North America Office

548 Market Street, PMB 12345, San Francisco, CA 94104

Client operations and business development

India Office

402 Shivalik Shilp II, SG Highway, Ahmedabad 380015

Engineering and delivery center

© 2026 - Copyright. All Rights reserved Oceanlab