Executive Summary
A freight company moving cargo between China and Nigeria was running on a legacy API with a single user role, so customers, agents, clearing partners and staff couldn't each get the right view of orders and shipments.
A new Next.js API on Supabase PostgreSQL with role-based authorisation on every route, a TanStack Start dashboard for staff, and a single Expo Router app whose sections change with the signed-in user's role. Records are never deleted: users are deactivated and shipment history is kept.
Core Capabilities & System Highlights
Role-Aware Mobile App
One Expo Router app with a section per role, sign-up by account type, live cargo updates and push notifications.
Cargo Timeline & Tracking
Staff receive goods, update cargo status and build a shipment timeline. Customers track by tracking number, air waybill or receiving number.
Approvals Workflow
Agents and clearing partners apply and are approved by staff before they get access.
Server-Side Authorisation
Every protected route loads the user's current roles and account status from the database, so role changes apply immediately.
System Architecture & Specs
Next.js App Router API
REST endpoints for orders, shipments, cargo and users, with ownership filtering for customer, agent and partner data.
TanStack Start Site & Dashboard
Public marketing site plus a staff dashboard for cargo, receiving goods, approvals, orders and shipments.
Expo Router App
A single app for every role with secure token storage, document and image pickers and push notifications.
Additive Migrations
Numbered, additive SQL migrations with backup and dry-run steps before every production change.
Key Engineering Trade-offs & Operational Notes
Instead of separate apps per audience, a single Expo app shows each user the sections their role allows.
Production holds live records, so schema changes are additive and always backed up and dry-run first.
The public tracking endpoint returns progress only: no names, phone numbers, notes or prices.
Tech Stack & Role Matrix
Every library and framework in Skyways Logistics Platform was chosen with intentional architectural trade-offs to balance speed, type safety, security, and scalability.
| Technology | Category | System Role | Performance Rationale |
|---|---|---|---|
| Next.js | Backend | API and business rules | One TypeScript codebase for every endpoint, deployed on Vercel. |
| Supabase | Database | Managed PostgreSQL | Reliable relational storage for orders, shipments and history. |
| TanStack Start | Framework | Website and staff dashboard | Type-safe routing and data loading for dashboard-heavy UIs. |
| Expo | Mobile | iOS and Android app | One codebase for every role on both platforms. |
Live Preview & Showcase
Skyways Logistics Platform Repository Record
This project is maintained directly as a public source code repository with technical documentation.
Metrics & Reliability
User Roles
Customer, agent, clearing partner, staff, admin
Apps
Website, dashboard and mobile app
Data Policy
Cargo, orders and shipment history are never deleted