Freight Forwarder Job Costing — from Excel margins to a per-shipment ledger

Overview

A web app for freight forwarders and customs brokers that replaces the Excel sheet they currently use to work out whether a shipment actually made money. For every job, it captures what was billed and every cost against it — ocean/air freight, duty, handling, trucking, documentation fees — and shows the margin immediately, per shipment, per client, and per trade lane. It also holds the shipment's documents (Bill of Lading, Certificate of Origin, permits) in one place, with alerts before anything expires.

Problem being solved

A forwarder's margin on any one job depends on a dozen cost lines that arrive at different times from different parties (the shipping line's invoice, the trucker's invoice, port handling charges, customs duty). Today these get pasted into a shared Excel workbook, usually by whoever has time, and nobody can say with confidence which clients or lanes are actually profitable until someone reconciles everything at month-end — by which point the next quote on that same lane has often already gone out underpriced.

Target customers

SME freight forwarders and customs brokers in Malaysia with roughly 5–30 staff, running a steady volume of ocean/air shipments, who do not already run an enterprise TMS (Transport Management System) because it is priced and built for much larger operations. The buyer is the owner or operations manager — usually the same person who currently maintains the Excel workbook or directly supervises whoever does.

Main product functionality

• Create a shipment job against a client, with the agreed billed amount
• Log cost line items against the job as invoices come in, from any staff member
• See live margin per job, and rolled up by client and by trade lane
• Upload and store BL, CO, and permit documents against a job, with an expiry date where relevant
• Get notified before a stored document expires

User roles

Owner / Admin

Full access — manages company settings, staff accounts, billing, and sees all jobs and margin reports

Ops staff

Creates and manages shipment jobs, logs costs, uploads documents — sees jobs they created or are assigned to by default, with an option for the Owner to grant company-wide visibility

Assumption to validate: whether ops staff should see every job by default or only their own. Forwarders with a small, trusted team may want full visibility; larger ones may want it restricted. Confirm with the first pilot customer rather than deciding this up front.

Key business rules

• A job's margin = billed amount − sum of all logged cost line items. Margin recalculates live as costs are added, not on a schedule
• A document with an expiry date triggers a reminder at a configurable lead time (default 14 days) before it lapses
• Only an Owner/Admin can delete a job or a cost line item once logged — ops staff can edit their own entries but not remove the audit trail

Core value proposition

Know which shipments, clients, and lanes are actually profitable the moment the last cost comes in — not at month-end reconciliation, when it's too late to reprice the next quote.

Minimum Sellable Product (MSP)

One pilot forwarder can replace their Excel workbook for new shipments: create a job, log costs against it from multiple staff, see the margin, and store the job's documents with expiry reminders. Nothing more.

What we're selling

A web app where a forwarder logs every shipment's costs as they come in and sees the real margin immediately — plus a place to keep the shipment's paperwork so nothing expires unnoticed.

Who should buy it

Owners or operations managers at freight forwarders / customs brokers, roughly 5–30 staff, who currently track shipment profit in a shared Excel sheet.

Problems it solves

Not knowing a shipment's real margin until weeks after it closes; costs scattered across emails and individual spreadsheets; documents expiring without warning.

How it works

Create a job for a shipment, enter what was billed. As invoices come in from the shipping line, trucker, customs agent, log each one against the job. The margin updates on its own. Upload the shipment's documents to the same job — the system reminds the team before any of them expire.

Main selling points

See profit the moment a shipment closes, not at month-end. Every staff member can log costs without emailing a spreadsheet around. One place for shipment documents with built-in expiry reminders.

What's included in release 1

Shipment jobs, multi-user cost logging, live margin, document storage with expiry reminders, owner/staff roles.

What's NOT included yet

Margin reports rolled up by client or lane (coming after the first pilots), multi-currency cost entries, a client-facing tracking portal, and direct sync with accounting software.

Customer onboarding

A short call to set up the company account and invite staff. New shipments go straight into the system from day one; old shipments are not migrated for the pilot — we start clean going forward rather than re-keying history.

Expected delivery timeline

8–10 weeks to a pilot-ready MVP from the day the first pilot forwarder commits — this assumes one developer working on this alone, with no major surprises in document-storage or file-upload handling; see §B·4 for the week-by-week breakdown and what could push this out.

Important limitations

The pilot only tracks shipments entered after go-live — it does not reconstruct historical profit. It is single-company per account; it does not yet connect to the forwarder's existing accounting software, so cost entries are typed in, not pulled automatically from invoices.

For pitching: lead with the month-end problem — "you find out a shipment lost money three weeks after you could have done anything about it." The document-expiry reminder is a secondary hook, not the opener; margin visibility is what justifies the subscription price.

A. Complete customer journey

flowchart LR
    A["Forwarder owner hears
about the product"] --> B{"Currently tracking
margin in Excel?"}
    B -- "Yes, in pain" --> C["Books a demo"]
    B -- "No real pain" --> X["Not a fit — exit"]
    C --> D["Sees live-margin demo
on a sample shipment"]
    D --> E{"Agrees to pilot?"}
    E -- "No" --> X
    E -- "Yes" --> F["Setup call:
company + staff invited"]
    F --> G["Team logs NEW shipments
going forward"]
    G --> H{"Margin visibility
actually used weekly?"}
    H -- "No" --> R["Churn risk —
founder follow-up"]
    H -- "Yes" --> I["Converts to paid
monthly subscription"]
    I --> J["Renews month over month"]

B. Customer onboarding

flowchart TD
    A["Pilot agreement signed"] --> B["Owner creates
company account"]
    B --> C["Owner invites ops staff
by email"]
    C --> D{"Staff accepts invite?"}
    D -- "No, after 3 days" --> E["Owner re-sends
or removes invite"]
    D -- "Yes" --> F["Staff sets password,
lands on empty dashboard"]
    F --> G["Owner or staff creates
first real shipment job"]
    G --> H["Team logs costs on it
as invoices arrive"]
    H --> I["First margin view
shown — activation moment"]

C. Core product operation — working a shipment

flowchart TD
    A["Create job:
client, billed amount, lane"] --> B["Job appears in
open-jobs list"]
    B --> C["Any staff member logs
a cost line item"]
    C --> D["Margin recalculates
immediately"]
    D --> E{"More invoices
still expected?"}
    E -- "Yes" --> C
    E -- "No" --> F["Owner marks
job closed"]
    A --> G["Upload BL / CO / permit
to the job"]
    G --> H{"Document has
an expiry date?"}
    H -- "Yes" --> I["Reminder scheduled
14 days before expiry"]
    H -- "No" --> J["Stored, no reminder"]
    I --> K{"Renewed before
expiry?"}
    K -- "No" --> L["Overdue flag shown
on job"]
    K -- "Yes" --> J

D. User roles and permissions

flowchart TD
    Owner["Owner / Admin"] -->|"full access"| Settings["Company settings,
billing, staff accounts"]
    Owner -->|"full access"| AllJobs["All shipment jobs
and margin reports"]
    Owner -->|"only role that can"| Delete["Delete a job or
a cost line item"]
    Staff["Ops staff"] -->|"create / edit own"| OwnJobs["Jobs they created
or are assigned to"]
    Staff -.->|"optional, owner-granted"| AllJobs
    Staff -->|"cannot"| Delete

E. Subscription and payment process

flowchart TD
    A["Pilot period ends
(target: 4 weeks)"] --> B{"Owner decides
to subscribe?"}
    B -- "No" --> X["Account frozen,
data kept 30 days"]
    B -- "Yes" --> C["Setup fee invoiced
(RM2,000 one-time)"]
    C --> D["Monthly plan selected
by shipment volume"]
    D --> E["Recurring card or
FPX charge via payment gateway"]
    E --> F{"Payment succeeds
each cycle?"}
    F -- "No" --> G["Grace period 7 days,
owner notified"]
    G --> H{"Resolved in
grace period?"}
    H -- "No" --> X
    H -- "Yes" --> F
    F -- "Yes" --> I["Account stays active"]

F. Administrative workflow

flowchart TD
    A["Owner opens
Company Settings"] --> B["Invite / remove staff"]
    A --> C["View billing &
invoice history"]
    A --> D["Set expiry reminder
lead time (default 14 days)"]
    A --> E["Export all shipment
data as CSV"]
    B --> F{"Staff removed
mid-pilot?"}
    F -- "Yes" --> G["Their logged jobs
reassigned to Owner,
audit trail kept"]

A modular monolith on managed infrastructure. Nothing here needs microservices, queues, or a separate background-job platform — the only asynchronous work is scheduled expiry-reminder checks, which a cron-style scheduled function handles.

Recommended stack

This is a deliberate match to a solo developer's existing toolkit rather than a from-scratch evaluation — swap any row for an equivalent the developer already knows well; the architecture below does not depend on the specific vendor.

flowchart TD
    subgraph Client["Browser"]
        UI["Next.js UI
(dashboard, job, documents)"]
    end
    subgraph App["Next.js app (Vercel)"]
        SA["Server actions /
API routes"]
        CRON["Scheduled function:
daily expiry check"]
    end
    subgraph Data["Managed data layer"]
        DB[("Postgres
Supabase / Neon")]
        STORE[("Object storage
R2 / Supabase Storage")]
    end
    EMAIL["Email provider
(Resend)"]
    PAY["Payment gateway
(CHIP / Stripe)"]

    UI -->|"reads/writes"| SA
    SA -->|"query/mutate"| DB
    SA -->|"signed upload/download URL"| STORE
    UI -->|"direct upload via
signed URL"| STORE
    CRON -->|"query expiring docs"| DB
    CRON -->|"send reminder"| EMAIL
    SA -->|"checkout / webhook"| PAY
    PAY -->|"payment status webhook"| SA

Security

• Every query scoped to the authenticated user's company_id — enforced at the query layer (and via Postgres row-level security if using Supabase), not just in application code
• Signed URLs for document upload/download expire after a short window (e.g. 5 minutes)
• Role check (Owner vs. Ops staff) enforced server-side on every mutation, never trusted from the client

Monitoring & backups

• Managed Postgres provider's automatic daily backups are sufficient at this scale — no custom backup pipeline needed
• Basic uptime/error monitoring (e.g. the hosting provider's built-in logs, or a free-tier error tracker) — full observability tooling is overkill for a single-pilot MVP

Single-tenant-per-row via company_id — not a separate schema per tenant. A company has many users and many clients; a client has many shipment jobs; a job has many cost line items and many documents.

erDiagram
    COMPANY ||--o{ USER : employs
    COMPANY ||--o{ CLIENT : "has as customer"
    CLIENT ||--o{ JOB : ships_for
    JOB ||--o{ COST_LINE : "costed by"
    JOB ||--o{ DOCUMENT : "attached to"
    USER ||--o{ JOB : creates
    USER ||--o{ COST_LINE : logs

    COMPANY {
        uuid id PK
        text name
        text subscription_status
        timestamptz created_at
    }
    USER {
        uuid id PK
        uuid company_id FK
        text email
        text role "owner | staff"
        timestamptz invited_at
        timestamptz joined_at
    }
    CLIENT {
        uuid id PK
        uuid company_id FK
        text name
        text contact_email
    }
    JOB {
        uuid id PK
        uuid company_id FK
        uuid client_id FK
        uuid created_by FK
        text lane
        numeric billed_amount
        text status "open | closed"
        timestamptz created_at
        timestamptz closed_at
    }
    COST_LINE {
        uuid id PK
        uuid job_id FK
        uuid logged_by FK
        text category "freight | duty | handling | trucking | other"
        numeric amount
        text note
        timestamptz created_at
    }
    DOCUMENT {
        uuid id PK
        uuid job_id FK
        uuid uploaded_by FK
        text doc_type "BL | CO | permit | other"
        text storage_key
        date expires_on
        timestamptz reminder_sent_at
        timestamptz created_at
    }

Key constraints

• JOB.billed_amount >= 0, COST_LINE.amount >= 0 — check constraints, costs are never entered negative (a correction is a note, not a negative line)
• USER.role restricted to owner / staff via a check constraint or enum
• Deleting a JOB or COST_LINE is restricted at the application layer to role = owner — not expressed as a DB-level permission, since the app always connects as one service role to a managed Postgres instance
• DOCUMENT.reminder_sent_at prevents the daily cron from sending the same reminder twice

API endpoints

Sitemap

• /login, /invite/:token — auth entry points
• /dashboard — list of open jobs, each showing live margin
• /jobs/:id — job detail: cost lines, documents, margin, status
• /jobs/new — create job form
• /clients — simple client list (name, contact) — not a full CRM
• /settings — company profile, staff list/invites, billing, reminder lead time (Owner only)

Dashboard structure

A single table of jobs (open by default, filterable to closed), columns: client, lane, billed amount, costs logged so far, margin, status. Margin is colored — green when positive, amber when thin, red when negative — so a forwarder scans the list and spots a problem job without opening it.

Screen-by-screen functionality

Visual style

Modern, minimal, professional — not playful. This is a tool used by ops staff mid-task, often on a shared desktop. Favor a dense, scannable table-first layout over cards; avoid heavy illustration or marketing-style visuals inside the app itself. Keep to one accent color for interactive elements and status color (margin health) kept visually distinct from that accent.

Responsive requirements

Desktop-first — ops staff work from a desk when logging costs and reviewing documents. A usable mobile view for checking margin on the go is a reasonable P1, not a P0 requirement; don't invest in a bespoke mobile layout before a pilot customer asks for one.

Sized for one developer. The goal is a pilot forwarder logging real shipments by week 8–10, not a feature-complete platform.

This 8–10 week estimate assumes no major surprises in the signed-URL upload flow (the one genuinely new technical surface here) and a pilot forwarder already lined up before Phase 4 starts. If no pilot is secured by week 6, pause new feature work and treat that as the actual blocker — building further without a real user logging real shipments just produces more unvalidated guesses about cost categories and document types.