Momentum Logistics Services

The Problem

MLS was operating without a web presence and with a largely manual client intake process. Two specific pain points made scaling the business difficult:

• No marketing website — the company had no public-facing presence. New clients discovered them only through referral, and there was no way to communicate their services, coverage, or pricing online
• Manual package estimation — to generate a shipping estimate, staff needed the exact dimensions and weight of a package. Because clients rarely had this information to hand, staff frequently had to contact them directly — and in many cases, physically visit them to measure and photograph packages themselves

Operational Cost of Manual Estimation

The visit-based estimation workflow was expensive in time and resource:

• Travel overhead: Staff made in-person visits purely to measure packages — time that could be spent on actual logistics operations
• Manual photography: Packages were photographed on-site to document dimensions and condition before quotes could be prepared
• Quote delays: A process that should be instantaneous took hours or days, depending on staff availability and travel distance
• No self-service option: Clients had no way to explore pricing independently — every enquiry required direct staff involvement, regardless of complexity
• Existing invoicing tool, nothing else: The company had an internal invoicing system but nothing customer-facing — no dashboard, no tracking, no online payment flow

Marketing Website

The client-facing Next.js application includes a full public marketing section — service pages, coverage information, and calls-to-action routing prospective clients into the registration and estimate flows. Marketing pages use Next.js server components for fast initial loads and good SEO performance.

Shipment Estimation & Creation

The core user journey — getting a shipping estimate — is now entirely self-service:

• Users enter package dimensions and weight manually, or select from a set of common package presets
• The platform queries FedEx and DHL in parallel, normalises responses, and returns a comparison of available service levels (Standard, Express, etc.) with real-time pricing
• Volumetric weight is calculated automatically, and the greater of actual vs. volumetric weight is used for accurate pricing
• Estimates include a full pricing breakdown — base rate, applicable taxes, surcharges — in the user's local currency via real-time exchange rate conversion
• Saved estimates can be converted into shipments and paid through the dashboard; estimates expire after 24 hours

Invoicing System (KSef-Compliant)

MLS operates under Polish tax regulations, so the invoicing system was built with KSef compliance in mind:

• Invoices are generated automatically on shipment confirmation, with itemised line items, tax breakdowns, and unique invoice IDs
• Multiple invoice statuses — draft, issued, paid, cancelled, refunded — with lifecycle management and configurable expiry
• PDF export and email delivery via Brevo SMTP with EJS templates
• Automatic payment reminder emails at 1 day before expiry, on expiry, and every 3 days after — configurable per invoice
• Admin interface for viewing, resending, voiding invoices, and managing the full refund workflow (request → approve → execute)

Payment Processing

Two payment gateways cover MLS's Poland-based user base and international clients:

• Stripe — Card payments via webhook-verified checkout; primary gateway for most users
• PayU Poland — Native Polish payment processing via hosted checkout, using OAuth 2.0 Client Credentials flow
• Automatic fallback: If the primary gateway does not respond within 15 seconds, the system silently retries through the secondary gateway — transparent to the user
• Webhook-primary verification with a polling fallback (every 30 seconds for up to 5 minutes) ensures payment status reliability across both providers

Authentication & Security

• JWT-based auth — short-lived access tokens paired with long-lived refresh tokens; bcrypt password hashing
• Full verification flows — email verification on registration, phone verification via Twilio SMS, OTP-based email change and address update workflows
• Password management — reset via OTP code, in-dashboard password change, admin-initiated rotation
• Super-admin OTP login — enhanced security for super-admin accounts; automatic password rotation on a configurable schedule (30/60/90 days)
• Activity audit logging — all user and admin actions logged with actor, action, resource, timestamp, and before/after values

Admin CMS & RBAC

The admin dashboard is a separate Next.js application (mls-admin) with a flat, minimalist design built on shadcn/ui:

• Three-tier role hierarchy: Super Admin (full system access) → Admin → Staff (limited, configurable permissions)
• Granular permissions across users, shipments, invoices, payments, refunds, and tax rules — each independently toggleable per role
• User management: directory, profile editing, ban/unban, shipment and estimate history per user
• Carrier management: dynamic carrier listing, commission configuration per carrier, 4-stage hierarchical commission system with threshold-based tiers
• Shipment management: full lifecycle view, status override, payment bypass for flagged shipments
• Address verification: OTP-initiated address change requests flow through an admin approval/rejection interface

Outcomes

• Manual site visits eliminated — clients self-serve dimensions (or use presets), and the platform returns accurate carrier rates instantly
• End-to-end shipment lifecycle online — estimate, create shipment, pay, receive invoice, track delivery — all without staff involvement for standard shipments
• KSef-compliant invoicing in production — invoices generated, delivered, and managed within Polish tax requirements
• Dual-gateway payment resilience — automatic Stripe → PayU fallback prevents failed payments from breaking the checkout flow
• Contract value and scope expanded — the quality of deliverables led the client to extend the engagement and increase the contract scope beyond the original brief

Key Learnings

• Three-repo architecture pays off at scale: Separating the client app, admin dashboard, and backend into independent codebases allowed each to evolve at its own pace — the admin dashboard adopted shadcn/ui while the client app kept its custom design system, without either imposing constraints on the other.
• Payments need a fallback, not just a handler: Building the Stripe → PayU fallback with a 15-second timeout proved its value during a Stripe outage. No user saw an error; they were silently routed to PayU.
• Compliance is a feature: KSef compliance wasn't a checkbox — it shaped the invoice data model, the numbering system, the expiry logic, and the admin interface. Building it in from the start was far cheaper than retrofitting it later.
• Presets reduce friction significantly: Adding common package size presets to the estimate form dramatically reduced the number of users who abandoned the flow at the dimensions step.