add readme

.env-STUB

@@ -0,0 +1,25 @@
+# 1. Rename this file to '.env'
+# 2. Set up your data
+
+MYSQLDB_DATABASE=car_sharing_db
+
+MYSQLDB_USER=set_your_data_or_use_default-> root
+MYSQLDB_ROOT_PASSWORD=set_your_data_or_use_default-> root
+
+MYSQLDB_LOCAL_PORT=3307
+MYSQLDB_DOCKER_PORT=3306
+
+SPRING_LOCAL_PORT=8081
+SPRING_DOCKER_PORT=8080
+DEBUG_PORT=5005
+
+JWT_EXPIRATION_TIME=36000000000
+JWT_SECRET=set_your_favorite_very-very-very-long-secret-string
+
+STRIPE_APY_KEY=set_your_data
+STRIPE_SUCCESS_LINK=http://localhost:8080/api/payments/success?session_id={CHECKOUT_SESSION_ID}
+STRIPE_CANCEL_LINK=http://localhost:8080/api/payments/cancel?session_id={CHECKOUT_SESSION_ID}
+
+TELEGRAM_BOT_TOKEN=set_your_data
+TELEGRAM_BOT_USERNAME=set_your_data
+

README.md

@@ -1 +1,231 @@
-# car-sharing-app
+![car-sharing-app-02.png](misc/car-sharing-app-02.png)
+# Car-Sharing-App
+
+## Introduction
+The Car-Sharing-App is a Java-based web application built using the Spring Boot framework. 
+It serves as a comprehensive platform for managing users, cars, user roles, rentals, 
+notifications 
+and payments. This project was inspired by the need for an efficient and scalable solution to 
+streamline car sharing operations.
+
+## Technologies Used
+* **Spring Boot**: Is a powerful framework for building production-grade Java Applications.
+* **Spring Security:** Is a powerful and highly customizable authentication and access-control 
+  framework.
+* **Spring Data JPA:** Simplifies the implementation of JPA-based (Java Persistence API) repositories.
+* **Hibernate:** ORM tool for Java applications.
+* **MySQL:** A relational database management system.
+* **Liquibase:** Database schema migration tool.
+* **Docker:** Docker helps developers build, share, run, and verify applications in containers.
+* **Lombok:** A library to reduce boilerplate code in Java.
+* **MapStruct:** Implements mapping between DTOs and entity models.
+* **Swagger:** Tool for API documentation and testing.
+* **Stripe:** Payment system.
+* **Telegram Bots:** Framework for building Telegram Bots.
+
+## Functionality
+* **User registration, login, and role-based authorization allows different user levels to have 
+  appropriate access and capabilities within the service.**
+* **Multiple endpoints with user and admin access enables different functionalities and 
+  operations for both users and administrators.**
+* **Telegram bot notifications provides users with timely updates about the rental status, 
+  payments, and changes in the condition of the cars, ensuring that users are always informed.**
+* **Integration with Stripe payment service offers secure and reliable transactions for car 
+  rentals, improving the user experience and trust in the service.**
+* **Car booking and management enables users to conveniently book, use, and return rental cars, 
+  with all the necessary details tracked within the service.**
+
+### User Management
+* **User registration.**
+  ``` 
+  POST: /api/auth/registration
+  ``` 
+  Example of request body to register user:
+  ```json
+  {
+    "email": "john@mail.com",
+    "password": "password1234",
+    "repeatPassword": "password1234",
+    "firstName": "John",
+    "lastName": "Doe"
+  }
+  ```
+
+* **Secure user login with JWT-based authentication.**
+  ``` 
+  POST: /api/auth/login
+  ``` 
+
+  Example of request body to do log-in:
+  ```json
+  {
+    "email": "john@mail.com",
+    "password": "password1234"
+  }
+  ```
+
+  Example of response body after successful log-in. Use generated JWT token in the Authorization 
+  header in 
+  your requests.
+  ```json
+  {
+    "token": "eyJhbGci .... .... eoWbArcG7o-CNQO2Jo"
+  }
+  ```
+
+### Car Management
+* **Create, retrieve, update, and delete cars.**
+<br/><br/>
+Available endpoints for Car Management
+  *  with USER role
+  ``` 
+  GET: /api/cars
+  GET: /api/cars/{id} 
+  ```
+  *  with ADMIN role
+  ``` 
+  POST: /api/cars/
+  DELETE: /api/cars/{id}
+  PUT: /api/cars/{id}
+  ``` 
+
+  Example of request body to create new Car or edit existing one:
+  ```json
+  {
+    "model": "X5",
+    "brand": "BMW",
+    "type": "SUV",
+    "inventory": 10,
+    "dailyFee": 50.75 
+  }
+  ```
+
+### Rental Management
+* **Create, retrieve, search and return Rentals.**
+  <br/><br/>
+  Available endpoints for Rental Management
+  *  with USER role
+  ``` 
+  GET: /api/rentals/{id}
+  ``` 
+  *  with ADMIN role
+  ``` 
+  POST: /api/rentals
+  POST: /api/rentals/{id}/return
+  GET: /api/rentals/search
+  ``` 
+
+  Example of request body to create new Rental:
+  ```json
+  {
+    "rentalDate": "2024-03-07",
+    "returnDate": "2024-03-10",
+    "carId": 1,
+    "userId": 2
+  }
+  ```
+
+### Payment Management
+* **Create new payment.**
+* **Renew expired payment session.**
+* **Search payments.**
+  <br/><br/>
+Available endpoints for Payment Management
+  *  with USER role
+  ```
+  POST: /api/payments/renew
+  GET: /api/payments/search
+  ```
+  Example of request body to renew payment:
+  ```json
+  {
+    "paymentId": "12"
+  }
+  ```
+  *  with ADMIN role
+  ```
+  POST: /api/payments
+  POST: /api/payments/renew
+  GET: /api/payments/search
+  ```
+  Example url params to search payments:
+  ```json
+  http://localhost:8080/api/payments/search?user_id=3,7,21,9  
+  ```
+
+## Project Structure
+The project follows a modular structure:
+
+* **model**: Models representing the business logic entities.
+* **repository**: Spring Data JPA repositories.
+* **service**: Business logic.
+* **controller**: Controllers for handling HTTP requests.
+* **dto**: Data Transfer Objects to send between the client and server.
+* **mapper**: Mappers for mapping between DTOs and models.
+
+## Setup
+* Clone the repository to your local machine.
+* Create for free Stripe test account https://dashboard.stripe.com/test/dashboard. Get 
+  **STRIPE_APY_KEY**.
+* Create custom TelegramBot in Telegram. Use BotFather for it. Get **TELEGRAM_BOT_TOKEN** and 
+  **TELEGRAM_BOT_USERNAME**.
+* To run on local machine:
+  * set up **'username'** & **'password'** for your MySql in file **'developer.properties'**.
+  * edit **'application-stripe-STUB.properties'** file as needed with your **STRIPE_APY_KEY**.<br/>
+  Rename file to **'application-stripe.properties'**.
+  * edit **'application-telegram_bot-STUB.properties'** file as needed with your 
+    **TELEGRAM_BOT_TOKEN** and **TELEGRAM_BOT_USERNAME**. <br/>
+  * Rename file to **'application-telegram_bot.properties'**.
+  * compile and run project.
+* To run in Docker container:
+  * Install DockerDesktop.
+  * edit **'.env-STUB'** file as needed with your **MYSQLDB_USER**, **MYSQLDB_ROOT_PASSWORD**, 
+    **STRIPE_APY_KEY**, **TELEGRAM_BOT_TOKEN** and **TELEGRAM_BOT_USERNAME**. <br/>
+    Rename file to **'.env'**.
+  * Compile project.
+  * Start DockerDesktop.
+  * Run project by running the command 'docker compose up' in project directory.
+
+To access Swagger documentation use link: http://localhost:8080/swagger-ui/index.html
+The API uses JWT (JSON Web Tokens) for authentication.
+
+To access protected endpoints first register and login to api, then include the generated JWT 
+token in the Authorization header of your requests.
+
+After the first launch, three user accounts are registered in the application, you can use them:
+  ```json
+  {
+    "email": "manager@mail.com",
+    "password": "12345678",
+    "firstName": "Manager",
+    "lastName": "Cool"
+  },
+  {
+    "email": "john@mail.com",
+    "password": "12345678",
+    "firstName": "John",
+    "lastName": "Doe"
+  },
+  {
+    "email": "tom@mail.com",
+    "password": "12345678",
+    "firstName": "Tom",
+    "lastName": "Foo"
+  }
+  ```
+
+## Challenges and Solutions
+* Challenge: Implementing secure user authentication.<br/>
+Solution: Utilized Spring Security and JWT for a robust authentication mechanism.
+
+* Challenge: Efficiently managing rentals, payment processing and user notification.<br/>
+Solution: Designed CarService, PaymentService to handle operations with cars and payment 
+management. Designed Telegram API based user notification service.  
+
+## Postman
+For detailed API usage, you can use provided requests samples.
+
+## Conclusion
+Car-Sharing-App is an innovative RESTful web application tailored to address car rental needs.
+Developed using Spring Boot and Java, the application strictly follows the principles of the REST architectural style,
+ensuring stateless communication between clients and the server.