{"id":18068403,"url":"https://github.com/fahimfba/vallocation","last_synced_at":"2026-05-04T11:39:38.585Z","repository":{"id":259527119,"uuid":"877332396","full_name":"FahimFBA/vallocation","owner":"FahimFBA","description":"Vehicle Allocation Management platform using FastAPI, MongoDB","archived":false,"fork":false,"pushed_at":"2024-10-25T07:37:05.000Z","size":898,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-14T11:57:38.818Z","etag":null,"topics":["fastapi","fastapi-mongodb","management-system","mongodb","rest-api","restful-api"],"latest_commit_sha":null,"homepage":"https://fahimfba.github.io/vallocation/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FahimFBA.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-23T13:28:11.000Z","updated_at":"2024-10-25T07:37:05.000Z","dependencies_parsed_at":"2024-10-26T08:06:03.900Z","dependency_job_id":"8a4d7f96-f42c-4d5c-bda9-c4e9707cacec","html_url":"https://github.com/FahimFBA/vallocation","commit_stats":null,"previous_names":["fahimfba/vallocation"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/FahimFBA/vallocation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FahimFBA%2Fvallocation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FahimFBA%2Fvallocation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FahimFBA%2Fvallocation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FahimFBA%2Fvallocation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FahimFBA","download_url":"https://codeload.github.com/FahimFBA/vallocation/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FahimFBA%2Fvallocation/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273986609,"owners_count":25202704,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-06T02:00:13.247Z","response_time":2576,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastapi","fastapi-mongodb","management-system","mongodb","rest-api","restful-api"],"created_at":"2024-10-31T08:06:19.554Z","updated_at":"2026-05-04T11:39:38.513Z","avatar_url":"https://github.com/FahimFBA.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Vehicle Allocation (Vallocation) Management Backend with FastAPI and MongoDB \n\n\nA fast and efficient **Vehicle Allocation System** built using **FastAPI** and **MongoDB**, designed to allow employees to allocate vehicles for specific dates, manage allocation statuses, and handle driver assignments. The system ensures that a vehicle is not double-booked and enforces date restrictions to prevent allocation modifications after the allocation date.\n\n![Banner](./docs-docusaurus/static/img/vallocation_banner.png)\n\n\u003e [!NOTE]\n\u003e Please check the [official website](https://fahimfba.github.io/vallocation/) for the complete instructions along with some popular resources!\n\n## Table of Contents\n- [Overview](#overview)\n- [Features](#features)\n- [Tech Stack](#tech-stack)\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Project Structure](#project-structure)\n- [API Endpoints](#api-endpoints)\n  - [Create an Allocation](#create-an-allocation)\n  - [Update an Allocation](#update-an-allocation)\n  - [Delete an Allocation](#delete-an-allocation)\n  - [Get Allocations History](#get-allocation-history)\n- [Database Schema](#database-schema)\n- [Contributors](#contributors)\n\n## Overview\n\nThe **Vehicle Allocation System** is a RESTful API that allows employees to reserve vehicles for specific days. Each vehicle has an assigned driver, and only one vehicle can be allocated per employee for a given day. Additionally, users can view, update, and delete allocations, provided the actions are performed before the allocated date.\n\nThis project is designed to handle a high number of users and vehicles, with optimizations for load handling and database efficiency.\n\n## Features\n\n- **Create Allocations:** Employees can allocate vehicles for future dates.\n- **Update Allocations:** Modify existing allocations before the allocation date.\n- **Delete Allocations:** Cancel allocations before the allocation date.\n- **Conflict Prevention:** Prevents multiple allocations of the same vehicle on the same date.\n- **Status Tracking:** Tracks the status of each allocation (e.g., pending, confirmed, canceled).\n- **Driver Assignment:** Each vehicle is pre-assigned to a driver.\n- **Performance Optimized:** Handles a large number of concurrent users and operations.\n  \n## Tech Stack\n\n- **Backend:** FastAPI\n- **Database:** MongoDB (Async with Motor)\n- **ORM:** Pydantic (For schema validation)\n- **Environment Management:** Python virtual environment\n- **Testing:** Pytest\n\n## Requirements\n\n- **Python 3.9+**\n- **MongoDB**\n- **FastAPI**\n- **Pydantic**\n- **Motor** (Async MongoDB driver)\n\n## Installation\n\nFollow these steps to set up and run the project locally.\n\n### 1. Clone the repository\n```bash\ngit clone https://github.com/FahimFBA/vallocation\ncd vallocation\n```\n\n### 2. Create a virtual environment\n```bash\npython -m venv env\nsource env/bin/activate  # On Windows: `env\\Scripts\\activate`\n```\n\n### 3. Install the required dependencies\n```bash\npip install -r requirements.txt\n```\n\n### 4. Set up environment variables\nCreate a `.env` file in the root directory with the following content:\n```\nMONGO_USERNAME=your_username\nMONGO_PASSWORD=your_password\nMONGO_CLUSTER_URL=your_mongodb_cluster_name\n```\n\n### 5. Run the application\nStart the FastAPI server:\n```bash\nuvicorn main:app --reload\n```\nor,\n```bash\nfastapi dev main.py\n```\n\nThe API will now be available at `http://127.0.0.1:8000`.\n\n## Project Structure\n\n```bash\nvallocation/\n│\n├── .github/               # Action Workflows\n├── config/\n│   └── database.py        # Database configuration for MongoDB\n│\n├── docs/                  # Documentation (Static Site - Generated by Docusaurus)\n│\n├── docs-docusaurus/       # Documentation (Docusaurus)\n│\n├── models/\n│   └── vallocation_model.py   # Pydantic model for vehicle allocations\n│\n├── routers/\n│   └── route.py           # FastAPI routes for vehicle allocation\n│\n├── schemas/\n│   └── schemas.py         # Pydantic schemas for request/response models\n│\n├── .env.example           # Example environment variables file\n├── .gitignore             # Git ignore rules\n├── LICENSE                # License file for the project\n├── main.py                # Entry point of the FastAPI application\n├── README.md              # Repository README\n├── requirements.txt       # Python dependencies for the project\n```\n\n## API Endpoints\n\n### Create an Allocation\n- **Endpoint:** `POST /allocate`\n- **Description:** Allocates a vehicle for a given employee on a specified date.\n- **Request Body:**\n  ```json\n  {\n    \"employee_id\": 101,\n    \"vehicle_id\": 456,\n    \"allocation_date\": \"2024-11-01\"\n  }\n  ```\n- **Response:**\n  ```json\n  {\n    \"id\": \"60c72b2f9b7e4e2d88d0f66b\",\n    \"employee_id\": 101,\n    \"vehicle_id\": 456,\n    \"driver_id\": 45,\n    \"allocation_date\": \"2024-11-01\",\n    \"status\": \"pending\"\n  }\n  ```\n\n### Update an Allocation\n- **Endpoint:** `PUT /allocate/{allocation_id}`\n- **Description:** Updates an existing allocation (e.g., change date or status).\n- **Request Body:**\n  ```json\n  {\n    \"allocation_date\": \"2024-11-02\",\n    \"status\": \"confirmed\"\n  }\n  ```\n\n### Delete an Allocation\n- **Endpoint:** `DELETE /allocate/{allocation_id}`\n- **Description:** Deletes an allocation before the allocation date.\n- **Response:**\n  ```json\n  {\n    \"message\": \"Allocation deleted successfully\"\n  }\n  ```\n\n### Get Allocation History\n- **Endpoint:** `GET /history/`\n- **Description:** Fetches allocation history with optional filters (e.g., by employee, vehicle, driver, or allocation date) and supports pagination.\n- **Query Parameters:**\n  - `employee_id` (optional): Filter allocations by employee ID.\n  - `vehicle_id` (optional): Filter allocations by vehicle ID.\n  - `driver_id` (optional): Filter allocations by driver ID.\n  - `allocation_date` (optional): Filter allocations by allocation date (format: `YYYY-MM-DD`).\n  - `skip` (optional, default: 0): Number of records to skip for pagination.\n  - `limit` (optional, default: 10): Maximum number of records to return.\n\n- **Response:**\n  ```json\n  {\n    \"total\": 100,\n    \"skip\": 0,\n    \"limit\": 10,\n    \"results\": [\n      {\n        \"id\": \"60c72b2f9b7e4e2d88d0f66b\",\n        \"employee_id\": 101,\n        \"vehicle_id\": 456,\n        \"driver_id\": 45,\n        \"allocation_date\": \"2024-11-01\",\n        \"status\": \"pending\"\n      },\n      {\n        \"id\": \"60c72b3f9b7e4e2d88d0f66c\",\n        \"employee_id\": 102,\n        \"vehicle_id\": 457,\n        \"driver_id\": 46,\n        \"allocation_date\": \"2024-11-02\",\n        \"status\": \"confirmed\"\n      }\n    ]\n  }\n  ```\n\n#### Example Request:\n```\nGET /history/?employee_id=101\u0026skip=0\u0026limit=10\n```\n\n#### Example Response:\n```json\n{\n  \"total\": 100,\n  \"skip\": 0,\n  \"limit\": 10,\n  \"results\": [\n    {\n      \"id\": \"60c72b2f9b7e4e2d88d0f66b\",\n      \"employee_id\": 101,\n      \"vehicle_id\": 456,\n      \"driver_id\": 45,\n      \"allocation_date\": \"2024-11-01\",\n      \"status\": \"pending\"\n    },\n    {\n      \"id\": \"60c72b3f9b7e4e2d88d0f66c\",\n      \"employee_id\": 101,\n      \"vehicle_id\": 458,\n      \"driver_id\": 47,\n      \"allocation_date\": \"2024-11-03\",\n      \"status\": \"confirmed\"\n    }\n  ]\n}\n```\n\n#### Pagination \u0026 Filters:\n- The endpoint allows pagination by using the `skip` and `limit` query parameters.\n- You can apply multiple filters like `employee_id`, `vehicle_id`, `driver_id`, or `allocation_date` to narrow down the results.\n\n## Database Schema\n\nEach allocation is stored in MongoDB in the following format:\n```json\n{\n    \"_id\": \"ObjectId('60c72b2f9b7e4e2d88d0f66b')\",\n    \"employee_id\": 101,\n    \"vehicle_id\": 456,\n    \"driver_id\": 45,\n    \"allocation_date\": \"2024-11-01\",\n    \"status\": \"pending\"\n}\n```\n\n## Contributors\n\n- **Fahim** - Developer, Architect\n- **[Contributors](https://github.com/FahimFBA/vallocation/contributors)**\n\nFeel free to open [issues](https://github.com/FahimFBA/vallocation/issues) or submit [pull requests](https://github.com/FahimFBA/vallocation/pulls) to help improve this project!\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffahimfba%2Fvallocation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffahimfba%2Fvallocation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffahimfba%2Fvallocation/lists"}