Skip to content

Commit

Permalink
docs: add Rental Module DesignDoc for Moto Delivery Manager
Browse files Browse the repository at this point in the history
Include a comprehensive Design Document for the new Rental Module in the Moto Delivery Manager system. This document outlines the module's objectives, system components, operation flow, architectural considerations, implementation details, and concludes with a summary of the module's impact on the system. The DesignDoc aligns with the latest system specifications and introduces asynchronous processing with AWS SQS, Restful API usage, and a clear depiction of the rental lifecycle management.

refs.: #10, #11 and #22
  • Loading branch information
chariondm committed Mar 22, 2024
1 parent 7eb369d commit d9c42df
Show file tree
Hide file tree
Showing 4 changed files with 154 additions and 0 deletions.
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,6 +110,7 @@ The `docker-setup` directory includes Docker Compose files necessary to configur
### Docs

- **[001-DriverLicensePhotoUpload](./docs/design-docs/001-DriverLicensePhotoUpload/DesignDoc001_DriverLicensePhotoUpload.md)**: Documentation detailing the driver's license photo upload feature, including API specifications, data flow diagrams, and integration details with AWS S3 for photo storage.
- **[002-RentalModule](./docs/design-docs/002-RentalModule/DesignDoc002_RentalModule.md)**: Documentation outlining the rental module's architecture, operation flow, and implementation details, including technology stack, key use cases, and architectural considerations.

This structure provides a solid foundation for the development, maintenance, and expansion of the `MotoDeliveryManager` system, allowing developers to contribute efficiently and the system to evolve in an organized and controlled manner.

Expand Down
124 changes: 124 additions & 0 deletions docs/design-docs/002-RentalModule/DesignDoc002_RentalModule.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
<a name="design-doc-top"></a>

# Design Document: Rental Module for Moto Delivery Manager

## Summary

This design document outlines the implementation of the Rental Module within the Moto Delivery Manager system. This module aims to manage the entire lifecycle of motorcycle rentals for delivery drivers, from initiation and retal plain selection to the final calculation of rental costs. Utilizing .NET 8 and C# within a clean and hexagonal architecture framework, the module ensures a seamless, efficient, and secure process for both rental management and financial obligations.

<details>
<summary>Table of Contents</summary>
<ul>
<li><a href="#diagram">Diagram</a></li>
<li><a href="#system-components">System Components</a></li>
<li><a href="#operation-flow">Operation Flow</a></li>
<li><a href="#architectural-considerations">Architectural Considerations</a></li>
<li><a href="#implementation-details">Implementation Details</a></li>
<li><a href="#conclusion">Conclusion</a></li>
</ul>
</details>

## Diagram
<p align="right">(<a href="#design-doc-top">back to top</a>)</p>

![C4 Model - Component Diagram](./rental-module-component-diagram.png)
Source: [Component Diagram](./rental-module-component-diagram.puml)

## System Components
<p align="right">(<a href="#design-doc-top">back to top</a>)</p>

- **Restful API**: Provides endpoints for rental management, including retal plans selection, motorcycle availability, and cost calculation.
- **Rental Agreement Worker**: Processes queued messages for rental agreement creation, verifying motorcycle availability and driver eligibility.
- **Database**: Stores information on motorcycles, drivers, rental agreements, and financial data. Utilizes Dapper for micro-ORM with PostgreSQL.
- **AWS SQS**: Queues messages for asynchronous processing, such as rental agreement creation. Ensures reliable and scalable communication between system components.

## Operation Flow
<p align="right">(<a href="#design-doc-top">back to top</a>)</p>

1. **Rental Initiation**:
- Delivery drivers select a rental plan through the Restful API, specifying the start date and expected end date, initiating the rental agreement process. The request is queued in AWS SQS for asynchronous processing.

2. **Motorcycle Availability and Driver Verification**:
- Queued messages are processed, verifying motorcycle availability and driver eligibility based on the rental plan selected. If the motorcycle is available and the driver meets the requirements, the rental agreement is created; otherwise, the driver is notified of the issue.

3. **Rental Agreement Creation**:
- A new rental agreement is created, detailing the motorcycle, rental plan, start date, and expected end date. The agreement is stored in the database for future reference, and the driver is notified of the successful rental initiation.

4. **Rental Termination and Cost Calculation**:
- The delivery driver indicates the end of the rental period, triggering the calculation of the final rental cost based on the rental plan and any additional fees incurred. The total cost is then presented to the driver for payment.

## Architectural Considerations
<p align="right">(<a href="#design-doc-top">back to top</a>)</p>

- Modular design within the system allows for clear separation of concerns, facilitating maintenance and future enhancements.
- The clean and hexagonal architecture ensures that core logic is decoupled from external interfaces, promoting flexibility and testability.
- Asynchronous processing with AWS SQS enhances system scalability and reliability, enabling efficient communication between system components.
- Database management with Dapper and PostgreSQL provides a robust and efficient solution for data storage and retrieval, ensuring data integrity and performance.

## Implementation Details
<p align="right">(<a href="#design-doc-top">back to top</a>)</p>

### Key Use Cases

- **List Rental Plans**: Delivery drivers can view available rental plans and select the one that best suits their needs.
- **Queue Rental Agreement Request**: The system validates the rental agreement request, ensuring that information provided is accurate and complete. If no issues are detected, the request is queued for processing. Otherwise, the driver is notified of the error.
- **Register Rental Agreement**: Delivery drivers can initiate a rental agreement by selecting a rental plan and specifying the start and end dates. The system verifies motorcycle availability and driver eligibility before creating the agreement.
- **Calculate Rental Termination Cost**: Upon indicating the end of the rental period, the system calculates the final rental cost based on the rental plan and any additional fees incurred. The total cost is then presented to the delivery driver for payment.


### Technology Stack

- Backend development with .NET 8 and C#.
- Restful API development using ASP.NET Core.
- Asynchronous processing with AWS SQS.
- Database management with PostgreSQL and Dapper micro-ORM.
- Unit testing with xUnit and Moq.

## Conclusion
<p align="right">(<a href="#design-doc-top">back to top</a>)</p>

The Rental Module is an essential component of the Moto Delivery Manager system, providing a seamless and efficient process for managing motorcycle rentals for delivery drivers. By leveraging .NET 8 and C# within a clean and hexagonal architecture framework, the module ensures a robust and scalable solution for rental management and financial obligations. With the integration of AWS SQS for asynchronous processing and PostgreSQL with Dapper for database management, the system delivers a reliable and performant solution for motorcycle rental operations.


## User Stories

### List Rental Plans

**As** a delivery driver,
**I want** to view available rental plans,
**So that** I can select the one that best suits my needs.

**Acceptance Criteria:**
- The system must provide a list of available rental plans.
- Each rental plan must include the duration and cost per day.
- The driver must be able to select a rental plan for further processing.


### Motorcycle Rental by Delivery Driver

**As** a delivery driver,
**I want** to rent a motorcycle for a specified period,
**So that** I can use it for my deliveries during that time.

**Acceptance Criteria:**
- The driver must be licensed in category A to rent a motorcycle.
- The rental agreement must specify the start, end date, and expected return time.
- The start of rental date always starts after the rental agreement is created.
- Only available motorcycles at the specified time can be rented.
- The system must calculate the total cost of the rental based on the rental plan and any additional fees incurred.
- The driver must receive a notification of the successful rental initiation and the final rental cost.

### Calculate Rental Termination Cost
**As** a delivery driver,
**I want** to know the total cost of my rental agreement upon termination,
**So that** I can make the necessary payment.

**Acceptance Criteria:**
- The system must calculate the total cost of the rental based on the rental plan and any additional fees incurred.
- If the motorcycle is returned early, apply a penalty fee on the unused days.
- For a 7-day plan, a 20% penalty is applied to the cost of unused days.
- For a 15-day plan, a 40% penalty is applied to the cost of unused days.
- For a 30-day plan, a 60% penalty is applied to the cost of unused days.
- If the motorcycle is returned late, additional fees must be applied.
- Additional days beyond the expected end date incur a charge of R$50,00 per extra day.

Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
@startuml rental-module-component-diagram
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Dynamic.puml

LAYOUT_TOP_DOWN()

AddElementTag("microservice", $shape=EightSidedShape(), $bgColor="CornflowerBlue", $fontColor="white", $legendText="Microservice")

Title "Rental Module Architecture"

Person(driver, "Delivery Driver", "A driver looking to rent a motorcycle for delivery tasks.")

System_Boundary(c1, "Rental Module") {
Container(mobile_app, "Native Mobile App", "React Native", "Allows drivers to request motorcycle rentals.")
Container(rest_api, "Delivery Driver Management API", "ASP.NET Core", "Provides endpoints for managing motorcycle rentals.", $tags = "microservice")
Container(consumer, "Rental Agreement Worker", ".NET Worker Service", "Processes queued messages for rental agreement creation.", $tags = "microservice")
ContainerQueue(queue, "AWS SQS", "Amazon SQS", "Stores rental requests for processing.")
ContainerDb(rental_db, "Moto Delivery Manager Database", "PostgreSQL & Dapper", "Stores information on motorcycles, drivers, and rental agreements.")
}

Rel_Right(driver, mobile_app, "Submits rental requests using", "HTTPS")
Rel_Down(mobile_app, rest_api, "Forwards rental requests to", "HTTPS")
Rel_Down(rest_api, queue, "Queues rental agreements in", "HTTPS")
Rel_Up(consumer, queue, "Processes rental agreements from", "HTTPS")
Rel(consumer, rental_db, "Writes rental agreements to", "JDBC")
Rel_Left(consumer, driver, "Notifies drivers of rental agreement status using", "Push Notifications")

SHOW_LEGEND()
@enduml

0 comments on commit d9c42df

Please sign in to comment.