📝 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,90 @@
-# pokemong
+# PoKeMoNg
 
-This project uses Quarkus, the Supersonic Subatomic Java Framework.
+This is 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 are [here](https://clientserveur-courses.clubinfo-clermont.fr/Notation.html) for reference.
 
-## Running the application in dev mode
+## About
 
-You can run your application in dev mode that enables live coding using:
-```shell script
-./gradlew quarkusDev
-```
+A "Pokemong" is a playful term for a `MongoDB` pocket monster.
 
-> **_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 framework and uses `MongoDB` as its database.
 
-## Packaging and running the application
+This application is a RESTful service designed to emulate a basic Pokemong management system. It allows users to perform
+CRUD operations on Pokemongs, trainers, moves, and types.
 
-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.
+<details><summary>🗂️ See the DCM</summary>
+<img src="./docs/mcd.png" alt="Data Concept Model" title="Data Concept Model">
 
-The application is now runnable using `java -jar build/quarkus-app/quarkus-run.jar`.
+</details>
 
-If you want to build an _über-jar_, execute the following command:
-```shell script
-./gradlew build -Dquarkus.package.type=uber-jar
-```
+<details><summary>🧬 See the UML Class diagram</summary>
+<img src="./docs/nosql_uml.png" alt="UML Class Diagram" title="UML Class Diagram">
 
-The application, packaged as an _über-jar_, is now runnable using `java -jar build/*-runner.jar`.
+</details>
 
-## Creating a native executable
+## Prep steps
 
-You can create a native executable using: 
-```shell script
-./gradlew build -Dquarkus.package.type=native
-```
+### ♨️ Java version
+
+This project is set up to use `Java 17`.
+
+Your build will fail if the version of `Java` that your build tools are using does not match that.
+
+<details><summary>💻 Run from command line</summary>
+
+You should have `JDK 17` installed locally, and accessible to `Gradle`.
+
+That may involve updating your `JAVA_HOME` and `Path` environment variables.
+
+</details>
+
+<details><summary>🛠️ Run from an IDE</summary>
+
+If you're planning to run this app directly from an IDE like IntelliJ, make sure to update any `Gradle JVM` (or similar)
+settings to use `JDK 17` for `Gradle` tasks
+
+</details>
+
+### 🔐 Database connection
+
+Note that the DB connection properties are not included -- your `src/main/resources/application.properties` should look
+like this :
 
-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
+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`
+<details><summary>🏫 If you are the corrector</summary>
+
+To be able to use this app, update `application.properties` with the provided database secrets.
+
+If none were provided, that was a mistake. Sorry. Please request them to the owner of this repo.
 
-If you want to learn more about building native executables, please consult https://quarkus.io/guides/gradle-tooling.
+</details> 
 
-## Related Guides
+<details><summary>👥 If you are another user or developer</summary>
 
-- MongoDB client ([guide](https://quarkus.io/guides/mongodb)): Connect to MongoDB in either imperative or reactive style
+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.
 
-## Provided Code
+You may want to look up the nice [MongoDB official documentation](https://www.mongodb.com/docs/) if you get stuck.
 
-### RESTEasy Reactive
+</details> 
 
-Easily start your Reactive RESTful Web Services
+### 🩺 API testing tool
 
-[Related guide section...](https://quarkus.io/guides/getting-started-reactive#reactive-jax-rs-resources)
+It is recommended to use an API testing tool such as [Postman](https://www.postman.com/)
+or [Insomnia](https://insomnia.rest/), while playing around with this app.
+
+Moving forward, the front end part of this app -- a different project -- might also come into play for trying out this
+API.
+
+## Running the application in dev mode
+
+You can run the application in dev mode using:
+
+```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"
+