📝 Add some initial documentation (#1)

Co-authored-by: Alexis DRAI <alexis.drai@etu.uca.fr>
Reviewed-on: alexis.drai/AD_MongoDB#1

README.md

@@ -1,60 +1,57 @@
-# pokemong
+# PoKeMoNg
 
-This project uses Quarkus, the Supersonic Subatomic Java Framework.
+A [Quarkus](https://quarkus.io/) / [MongoDB](https://mongodb.com/) app for educational purposes.
 
-If you want to learn more about Quarkus, please visit its website: https://quarkus.io/ .
+Instructions [here](https://clientserveur-courses.clubinfo-clermont.fr/Notation.html).
 
-## Running the application in dev mode
+## About
 
-You can run your application in dev mode that enables live coding using:
-```shell script
-./gradlew quarkusDev
-```
+This application is a RESTful service designed to emulate a 'Pokemong' management system. It allows users to perform
+CRUD operations on 'Pokemongs'.
 
-> **_NOTE:_**  Quarkus now ships with a Dev UI, which is available in dev mode only at http://localhost:8080/q/dev/.
+The application is developed using the [Quarkus](https://quarkus.io/) framework and uses [MongoDB](https://mongodb.com/)
+as its database.
 
-## Packaging and running the application
+## Prep steps
 
-The application can be packaged using:
-```shell script
-./gradlew build
-```
-It produces the `quarkus-run.jar` file in the `build/quarkus-app/` directory.
-Be aware that it’s not an _über-jar_ as the dependencies are copied into the `build/quarkus-app/lib/` directory.
+### ♨️ Java version
 
-The application is now runnable using `java -jar build/quarkus-app/quarkus-run.jar`.
+* #### Run locally from terminal
 
-If you want to build an _über-jar_, execute the following command:
-```shell script
-./gradlew build -Dquarkus.package.type=uber-jar
-```
+This project should be configured to run on `JDK 17`. That means you should have `JDK 17` installed locally, and
+accessible to `Gradle`.
 
-The application, packaged as an _über-jar_, is now runnable using `java -jar build/*-runner.jar`.
+* #### Run from IDE
 
-## Creating a native executable
+Moreover, if you're planning to run this app directly from an IDE like IntelliJ, make sure to update the `Gradle JVM`
+setting to use `JDK 17` for `Gradle` tasks
 
-You can create a native executable using: 
-```shell script
-./gradlew build -Dquarkus.package.type=native
-```
+### 🔐 Database connection
 
-Or, if you don't have GraalVM installed, you can run the native executable build in a container using: 
-```shell script
-./gradlew build -Dquarkus.package.type=native -Dquarkus.native.container-build=true
+Note that the DB connection properties are not included -- your `src/main/resources/application.properties` should look
+like this :
+
+```yml
+quarkus.mongodb.connection-string=mongodb+srv://<username>:<password>@<cluster>.<node>.mongodb.net
+quarkus.mongodb.database=<database>
 ```
 
-You can then execute your native executable with: `./build/pokemong-1.0-SNAPSHOT-runner`
+#### If you are the corrector
 
-If you want to learn more about building native executables, please consult https://quarkus.io/guides/gradle-tooling.
+To be able to use this app, update `application.properties` with the provided database secrets.
 
-## Related Guides
+If none were provided, that was a mistake. Sorry. Please request them to the owner of this repo.
 
-- MongoDB client ([guide](https://quarkus.io/guides/mongodb)): Connect to MongoDB in either imperative or reactive style
+#### If you are not the corrector
 
-## Provided Code
+To be able to use this app, first create a MongoDB database, either locally or on
+their [Atlas Cloud](https://cloud.mongodb.com/), then update `application.properties` with your database secrets. You
+may want to look up the nice [MongoDB official documentation](https://www.mongodb.com/docs/) if you get stuck.
 
-### RESTEasy Reactive
+## Running the application in dev mode
 
-Easily start your Reactive RESTful Web Services
+You can run the application in dev mode using:
 
-[Related guide section...](https://quarkus.io/guides/getting-started-reactive#reactive-jax-rs-resources)
+```shell script
+./gradlew quarkusDev
+```

docs/DB.md

@@ -0,0 +1,75 @@
+# About the database schema
+
+## Collections
+
+### trainers collection
+
+* _id: ObjectId
+* name: string
+    * (_indexed_: would be queried often in a dashboard situation)
+* dob: date
+* wins: int
+* losses: int
+* past_opponents: array of ObjectId (references to other trainers)
+    * (_indexed_: reflexivity would make deep queries quite slow, so it seems worthwhile)
+* pokemongs: array of ObjectId (references to owned pokemongs) + denormalizing on "nickname" and "species"
+    * (_indexed_: to improve speed when querying non-denormalized fields)
+
+### pokemongs collection
+
+* _id: ObjectId
+* nickname: string
+* dob: date
+* level: int
+* pokedex_id: int
+* evo_stage: int
+    * (_indexed_: "species" is calculated as evo_track[evo_stage], and would be queried often)
+* evo_track: array of strings (therefore "species" is evo_track[evo_stage], and "evo_base" is evo_track[0])
+    * (_indexed_: "species" is calculated as evo_track[evo_stage], and xould be queried often)
+* is_mega_evolved: boolean
+    * **polymorphic**: this field is only here for mature_pokemongs, i.e. pokemongs who have reached their last evo_stage
+* trainer: ObjectId? (reference to a trainer) (but can be "wild" instead, if ref is null)
+    * (_indexed_: could be queried often in a dashboard situation)
+* types: embedded type, or array of embedded types
+    * (_indexed_: would be queried often in a dashboard situation)
+* move_set: array of ObjectId (references to known moves) + denormalizing on "name"
+
+### moves collection
+
+* _id: ObjectId
+* name: string
+    * (_indexed_: would be queried often in a dashboard situation)
+* category: string (can be "physical", "special", or "status")
+* pp: int
+* power: int
+    * (_indexed_: would be used often in sorts, in a dashboard situation)
+* accuracy: int
+* type: embedded type
+    * (_indexed_: would be queried often in a dashboard situation)
+
+
+### types collection
+
+* _id: ObjectId
+* name: string
+    * (_indexed_: would be queried often in a dashboard situation)
+* weak_against: array of strings (denormalized type names)
+* effective_against: array of strings (denormalized type names)
+
+## Relationships
+
+* trainers.past_opponents: one-to-many and reflexive
+    * => referencing
+* trainers.pokemongs: one-to-many
+    * => referencing + denormalizing on "nickname" and "species"
+* pokemongs.trainer: many-to-one
+    * => referencing
+* pokemongs.types: one-to-few [1;2] but will also need to be queried independently
+    * => denormalizing on all fields
+* pokemongs.move_set: one-to-few [1;4] but will also need to be queried independently
+    * => referencing + denormalizing on  "name"
+* moves.type: one-to-one [1;1] but will also need to be queried independently
+    * => denormalizing on all fields
+* types.weak_against & types.effective_against: one-to-few but reflexive
+    * => denormalizing on "name"
+