diff --git a/docs/ecolyo/functionalities/challenge.md b/docs/ecolyo/functionalities/challenge.md
index 2cf4828cc8193561d1d7b006f4c3768552ec70c9..28ee8f2ebbf9cc26ad76dc41f87c97a48b4e1669 100644
--- a/docs/ecolyo/functionalities/challenge.md
+++ b/docs/ecolyo/functionalities/challenge.md
@@ -9,20 +9,109 @@ This section explain all the functionnalities in the challenge part
## Duel
-### On launch
+### On launch
- In order to find a valid reference period we search for a period which is defined by the duel duration.
- We check the most recent period first if it's complete and then we go farther and farther in the time if the ones before got missing values.
- We also define a threshold for a maximum old period (6 months for the moment). If the thresold is reached and no valid period was found, we alert the user that he can't lunch the duel and have to wait before he can retry this process.
+In order to find a valid reference period we search for a period which is defined by the duel duration.
+ We check the most recent period first if it's complete and then we go farther and farther in the time if the ones before got missing values.
+ We also define a threshold for a maximum old period (6 months for the moment). If the thresold is reached and no valid period was found, we alert the user that he can't lunch the duel and have to wait before he can retry this process.
-### On going
+### On going
- Every time the user go into the duel mode, we are checking if the duel is finished.
- if (actualDate - startDate) > duelDuration, the duel is done.
+Every time the user go into the duel mode, we are checking if the duel is finished.
+if (actualDate - startDate) > duelDuration, the duel is done.
-### On finish
+### On finish
- Once the state of the duel is set to DONE, we save the user result and determine if he wins (userComsumption < threshold of the reference period) or if he loses. Then the user sees his earned badge.
+Once the state of the duel is set to DONE, we save the user result and determine if he wins (userComsumption < threshold of the reference period) or if he loses. Then the user sees his earned badge.
+## Challenge data managment
+We handle data storage according to the following process :
+The folder /db contains all the JSON entities that are directly stored in the couchDB during the initialization process that is executed in the splash screen. They are stored under their related doctype.
+
+## Initialization and Updating
+
+During the initialization process, we store a hash for each dataEntity that is likely to be changed or updated. The hash is stored in the userProfile.
+
+```json
+[
+ {
+ "ecogestureHash": "",
+ "challengeHash": "",
+ "duelHash": "",
+ "isFirstConnection": true,
+ "haveSeenFavoriteModal": false,
+ "haveSeenOldFluidModal": false,
+ "haveSeenLastReport": true,
+ "sendReportNotification": false,
+ "monthlyReportDate": "0000-01-01T00:00:00.000Z"
+ }
+]
+```
+
+This way, once the initialization is launched, we compare the hash we have in the current userProfile with the one generated from the entity located in /db folder, and if they are different we update the couchDB with the new data.
+
+### dataEntity vs userData
+
+In the project, you'll see two versions for the same data. The dataEntity (quizEntity, challengeEntity, ...) is the data stored in the db folder and in the couchDB. These data are only edited in the couchDB when we update a challenge/quiz/duel or add a new one.
+
+The userData (userChallenge, userQuiz...) is created from the entity and extended with user's data, such as his progress, his consumption data, goals, fails etc.
+
+Using this 2 structures allows us to keep user's datas when we'll update the application, by editing just the entities.
+
+## Challenges
+
+We can find the file challengeEntity.json in the /db folder. This file contains an array of challenges, and each of them includes relationships to duels, quiz, missions and actions.
+
+### Relationships
+
+Relationships is a functionality made by cozy, they are built with the name of the relation, containing a "data" object, itself containing the id of the related item and its doctype "\_type". Using this allows us to reduce the size of the stored items and increase readability.
+
+You can see more on [cozy documentation](https://docs.cozy.io/en/cozy-doctypes/docs/io.cozy.apps.suggestions/#relationships).
+
+```json
+"relationships": {
+ "quiz": {
+ "data": { "_id": "QUIZ001", "_type": "com.grandlyon.ecolyo.quiz" }
+ },
+ "duel": {
+ "data": { "_id": "DUEL001", "_type": "com.grandlyon.ecolyo.duel" }
+ }
+ }
+```
+
+### UserData creation
+
+Once a user launch a challenge in the Ecolyo app, we create a userChallenge and store it in the couchDB under the doctype '**com.grandlyon.ecolyo.userchallenge'.** During this process, the objects related to the challenge (quiz, duel, mission, action) will be be converted to an user version which contains informations about the user progress, the fluids connected and so on. So we have now a userChallenge that contains a userQuiz, a userDuel, etc. instead of relations.
+
+To illustrate this, let's show the conversion of quizEntity to userQuiz :
+
+```jsx
+DuelEntity {
+ id: string
+ title: string
+ description: string
+ duration: Duration
+}
+```
+
+Becomes :
+
+```jsx
+UserQuiz {
+ id: string
+ title: string
+ description: string
+ duration: Duration
+ threshold: number
+ state: UserDuelState
+ startDate: string | null
+ fluidTypes: FluidType[]
+ userConsumption: number
+}
+```
+
+### Data managment schema
+
+
diff --git a/docs/img/challengeFlow.png b/docs/img/challengeFlow.png
new file mode 100644
index 0000000000000000000000000000000000000000..d5ab6ec40a785d9cfe512abaacc373438b07f932
Binary files /dev/null and b/docs/img/challengeFlow.png differ