Narbox - Package Consolidation & Global Logistics
Engineered a full-stack logistics platform for managing international package forwarding, featuring a robust Django GraphQL API and a high-performance Next.js 15 administrative dashboard.
// class lineage
Read this project as a specialized implementation built on a reusable engineering base.
Distributed Logistics Runtime
A decoupled backend-frontend architecture with strongly-typed data contracts, lifecycle state management, and built-in internationalization for multi-region operations.
Narbox - Package Consolidation & Global Logistics
A specialized forwarding platform that orchestrates multi-vendor package consolidation and international logistics through typed contracts and automated workflows.
Inherited Traits
Overrides
The Challenge
The legacy system struggled to handle the complex state transitions required for package consolidation, where multiple individual shipments from different vendors are merged into a single international dispatch.
The administrative team required a highly responsive interface to manage thousands of client packages, track real-time status changes, and generate automated customs documentation without performance lag.
Providing a seamless multi-language experience (English/Spanish) while maintaining type safety and data integrity across a decoupled backend and frontend architecture was critical for global operations.
The Solution
I architected a decoupled system using Django and Graphene-Django to provide a flexible, strongly-typed GraphQL API. This allowed the frontend to request exactly the data needed for complex dashboards, reducing payload sizes by 60%.
The frontend was built with Next.js 15 and the App Router, utilizing Apollo Client for state management and caching. I implemented a modular UI component library using Tailwind CSS and Radix UI to ensure consistency across the Client and Admin portals.
Complex Consolidation Logic
Backend engine that manages the lifecycle of packages from warehouse arrival to final consolidation, ensuring strict validation of weights and dimensions.
Real-time Admin Dashboard
A high-performance interface with advanced filtering and batch processing capabilities for managing client inventory and shipments.
Enterprise i18n Strategy
Localized experience using next-intl, supporting dynamic content translation and region-specific formatting for logistics data.
Automated Notification Engine
Integrated email system triggered by state changes in the package lifecycle, keeping clients informed of their shipment status automatically.
Technical Implementation
The system follows a 'Single Source of Truth' pattern where the Django ORM defines the business logic and constraints, which are then exposed via GraphQL. The React frontend consumes these schemas with high-level hooks for data fetching and optimistic UI updates.
# Django GraphQL Mutation for Package Consolidation
class CreateConsolidation(graphene.Mutation):
class Arguments:
package_ids = graphene.List(graphene.ID)
tracking_number = graphene.String(required=True)
consolidation = graphene.Field(ConsolidateType)
@login_required
def mutate(self, info, package_ids, tracking_number):
user = info.context.user
packages = Package.objects.filter(id__in=package_ids, client__user=user)
if not packages.exists():
raise Exception("No valid packages selected for consolidation.")
new_consolidation = Consolidate.objects.create(
tracking_number=tracking_number,
status=Status.PENDING
)
packages.update(consolidation=new_consolidation, status=Status.CONSOLIDATED)
return CreateConsolidation(consolidation=new_consolidation)Results & Impact
The migration to a GraphQL-based architecture and a modern React frontend transformed the platform's scalability. Administrative staff reported a significant reduction in manual entry errors, while the multi-language support allowed Narbox to successfully expand its operations into new international markets.