Gig Overview

This backend gig focuses on implementing a Fuel Management Service that enables vehicle fuel tracking, assignment-based fuel logging, consumption efficiency computation, and fleet-wide performance insights. This service plays a key role in optimizing fuel usage, identifying inefficiencies, and providing actionable metrics to logistics managers.

You are expected to implement a clean, maintainable, and secure set of API endpoints using Node.js, TypeScript, Prisma ORM, and Express.js. All input validations must use Joi, and responses should conform to the standardized response structure.

GitHub Repository

Repo: https://github.com/suburban-fiber-company/Logistics_Fleet_Service/tree/fuel_management  

Branch: fuel_management (Ensure to work strictly within this branch)

Scope of Work

You will work strictly within the FuelManagementController.ts, implementing the following endpoints:

- Implementation Guidelines

1. Use existing FuelManagementController.ts and routes.

2. Validate request payloads using Joi, with all schemas defined in the validations/ folder.

3. Use Swagger.IO to document all endpoints with meaningful descriptions.

4. Send user-friendly validation error messages with proper HTTP status codes.

5. Paginate all retrieval and allow filters where relevant. Use the PaginatedResult in types.ts 

6. Ensure robust error handling for not found (404), bad request (400), and validation issues (422).

7. Implement middleware for API Key authentication.

8. Ensure that every single record is checked where necessary

9. Database transaction should be used where multiple models are saved within a single method

Endpoints Specification:
1. Create Fuel Log

• Method: POST

• Endpoint: /api/v1/logistics-fleet-service/fuel-logs/

• Description: This endpoint creates a new fuel log for a vehicle. It records key data such as fuel volume, odometer reading, registration number, assignment ID, and date of entry. The system must validate all input data to ensure logical consistency (e.g., fuel volume must be positive, odometer reading must increase over time). Refer to FuelLog model for more details

• Response:
  Sample Response

{

"status": "success",

"message": "Fuel log created successfully",

"data": []

}

2. Get Fuel Logs by Vehicle

• Method: GET

• Endpoint: /api/v1/logistics-fleet-service/fuel-logs/vehicle/:registration_number

• Params: registration_number (Path) – The vehicle’s unique plate number

• Description: Retrieves all fuel logs for a specific vehicle, ordered by most recent first. This allows managers to track refueling patterns, identify irregularities, and audit usage over time.

• Response:

Sample Response

{

"status": "success",

"message": "message displayed here",

"data": []

}

3. Get Fuel Logs by Assignment

• Method: GET

• Endpoint: /api/v1/logistics-fleet-service/fuel-logs/assignment/:assignment_id

• Params: assignment_id (Path) – The ID of the vehicle assignment

• Description: Fetches fuel logs tied to a specific assignment. This is used to assess the fuel consumption for a trip or delivery route and link performance data to specific drivers or tasks.

• Response:

Sample Response

{

"status": "success",

"message": "message displayed here",

"data": []

}

4. Compute Fuel Efficiency

• Method: GET

• Endpoint: /api/v1/logistics-fleet-service/fuel-logs/assignment/:assignment_id/efficiency

• Params: assignment_id (Path) – The assignment for which efficiency should be calculated

• Description: Calculates the fuel efficiency (km/l) for a given assignment by comparing odometer readings and total litres logged. If data is insufficient to compute this metric, the API should return a friendly message and avoid division by zero or other calculation errors.

• Response:

Sample Response

{

"status": "success",

"message": "message displayed here",

"data": {}

}

5. Get Fleet Performance Metrics

• Method: GET

• Endpoint: /api/v1/logistics-fleet-service/fuel-logs/performance-metrics
  
  

• Query Params: start_date, end_date – To filter performance by time range

• Description: Provides summarized performance metrics across the fleet, such as average fuel efficiency, highest and lowest performing vehicles, and consumption trends over time.

• Response:

Sample Response

{

"status": "success",

"message": "message displayed here",

"data": {}

}

6. Get Fleet Fuel Summary

• Method: GET

• Endpoint: /api/v1/logistics-fleet-service/fuel-logs/summary

• Description: Returns a consolidated summary of fuel consumption for the entire fleet. This may include total litres consumed, average efficiency, number of logs recorded, and total number of vehicles with logs in the system

• Response:

Sample Response

{

"status": "success",

"message": "message displayed here",

"data": {}

}

Common Error Response Template

{
  "status": "error",
  "message": "Sorry, unable to complete the operation. Please, try again"
}

Required Skills:

• Node.js with TypeScript

• Prisma ORM (MySQL)

• Joi validation

• Swagger.IO for documentation

• REST API design principles

• Secure middleware usage

Software/Design Requirements:

• Language: Node.Js/Typescript.

• Database:

  • Prisma (MySQL) for persistent data storage.

• Design Pattern: Adapter pattern to standardize API interactions.

• Documentation: Swagger for API documentation and testing.

Breakdown of Common API status codes

“Please ensure all of the status codes are properly handled for seamlessly frontend integration”

• 400 Bad Request – The server cannot process the request due to client error (e.g., invalid JSON, missing parameters).

• 401 Unauthorized – The request lacks valid authentication credentials (e.g., missing or invalid token).

• 404 Not Found – The requested resource does not exist on the server.

• 422 Unprocessable Entity – The request is well-formed but contains invalid data (e.g., validation errors).

• 500 Internal Server Error – A generic server-side error, often due to unexpected failures in processing.

Expectations: 

As a Techo chosen to participate in this gig, we have some expectations.

• Timely Completion: complete each gig within the given timeframe. If the gig has not been completed within this frame, the project will be re-assigned.

• Communication: Stay in touch with the Community Manager for guidance, support and feedback throughout the project. This can be done through the chat box in the My Gigs section underneath the gig description.

• Work-Ethic Alignment: Make a concerted effort to comply with our standards.

• It is very key that Techo pays very attentions to details so as to avoid disqualification or re-assigning of the gig

• Where the project structure has been defined, it is very important that the Techo does not deviate from the established structure