NTD

Shipment Tracking System for Logistics

A robust full-stack web application for managing and tracking logistics shipments, with user management and dashboard analytics.

Project Overview
Details and technologies
Full Stack Web Application

This comprehensive system streamlines logistics operations by allowing administrators to manage users and track shipments from creation to delivery. It provides a user-friendly interface for creating, viewing, editing, and deleting shipment records. The system features a powerful dashboard with real-time statistics, charts for various metrics (status, type, office, payment), and recent activity. Secure JWT authentication and role-based access control ensure data integrity and user permissions. Built with Next.js, React, Prisma, and PostgreSQL, it offers a scalable and efficient solution for logistics management.

Technologies

Next.jsReactTypeScriptTailwind CSSShadcn UIRechartsSonnerNode.jsNext.js API RoutesPrisma ORMPostgreSQLJWT (Jose)BcryptjsCloudinaryLucide React

Key Features

  • •Secure User Authentication (JWT)
  • •Role-Based Access Control (Admin/User)
  • •Comprehensive Shipment CRUD (Create, Read, Update, Delete)
  • •Interactive Dashboard with Analytics and Charts
  • •Shipment Filtering, Search, Pagination, and Sorting
  • •Detailed Shipment Views
  • •User Management (Admin-only)
  • •Responsive Design
  • •Activity Logging
  • •Customizable Statuses for Shipments, Payments, and Tax Refunds
    • Project Screenshots
    Scroll through to see some pages of the application
    1 / 9

    Dashboard Overview

    Dashboard

    Central dashboard with key statistics, monthly trends, and distribution charts for shipments.

    Dashboard Overview
    Shipment List (Table View)
    Shipment List (Grid View)
    Shipment Details Page
    Shipment Form (Basic Tab)
    Shipment Form (Details Tab)
    User Login Page
    Admin User List
    Admin Add/Edit User Form

    System Architecture

    Architecture Overview

    The Shipment Tracking System is a robust full-stack web application designed for logistics management. It provides comprehensive tools for administrators to manage users and track shipments, offering detailed views, analytics, and secure role-based access.

    Frontend Layer

    Built with Next.js, providing server-side rendering for optimal performance and a rich user experience.

    Technologies

    Next.jsReactTypeScriptTailwind CSSShadcn UIRecharts

    Components

    • Dashboard
    • Shipment List (Table/Grid)
    • Shipment Details
    • Multi-tabbed Forms
    • User Management UI
    • Login Page
    Backend Services

    Handles API routes, business logic, authentication, and database interactions, leveraging Next.js API Routes.

    Technologies

    Node.jsNext.js API RoutesPrisma ORMJWT (Jose)Bcryptjs

    Components

    • Authentication API
    • Shipment CRUD API
    • Dashboard Analytics API
    • User Management API
    • Data Filtering & Pagination
    Database Layer

    Scalable relational database for storing all logistics and user data.

    Technologies

    PostgreSQLPrisma ORM

    Components

    • Shipment Records
    • User Accounts
    • Status Enums
    • Audit Logs
    Deployment & Infrastructure

    Modern cloud-native deployment strategy ensuring scalability and reliability.

    Technologies

    Vercel (Frontend/API)Cloudinary (Asset Management)Docker (Conceptual)

    Components

    • Serverless Functions (API Routes)
    • Managed Database Service
    • CDN for Assets

    System Architecture Diagram

    Admin Users
    General Users
    Next.js App
    Next.js API Routes
    Prisma ORM
    PostgreSQL DB
    Cloudinary (Assets)
    JWT Authentication
    Shipment Service
    Dashboard Analytics
    Admin UI Access
    User Portal
    API Requests
    Auth Requests
    Shipment Data
    Analytics Requests
    Asset Uploads
    User Auth Data
    Read/Write Shipment
    Aggregated Data
    ORM Queries
    Display Assets
    Wheel to zoom • Drag to pan • Click elements for details
    100%

    Key System Interactions

    Authentication & Authorization

    Users log in via JWT. Next.js middleware and API routes enforce role-based access for admins and general users for all data access.

    Shipment Lifecycle Management

    Admins perform CRUD operations on shipments. The system tracks status changes, container details, and payment/tax refund statuses throughout the shipment journey.

    Dashboard Data Aggregation

    Backend APIs efficiently query and aggregate shipment data to provide real-time statistics and trends for the interactive dashboard.

    Dynamic Data Filtering

    The shipment list supports advanced filtering, searching, and pagination, with backend queries optimized for performance and responsiveness.

    Key Features

    Secure Authentication

    JWT-based authentication with Bcrypt for password hashing ensures secure access.

    Comprehensive CRUD

    Full control over shipment records, including creation, viewing, editing, and deletion.

    Interactive Analytics

    Visualize key logistics metrics and trends through dynamic charts on the dashboard.

    Advanced Data Management

    Robust filtering, searching, and pagination capabilities for efficient data navigation.

    Implementation Details

    Installation & Setup

    The system is divided into client (frontend) and server (backend) components, each with its own installation process:

    git clone https://github.com/Nardos-Tilahun/shipment-tracking-system.git
    cd shipment-tracking-system
    npm install
    # Configure environment variables (.env.local) for database connection, JWT secret, etc.
    npx prisma db push # To sync database schema
    npx prisma db seed # To seed initial data (optional)

    Development Environment

    Running the application requires starting the necessary services:

    # Run in development mode
    npm run dev
    The application will be available at http://localhost:3000

    Security Considerations

    • JWT for API authentication and authorization (with Jose library)
    • Bcrypt.js for secure password hashing
    • Role-Based Access Control (RBAC) enforced on API routes and UI
    • Environment variables for sensitive API keys and database credentials
    • Input validation on all forms and API endpoints
    • HTTPS enforcement in production

    Challenges & Solutions

    Building this full-stack system involved several complex challenges that required innovative solutions and professional growth.

    Robust Auth & RBAC Implementation

    Challenge:

    Building a secure authentication and role-based access control (RBAC) system from scratch, ensuring seamless integration between Next.js API routes and client-side protected pages, while preventing unauthorized data access or actions.

    Solution:

    I developed a custom JWT-based authentication flow using `jose` for token handling and `bcryptjs` for secure password hashing. Implemented middleware in Next.js API routes to verify tokens and inject user roles/IDs. Client-side, a global `AuthContext` managed user sessions, redirecting unauthenticated users and dynamically adjusting UI based on roles.

    Click to see solution

    Complex Data Query Optimization

    Challenge:

    Optimizing Prisma queries for a dashboard displaying various aggregated statistics (counts, monthly trends) and for a flexible shipment list with search, filtering, sorting, and pagination, all while maintaining performance for potentially large datasets.

    Solution:

    I leveraged Prisma's `groupBy`, `count`, and `findMany` with dynamic `where` clauses and `orderBy` options. For the dashboard, I used `Promise.all` with multiple Prisma queries to fetch all required data concurrently. For the list, I implemented server-side pagination and filtering based on URL query parameters, ensuring only relevant data is fetched.

    Click to see solution

    Multi-Tabbed Form Validation & UX

    Challenge:

    Creating a multi-tabbed shipment creation/editing form that guides the user through required fields, provides real-time validation feedback, and ensures all necessary data is present before submission across different sections.

    Solution:

    The `ShipmentForm` component was structured using Shadcn UI's `Tabs`. I implemented a state-managed form with a validation function that checks all required fields on the *current* tab when navigating. Field-specific error messages are displayed below inputs, and a global toast notifies the user if validation fails before proceeding or submitting.

    Click to see solution

    Consistent Error Handling & User Feedback

    Challenge:

    Ensuring that all API interactions, whether for fetching, creating, updating, or deleting data, provide consistent, clear, and actionable error messages to the user across the application.

    Solution:

    I established a centralized error handling pattern. On the server-side, Next.js API routes return JSON `{ error: "..." }` with appropriate HTTP status codes. On the client, fetches use `try-catch` blocks and `response.json()` to extract custom error messages. `sonner` toasts are used to display these messages in a non-intrusive way, improving the overall user experience during unexpected issues.

    Click to see solution

    Project Outcomes

    Despite these challenges, I successfully delivered a full-stack application that provides a comprehensive platform. The system now efficiently handles all core requirements while maintaining high standards of security and user experience.

    100%
    Core requirements met
    4
    Major challenges overcome
    1+
    Key solutions developed

    Code Implementation Highlights

    Key code examples from this financial software project, showcasing authentication, calculations, visualizations, and data management implementations.

    Future Improvements

    Strategic enhancements planned for the Personal Loan Management System, designed to extend functionality and improve user experience.

    Real-time Tracking & GPS Integration

    Integrate with third-party GPS tracking services and carrier APIs to provide real-time location updates of shipments on a map interface, accessible to both admins and potentially customers.

    BENEFITS

    Enhanced visibility, proactive issue resolution, improved customer satisfaction, reduced manual tracking efforts.

    TECHNOLOGIES

    Google Maps API, OpenStreetMap, WebSockets, MQTT, Carrier APIs (e.g., FedEx, DHL)

    Automated Notifications & Alerts

    Implement an automated notification system to send email/SMS alerts for key shipment milestones (e.g., departure, arrival, delays, status changes) to relevant stakeholders (customers, agents).

    BENEFITS

    Timely communication, reduced customer inquiries, proactive issue alerts, improved operational efficiency.

    TECHNOLOGIES

    Twilio, SendGrid, Cron jobs, Event-driven architecture (Kafka/RabbitMQ)

    Customer & Agent Portals

    Develop dedicated, restricted-access portals for customers to view their shipment statuses and for external agents (e.g., Djibouti Agent) to update shipment milestones directly.

    BENEFITS

    Self-service capabilities, reduced administrative burden, improved collaboration with partners, enhanced transparency.

    TECHNOLOGIES

    NextAuth.js (for external users), dedicated React components, API access controls

    Advanced Reporting & Export

    Expand dashboard capabilities with custom report generation (e.g., monthly volume reports, performance metrics by office/agent) and export options (PDF, Excel).

    BENEFITS

    Deeper business insights, easier compliance reporting, enhanced data analysis capabilities, improved data sharing.

    TECHNOLOGIES

    React-PDF, SheetJS (for Excel), Chart.js (for new chart types), Data warehousing (if data volume grows)

    Document Management

    Add functionality to upload, store, and manage shipment-related documents (e.g., invoices, customs declarations) securely, with versioning and search capabilities.

    BENEFITS

    Centralized document repository, reduced manual paperwork, improved compliance, quicker document retrieval.

    TECHNOLOGIES

    AWS S3, Google Cloud Storage, OCR (Optical Character Recognition) libraries, Elasticsearch (for document search)

    Mobile Application

    Develop a native mobile application (iOS/Android) for administrators and field agents to manage and update shipment statuses on the go, including offline capabilities.

    BENEFITS

    Increased operational flexibility, faster updates from field, improved agent efficiency, better accessibility.

    TECHNOLOGIES

    React Native, Expo, Firebase (for push notifications/offline data), SQLite (for local storage)