From 8a7b1700868e6c849e5d4685c8b2967c654bbbc3 Mon Sep 17 00:00:00 2001
From: ccornu <ccornu@takima.fr>
Date: Tue, 11 Feb 2025 12:10:18 +0100
Subject: [PATCH] feat: update README.md
---
README.md | 166 ++++++++++++++++++++++++++++++++++++++++++------------
1 file changed, 131 insertions(+), 35 deletions(-)
diff --git a/README.md b/README.md
index afe3e09..354a2ca 100644
--- a/README.md
+++ b/README.md
@@ -1,63 +1,159 @@
# Tournament API
-## Initalisation
+## Subject
+
+The goal of this project was to design a REST API to manage players ranking during a tournament.
+
+### Functional requirements:
+
+The API must be able to:
+
+- Add a player by its pseudo
+- Update player points
+- Retrieve player info
+- Retrieve players ranking
+- Delete all players when tournament is over
+
+### Technical requirements :
+
+- Use of **Kotlin**
+- Use of asynchronous framework **Ktor**
+- Use of dependency injection framework **Koin**
+- Use of **DynamoDB** as database
+
+## Initialization
### Pre-requisites
-You need to have Docker and AWS CLI installed on your machine
+Ensure you have the following tools installed on your machine:
+
+- [Docker](https://www.docker.com/)
+- [AWS CLI](https://aws.amazon.com/cli/)
-### How to start the database
+### Starting the database
-In `docker/db` folder, run the following command:
+Navigate to the `docker/db` directory and run the following command to start the local database:
```bash
docker compose up -d
```
-### How to start the API
+### Starting the API
-Place yourself at root and start
+1. Make sure that the database is up by executing
```bash
-docker compose up -d
+docker ps
```
-// or with cmd
+Look for the `dynamodb-local` container in the list of running services
+
+2. From the root directory, start the API using:
+
+```bash
+./gradlew run
+```
+
+---
## Available endpoints
-## Technical choices
+Below is a list of available API endpoints and their usage:
+
+| Endpoint goal | HTTP verb | URL | Body | Response |
+|-------------------------------|-----------|------------------------|-------------------------------------------|--------------------------------------------------------------------------------------------------------------|
+| Create new player | POST | /players | { "pseudo" : "John" } | { "pseudo" : "John", "pointsNumber": 0 } |
+| Update players points | PUT | /players | { "pseudo" : "John", "pointsNumber": 15 } | { "pseudo" : "John", "pointsNumber": 15 } |
+| Get player info by its pseudo | GET | /players?pseudo="John" | | { "pseudo" : "John", "pointsNumber": 15, rank: 1 } |
+| Get players ranking | GET | /players/ranking | | [{ "pseudo" : "John", "pointsNumber": 15, rank : 1 }, { "pseudo" : "Francis", "pointsNumber": 0, rank : 2 }] |
+| Delete all players | DELETE | /players | | |
+
+---
+
+## Testing
+
+### 1. Run
+
+To run all tests, run the following command:
+
+```bash
+./gradlew clean test --info
+```
+
+### 2. Coverage
+
+We tried to have the best coverage possible
+
+---
+
+## Preparing for Production
+
+To deploy this application in a production environment, there are several key areas to address:
+
+### 1. Security management :
+
+**Database**
+
+- Currently, a local database with dummy logging is used. For production, we can leverage AWS DynamoDB in the cloud by
+ connecting our API to a live DynamoDB instance.
+- To do so :
+ - We can externalize DynamoDBConfiguration values (e.g.: set them as environment variables)
+ - We can create CI to load the secrets when deploying the application
+
+**Endpoints**
+
+- All API endpoints are currently open to public access. For secure access, implement authentication using the
+ `ktor-server-auth` plugin .
+
+- We currently enabled our API being requested from any host (look for the CORS configuration). When releasing to
+ production environment, we would want to control who can access our API by declaring hosts by environment variables.
+
+- We have no access management. We could use an IAM solution, such as Keycloak, that we can connect to our API to handle
+ access management.
+
+- Additionally, we can use an API Gateway (e.g., Kong) to handle requests and manage security for our API.
+
+### 2. Database and table creation
+
+- Currently, table creation is handled at application startup. The logic is implemented to execute the migration only if
+ needed.
+- To correctly handle migrations, it could be useful to handle it through a migration tool, like Liquibase.
+- Considering that you are using Terraform at Betclic, it could also be a way to set up the database. Indeed, Terraform
+ plays nicely with DynamoDB to manage the setup of table and to establish connections with AWS.
+
+### 3. CI/CD Pipelines
+
+Implementing CI/CD pipelines is essential for secure deployment. We can set up the following jobs in your repository:
+
+- `install dependencies`: Cache reusable dependencies for following jobs.
+- `build`: Ensure the application compiles successfully.
+- `test`: Run all application tests to validate functionality.
+- `package`: Prepare the application for deployment.
+- `deploy`: Create a manual, clickable job to deploy the application to the desired environment
+
+### 4. GreenIT Considerations
-- I chose ... because ...
+- This application is primarily used during tournaments to calculate points and rankings.
+- To reduce unnecessary resource consumption, we could set up infrastructure jobs to shut down the API when not in use
+ and restart it when needed.
-## I want to ensure tests are running
+## Next technical steps
-## Left to do
+Our API fulfills the requirements stated in the subject.
-- [x] setup dynamo DB
-- [x] faire la connexion avec Dynamo
-- 1er endpoint
- - [x] créer l'entité joueur
- - [x] créer le repo et le connecter à la BD
- - [x] tester unitairement le service
- - [ ] tester l'intégration complète
- - [x] endpoint fonctionnel pour l'ajout d'un joueur avec test
- - [ ] tests d'intégration
- - [ ] tests unitaires
-- [x] tous les endpoints demandés
-- [ ] gestion de la sécurité
+However, we could still improve this application in a technical way.
-Dans l'ordre :
+For example, we could add checkstyle with linters, by using **ktfmt** for example.
-- Amélioration du fonctionnel
- - Routes factorisées
- - DTO
- - Appels à la BD
-- Amélioration des tests
-- Amélioration de la sécurité
-- Déploiement en prod serein
+We could also use **open-api** in order to help users to explore our endpoints, and facilitate their comprehension of
+this API.
-## Going further
+Concurrency is currently not handled by the API : if 2 users try to update the same player's points at the same time,
+the update could return inconsistent data. We could for example use a versioning on player entity to set it up.
-- Database migration tool
-- ...
\ No newline at end of file
+- change score computing
+- add checkstyle
+- ...
+- open api
+- Itest
+ regarder les contraintes
\ No newline at end of file
--
GitLab