Shipping operations system with scan-first confirmation

This was one workstream inside a broader internal operations platform, not a separate standalone product. The transferable engineering problem was full-stack workflow reliability: make handheld input fast for the operator while keeping the API and database responsible for the truth.

The old path depended on paper checklists, handwriting, messenger updates, Excel edits, and email sharing. The new path let operators scan shipping work directly and made the result visible to office users through the website.

Artifact note: screenshots, data examples, and code seams below are public-safe reconstructions of the production workflow. Actual UI, identifiers, customer data, and private table names are redacted; the workflow, validation cases, and system boundaries reflect the implementation I owned.

Before and after

Before:

Operator checks boxes manually
  -> writes or messages shipment update
  -> office user re-enters status in Excel
  -> spreadsheet or email becomes the latest source of truth
  -> another user asks whether the shipment is actually ready

After:

Operator opens PDA shipping screen
  -> selects shipment context
  -> scans box/order barcode
  -> API validates duplicate, shipment, and allowed status
  -> valid scan is saved or staged for review
  -> web dashboard shows updated shipping state

The product change was not only a better screen. It removed the manual translation step between floor work and office visibility, and it moved the most important decision to the backend: is this scan allowed for this shipment right now?

My ownership

I helped architect the shipping domain and served as the primary builder for the module. My work included:

• mapping the shipping process with operators and office users;
• designing the scanner workflow, error states, and recovery path;
• implementing React/PWA handheld screens for fast barcode input;
• connecting scan actions to NestJS validation endpoints;
• modeling accepted, duplicate, wrong-shipment, quality-hold, and not-shippable outcomes;
• writing progress and confirmation state into PostgreSQL current/history records;
• aligning the shipping workflow with receiving, quality, and dashboard screens.

Artifact: scan-first workflow

Artifact: implementation boundary

Simplified from the production API shape; names and identifiers are changed.

type ShippingScanRequest = {
  shipmentId: string;
  scannerSessionId: string;
  barcode: string;
  scannedAt: string;
  operatorId: string;
};

type ShippingScanResult =
  | {
      result: "accepted";
      boxId: string;
      shipmentId: string;
      scannedCount: number;
      expectedCount: number;
      nextAction: "scan_next" | "review_and_confirm";
    }
  | {
      result: "blocked";
      reason: "duplicate" | "wrong_shipment" | "quality_hold" | "not_shippable";
      message: string;
      blockingStatus?: "quality_hold" | "already_shipped" | "not_received";
    };

The frontend showed immediate feedback, but it did not invent the business rule. The API checked shipment context, duplicate state, and current box status before a scan became part of the shipment record.

Operational story

A realistic failure case was a box physically sitting in the shipping area while the system record was still on quality hold. In the old workflow, that could become reconciliation work after someone updated the sheet or sent the wrong status message. In the scanner workflow, the PDA returned a blocked message immediately and the row never became part of the confirmed shipment.

That gave floor users a simple path: scan, see accepted or blocked, keep moving. It also gave office users a better answer than “wait for the updated spreadsheet.”

Outcome

This workflow was used in daily shipping operations.

• Operators could scan and save shipment work instead of writing it down first and having someone re-enter it into Excel.
• Office users could see shipping state on the website without waiting for a message, spreadsheet, or email update.
• Duplicate, wrong-shipment, and blocked-status cases were handled before confirmation instead of becoming reconciliation work later.
• The reusable full-stack pattern was scanner-speed UX backed by server-side validation and durable shipment state.