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\nabout the product"] --> B{"Currently tracking\nmargin 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\non a sample shipment"]
    D --> E{"Agrees to pilot?"}
    E -- "No" --> X
    E -- "Yes" --> F["Setup call:\ncompany + staff invited"]
    F --> G["Team logs NEW shipments\ngoing forward"]
    G --> H{"Margin visibility\nactually used weekly?"}
    H -- "No" --> R["Churn risk —\nfounder follow-up"]
    H -- "Yes" --> I["Converts to paid\nmonthly subscription"]
    I --> J["Renews month over month"]

B. Customer onboarding

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

C. Core product operation — working a shipment

flowchart TD
    A["Create job:\nclient, billed amount, lane"] --> B["Job appears in\nopen-jobs list"]
    B --> C["Any staff member logs\na cost line item"]
    C --> D["Margin recalculates\nimmediately"]
    D --> E{"More invoices\nstill expected?"}
    E -- "Yes" --> C
    E -- "No" --> F["Owner marks\njob closed"]
    A --> G["Upload BL / CO / permit\nto the job"]
    G --> H{"Document has\nan expiry date?"}
    H -- "Yes" --> I["Reminder scheduled\n14 days before expiry"]
    H -- "No" --> J["Stored, no reminder"]
    I --> K{"Renewed before\nexpiry?"}
    K -- "No" --> L["Overdue flag shown\non job"]
    K -- "Yes" --> J

D. User roles and permissions

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

E. Subscription and payment process

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

F. Administrative workflow

flowchart TD
    A["Owner opens\nCompany Settings"] --> B["Invite / remove staff"]
    A --> C["View billing &\ninvoice history"]
    A --> D["Set expiry reminder\nlead time (default 14 days)"]
    A --> E["Export all shipment\ndata as CSV"]
    B --> F{"Staff removed\nmid-pilot?"}
    F -- "Yes" --> G["Their logged jobs\nreassigned to Owner,\naudit 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\n(dashboard, job, documents)"]
    end
    subgraph App["Next.js app (Vercel)"]
        SA["Server actions /\nAPI routes"]
        CRON["Scheduled function:\ndaily expiry check"]
    end
    subgraph Data["Managed data layer"]
        DB[("Postgres\nSupabase / Neon")]
        STORE[("Object storage\nR2 / Supabase Storage")]
    end
    EMAIL["Email provider\n(Resend)"]
    PAY["Payment gateway\n(CHIP / Stripe)"]

    UI -->|"reads/writes"| SA
    SA -->|"query/mutate"| DB
    SA -->|"signed upload/download URL"| STORE
    UI -->|"direct upload via\nsigned 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.