RESTful API: The IDC Platform

1. Introduction

1.1 Project Overview

An advanced API solution designed specifically for Independent Delivery Contractors (IDCs) partnering with Intelcom Express Canada (Dragonfly). The platform aims to streamline and automate essential daily tasks associated with managing delivery operations. By focusing on resource management—encompassing routes, drivers, and fleet vehicles—The API enhances operational efficiency and driver satisfaction.

The Platform leverages historical performance data and intelligent algorithms to assign routes automatically, ensuring fairness and optimal workload distribution among drivers. This approach not only boosts driver morale but also contributes to improved customer service satisfaction scores, as satisfied drivers are more likely to deliver superior service.

1.2 Purpose and Problem Addressed

IDCs often face challenges in efficiently managing their resources due to:

• Manual Scheduling: Time-consuming processes leading to potential errors and inefficiencies.
• Uneven Workload Distribution: Some drivers may be overworked while others are underutilized, causing dissatisfaction.
• Lack of Performance Tracking: Difficulty in monitoring driver availability and performance metrics in real-time.
• Administrative Overheads: Excessive time spent on routine tasks rather than strategic planning.

The Platform addresses these issues by providing:

• Automated Resource Management: Minimizes manual intervention, reducing errors and saving time.
• Fair Workload Distribution: Ensures equitable assignment of routes based on data-driven insights.
• Enhanced Driver Satisfaction: Leads to better performance and lower turnover rates.
• Improved Customer Service: Happy drivers contribute to higher customer satisfaction levels.

2. Key Features

The Platform serves different users with different role access levels

Drivers : Each IDC has a team of drivers that prefer to work in different Intelcom's (Dragonfly) stations.

• Availability Submission: Drivers can submit their weekly availbaility schedules via the Driver Mobile App.
• Route Assignment Notification: Drivers can receive a Route Assignment Notification in near real-time.

Coming soon: More features will be documented very soon. Please check back later.

2. Motivation and Context

The inspiration for the Platfrom emerged from my personal experience as an Independent Contractor Driver with an IDC while I was in school. To support myself financially, I took on delivery routes, which gave me a unique opportunity to observe the daily operations and challenges firsthand. As a driver, I experienced the inefficiencies that many drivers and delivery contractors face and began conceptualizing solutions to improve the workflow for Independent Delivery Contractors (IDCs).

2.1 Real-World Experience:

During my time as a delivery driver, I encountered several recurring challenges that highlighted the need for a better system:

• Manual Workflows: Tasks such as route assignments and availability tracking were largely manual, which created bottlenecks and delays. As a driver, I frequently noticed that these processes were inefficient and often unfair.
• Unbalanced Workloads: Drivers, including myself, often faced inequities in the workload. Some drivers were given disproportionately difficult or lengthy routes, while others had less demanding ones, leading to frustration among drivers.
• Lack of Transparency and Real-Time Data: There was no clear mechanism to track my performance in real time or receive feedback on how I was doing, making it difficult for drivers to improve or for IDCs to optimize route assignments.
• Limited Driver Satisfaction: The absence of automated systems meant that drivers' concerns, such as fatigue and route preferences, were rarely considered, negatively impacting job satisfaction and overall performance.

This firsthand experience provided me with valuable insight into how the system could be improved. I wanted to create a platform that would not only streamline these operational tasks but also enhance fairness, reduce administrative burden, and increase driver satisfaction.

3. Technical Implementation

3.1 Technologies Used

• Node.js: A fast and scalable JavaScript runtime environment used for building the backend server.
• Express.js: A minimalist web framework for Node.js, used to manage API routes and handle requests/responses.
• TypeScript: A statically typed superset of JavaScript used to ensure type safety, enhancing maintainability and scalability.
• MongoDB: A NoSQL database used for storing and querying the application’s data.
• Redis: An in-memory data store used for caching frequently accessed data, improving API performance and reducing database load.
• JWT (JSON Web Tokens): Used for secure authentication and authorization of users through token-based sessions.
• Firebase Cloud Messaging: Integrated to send real-time notifications to drivers and other users of the platform.
• Nodemailer: Used for sending automated emails, such as notifications or alerts, to users.
• InversifyJS: A powerful and lightweight IoC (Inversion of Control) container for managing dependencies, following the Dependency Injection design pattern.
• Winston: A logging library used for capturing and managing logs, making it easier to debug and monitor the API.
• Mockito: A popular mocking framework used to simulate behavior in unit tests.
• Jest: A testing framework used for writing and running tests to ensure code reliability and correctness.
• Morgan: A HTTP request logger middleware for Node.js that provides detailed logs of API requests, aiding in monitoring and debugging.
• class-transformer: Used for transforming plain JavaScript objects into class objects, helping with data transformation and validation.
• class-validator: A powerful validation library that ensures data integrity and enforces validation rules on incoming requests and data models.

3.2 Architecture and Design

Monolithic API With Clean Architecture

The Api adopts a monolithic architecture with Clean Architecture principles. Clean Architecture is structured to ensure that the core business logic and application rules remain independent of external frameworks. This modular, decoupled design allows the system to be scalable, maintainable, and testable, making it an ideal choice for solo development and future scalability.

Design Patterns and Principles

• 1. Separation of Concerns (Layered Architecture)

  • The project is divided into distinct layers, each responsible for a specific role within the application:

    • Entities/Domain Layer: Contains the core business logic, such as Driver.entity.ts and Availability.entity.ts. This layer is framework-independent and does not rely on any external tools or libraries. Just pure javascript classes that have business rules & logic.

    • Use Cases/Application Layer: Encapsulates the business rules and workflows (e.g., createDriver.usecase.ts, fetchAvailability.usecase.ts). These use cases are responsible for orchestrating the application's behavior and ensuring that the core logic (from the domain layer) is executed correctly.

    • Interfaces/Adapters Layer (Infrastructure): This layer contains the infrastructure-specific code, such as repository implementations and external services & data access (e.g., MongoDB, Redis). For example, driver.repository.ts communicates with the MongoDB database, but this layer remains abstracted from the business logic.

    • Controllers/Routes (Presentation Layer): Manages how external requests are handled and routed through the system (e.g., driver.routes.ts, driver.controller.ts), translating them into the relevant use cases.

• 2. Dependency Inversion Principle (DIP)
  • The Dependency Injection (DI) pattern is used throughout the project via InversifyJS, adhering to the Dependency Inversion Principle. This allows higher-level modules (e.g., use cases) to remain independent of lower-level implementations (e.g., repositories).
  • The driverContainer.ts file shows how dependencies are injected and managed, which further decouples the application logic from specific implementations.

• 3. Use Case-Centric Design

  • Clean Architecture emphasizes that each action or feature of the system should be encapsulated within a specific use case. Your structure reflects this approach by having distinct use cases such as createDriver.usecase.ts, fetchAssignedRoute.usecase.ts, and updateDriverProfile.usecase.ts.
  • This not only keeps the codebase modular but also ensures that each feature of the system remains focused and testable in isolation.

• 4. Framework Independence

  • The core business logic (entities and use cases) is kept independent of external frameworks. This design allows for easier migrations or changes to the technology stack in the future (e.g., switching databases or web frameworks without affecting the business rules).
• 5. Interface Adapters (Infrastructure Layer)
  • Repositories and external services (e.g., Firebase Cloud Messaging, MongoDB) reside in the infrastructure layer, following the Repository Pattern. These components interact with external systems, but they remain abstracted from the use cases, ensuring that the business logic is not tied to specific technologies.
  • Mappers (e.g., availability.mapper.ts, driver.mapper.ts) ensure that data flowing between layers is transformed appropriately, adhering to the necessary DTO formats.
• 6. Validation and Data Transformation
  • class-validator and class-transformer are used to ensure that incoming requests are validated and transformed before they reach the core business logic. This keeps the domain layer clean and only concerned with well-formed data, preventing bugs and errors that could arise from bad inputs.

• 7. Centralized Error Handling

  • The application centralizes error handling using custom exceptions and middleware, ensuring consistent error reporting across the API. This aligns with Clean Architecture’s emphasis on maintaining consistency and isolation in how errors are managed across the application.
• 8. Testing Strategy
  • Jest and Mockito are used to write unit tests for the core use cases, ensuring that the business logic is well-tested and robust. Testing is focused primarily on the use cases, with mock dependencies to isolate the logic.

Documentation will be continued very soon. Please Check back later.