{"id":30283199,"url":"https://github.com/rupesh-dev30/air-cargo-booking-and-tracking","last_synced_at":"2025-08-16T17:33:48.074Z","repository":{"id":310091332,"uuid":"1038265146","full_name":"rupesh-dev30/Air-Cargo-Booking-and-Tracking","owner":"rupesh-dev30","description":"GoComet Assesment","archived":false,"fork":false,"pushed_at":"2025-08-15T16:19:14.000Z","size":454,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-15T18:33:56.025Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rupesh-dev30.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null}},"created_at":"2025-08-14T22:27:07.000Z","updated_at":"2025-08-15T16:19:17.000Z","dependencies_parsed_at":"2025-08-15T18:33:59.387Z","dependency_job_id":"c0a1138a-c6f1-4cd3-9418-479ac236328d","html_url":"https://github.com/rupesh-dev30/Air-Cargo-Booking-and-Tracking","commit_stats":null,"previous_names":["rupesh-dev30/air-cargo-booking-and-tracking"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/rupesh-dev30/Air-Cargo-Booking-and-Tracking","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rupesh-dev30%2FAir-Cargo-Booking-and-Tracking","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rupesh-dev30%2FAir-Cargo-Booking-and-Tracking/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rupesh-dev30%2FAir-Cargo-Booking-and-Tracking/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rupesh-dev30%2FAir-Cargo-Booking-and-Tracking/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rupesh-dev30","download_url":"https://codeload.github.com/rupesh-dev30/Air-Cargo-Booking-and-Tracking/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rupesh-dev30%2FAir-Cargo-Booking-and-Tracking/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270746846,"owners_count":24638428,"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-08-16T02:00:11.002Z","response_time":91,"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":[],"created_at":"2025-08-16T17:33:46.711Z","updated_at":"2025-08-16T17:33:48.029Z","avatar_url":"https://github.com/rupesh-dev30.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Air Cargo Booking \u0026 Tracking System\n\nThis project is a full-stack application designed to manage the booking and tracking of air cargo shipments. The system provides a robust backend for handling booking logic, flight information, and real-time status updates, complemented by a simple and intuitive UI for user interaction.\n\n---\n\n# DOCUMENTATION\nhttps://www.notion.so/Air-Cargo-Booking-Tracking-System-Documentation-250a3413cab280e1b928c37f96a1c075?source=copy_link\n\n---\n\n## 🚀 Project Objective\n\nThe primary goal is to build a system that allows users to create an air-cargo booking and track its status from the point of origin to its final destination.\n\n---\n\n## 📊 Data Models\n\nThe system is built around two core data models:\n\n### **`Booking`**\n\n- `ref_id`: A human-friendly, unique identifier for each booking.\n- `origin`: The starting location of the cargo.\n- `destination`: The final destination of the cargo.\n- `pieces`: The number of items in the shipment.\n- `weight_kg`: The total weight of the shipment in kilograms.\n- `status`: The current state of the booking (e.g., `BOOKED`, `DEPARTED`, `ARRIVED`, `DELIVERED`).\n- `timestamps`: Timestamps for creation and last update.\n- `flight_ids`: An array of Flight IDs associated with the booking.\n\n### **`Flights`**\n\n- `flight_id`: Unique identifier for the flight.\n- `flight_number`: The specific flight number.\n- `airline_name`: The name of the airline operating the flight.\n- `departure_datetime`: Scheduled departure date and time.\n- `arrival_datetime`: Scheduled arrival date and time.\n- `origin`: The airport of origin.\n- `destination`: The airport of destination.\n\n---\n\n## ✨ Functional Requirements\n\nThe backend API provides the following core functionalities:\n\n1.  **Get Route**\n    - **Input**: `origin`, `destination`, `departure_date`.\n    - **Output**:\n      - Direct flights matching the request.\n      - Single transit routes where the connecting flight departs on the same day or the day after the first leg's arrival.\n\n2.  **Create Booking**\n    - Creates a new booking with the provided basic details.\n    - Initializes the booking status to `BOOKED`.\n\n3.  **Depart Booking**\n    - Updates a booking's status to `DEPARTED`.\n    - Records a departure event in the booking's timeline, including origin and optional flight details.\n\n4.  **Arrive Booking**\n    - Updates a booking's status to `ARRIVED` at a specified location.\n    - Records an arrival event in the booking's timeline.\n\n5.  **Get Booking History (by `ref_id`)**\n    - **Input**: `ref_id`.\n    - **Output**: Returns all basic booking details along with a full, chronological event timeline. This is used by the UI to display tracking history.\n\n6.  **Cancel Booking**\n    - Marks a booking as `CANCELLED`.\n    - A booking cannot be canceled once its status is `ARRIVED`.\n\n---\n\n## 🛠️ Non-Functional Requirements\n\n- **Concurrency**: The system must handle concurrent operations on the same booking from multiple users. Distributed locks will be used to ensure data integrity.\n- **Scalability**: The system is designed to handle high transaction volumes:\n  - **Bookings**: \\~50,000 new bookings per day.\n  - **Updates**: \\~150,000 updates per day.\n  - **Flights**: \\~100,000 active flights with roughly 10 flights per Origin-Destination pair daily.\n- **Logging**: A basic logging system is in place for debugging and monitoring.\n\n---\n\n## 🖥️ User Interface (UI)\n\nThe frontend provides the following pages:\n\n- **Create Booking Form**: A form for users to submit new cargo bookings.\n- **Search Booking**: A page to search for a specific booking using its `ref_id`.\n- **Booking Detail Panel**: A detailed view showing the booking's current status and its complete timeline history.\n\n---\n\n## 🚀 Getting Started\n\nFollow these steps to set up the project and run the API and UI locally.\n\n### **1. Project Setup**\n\n1.  **Clone the repository:**\n\n    ```bash\n    git clone https://github.com/rupesh-dev30/Air-Cargo-Booking-and-Tracking.git\n    cd air-cargo-booking-and-tracking\n    ```\n\n2.  **Install dependencies:**\n\n    ```bash\n    npm install\n    ```\n\n3.  **Using Turbo Repo:**\n\n    ```bash\n    turbo run dev\n    ``` \n\n### **2. Environment Variables**\n\nBefore running the applications, you need to set up the environment variables.\n\n#### API\n\nCreate a `.env` file in the root of the `apps/api/` directory with the following configuration:\n\n```\nPORT=9001\n\n# DATABASE\nDB_HOST=localhost\nDB_PORT=5432\nDB_USERNAME= # \u003cDB_USERNAME\u003e\nDB_PASSWORD= # \u003cDB_PASSWORD\u003e\nDB_NAME=aircargo\n```\n\n#### Web UI\n\nCreate a `.env` file in the `apps/web/` directory. This file should contain the URL of your API.\n\n```\nNEXT_PUBLIC_API_URL=http://localhost:9001\n```\n\n### **3. Running the Project**\n\nTo run both the API and Web UI, you can use a unified command if your project uses a tool like Turborepo. Otherwise, you'll need to start them separately:\n\n- **To start the API:**\n\n  ```bash\n  cd apps/api\n  npm run dev\n  ```\n\n- **To start the Web UI:**\n\n  ```bash\n  cd apps/web\n  npm run dev\n  ```\n\n---\n\n## ✅ Evaluation Criteria\n\nThe final solution will be evaluated based on the following:\n\n1.  **Database Design**: Choice of database and effective data modeling.\n2.  **Code Structure**: Clean, modular, and maintainable code.\n3.  **Performance**: Optimized for high-throughput and low-latency operations.\n4.  **Indexing**: Proper database indexing for efficient queries.\n5.  **Caching**: Strategic use of caching to improve performance.\n6.  **Testing**: Comprehensive unit tests to ensure reliability.\n7.  **Monitoring**: Implementation of monitoring tools to track system health.\n8.  **UI/UX**: Clean, simple, and usable user interface.\n9.  **Documentation**: Clear and concise High-Level Design (HLD) and Low-Level Design (LLD) documentation.\n\n---\n\n## 📦 Final Deliverables\n\nThe complete project will include:\n\n1.  **Backend Code**: The source code for the API and business logic.\n2.  **Frontend Code**: The source code for the user interface.\n3.  **Recorded Demo**: A video demonstration of the system's functionality.\n4.  **Documentation**: All relevant design and implementation documents.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frupesh-dev30%2Fair-cargo-booking-and-tracking","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frupesh-dev30%2Fair-cargo-booking-and-tracking","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frupesh-dev30%2Fair-cargo-booking-and-tracking/lists"}