Adjust how it works

docs/services/etherpad/How it works.md

@@ -1,20 +1,67 @@
 # How it works
 
-## Session managment
+## Configuration
+- ETHERPAD_COOKIE__EXPIRES_SECONDS - time in seconds after which a session expires
+- ETHERPAD_ETHERPAD_COOKIE_RELEASE_THRESHOLD - time in seconds after which a session is not returned to the user
+- ETHERPAD_API_KEY - api key for etherpad
+- ETHERPAD_URI - uri of etherpad api
+- ETHERPAD_API_PATH - path to etherpad api
+- ETHERPAD_BASE_URL - base url of etherpad
+- ETHERPAD__PAD_PATH
+- ETHERPAD__PAD_URI
+- ETHERPAD__NEW_DOMAIN
+- ETHERPAD__OLD_DOMAIN
+
+## Creating and Opening an Etherpad Element on a Column Board
+
+![Requests of etherpad creation](how_it_works.png)
+
+### Creating an Etherpad Element
+1. The user initiates the process by creating an Etherpad element on a column board.
+2. Vue then sends a request to the board module in the Schulcloud server for a new Etherpad element.
+3. The server responds by returning an Etherpad element which is then displayed on the board.
+
+### Interacting with the Etherpad Element
+1. When the user clicks on the Etherpad element, the Vue client sends a request to the collaborative text editor module in the Schulcloud server for a new Etherpad.
+2. The Schulcloud server is capable of creating Etherpads based on parent types. The parent type is further used for handling authorisation of the etherpad. Currently, the only parent type is a column board element.
+
+### Grouping and Creating Etherpads
+1. The Schulcloud server first creates a group that clusters several Etherpads together. Each group shares a session and a new group is created for every column board element. This requires sending a request to the Etherpad server.
+2. Once the group is created, the server can send a request to create an Etherpad within that group.
+
+### Session Creation and Cookie Setting
+1. For session creation, the server first needs to request an Etherpad author and then the session for that author.
+2. With that session, the server can set a session cookie in the client's browser and return the Etherpad URL to Vue.
 
-### Column and List Board
-An etherpad session is created for every click on the etherpad element. This session expires after the amount of time defined by `ETHERPAD_COOKIE__EXPIRES_SECONDS`. This means that a user will loose access to the pad after that time period is expired. Losing access means that after interaction with the pad an english non translated message "You do not have permission to access this pad." will be shown instead of the pad. If a user is not interacting with the pad he will be able to see the content also after the period of `ETHERPAD_COOKIE__EXPIRES_SECONDS`.
+### Opening the Etherpad
+In the final step, Vue opens the Etherpad URL in a new browser tab, enabling the user to interact directly with the Etherpad. It's important to note that the Etherpad client interface displayed to the user is served by the Etherpad server, and as such, it is not a part of our own codebase.
+
+## Etherpad Adapter
+For the communication with the Etherpad server, the Schulcloud server uses an adapter. This adapter is responsible for handling all requests to the Etherpad server and ensuring that the correct data is sent and received. This adapter uses a client that is generated by open api generator. Client generation can be triggered with `generate-client:etherpad` and should be executed after update of etherpad server.
+
+## Authentication
+The authentication process in our system works via a token. This token is sent with each request as a parameter to ensure secure communication.
+
+The token is defined by the `ETHERPAD_API_KEY` environment variable. This variable holds the key used for authentication, ensuring that only authorized requests are processed.
+
+In the Schulcloud server, this API key is passed to the etherpad adapter on its initialization in the collaborative text editor module.
+
+## Session managment
 
-If a user clicks on the etherpad element for the second time, a session that already exists for this element might be returned. If the old session or a new one is created depends on the env var settings. `ETHERPAD_ETHERPAD_COOKIE_RELEASE_THRESHOLD` defines the amount of time a session must still be valid to be delivered to the user. Currenty in production `ETHERPAD_ETHERPAD_COOKIE_RELEASE_THRESHOLD` and 
-`ETHERPAD_COOKIE__EXPIRES_SECONDS` are set to the same value of 2 hours. With that setting for every click on an etherpad element a new session is created.
+### Etherpad Session Creation and Expiration
+Each interaction with an Etherpad element initiates the creation of a new session. The lifespan of this session is determined by the ETHERPAD_COOKIE__EXPIRES_SECONDS environment variable. Once this time period elapses, the user loses access to the pad. This loss of access is indicated by the display of a non-translated English message: "You do not have permission to access this pad." However, even after the session expires, users can still view the pad content as long as they do not interact with it.
 
-There is no such thing as an automatic session renewal on interaction. Etherpad provides the config variable COOKIE_SESSION_REFRESH_INTERVAL which defines the amount of time after a session of a user gets automatically renewed in an open tab. Currently this is not set and so the default of 1 day has no influence because this value is greater than ETHERPAD_COOKIE__EXPIRES_SECONDS. So with that setting sessions are not automatically renewed.
+### Session Reuse
+Upon subsequent interactions with the Etherpad element, an existing session for that element may be reused. Whether an old session is reused or a new one is created depends on the environment variable settings. The `ETHERPAD_COOKIE_RELEASE_THRESHOLD` variable determines the remaining validity period of a session for it to be delivered to the user. In the current production environment, both `ETHERPAD_COOKIE_RELEASE_THRESHOLD` and `ETHERPAD_COOKIE__EXPIRES_SECONDS` are set to the same value of 2 hours. This configuration results in the creation of a new session for each interaction with an Etherpad element.
 
-When user logsout out of schulcloud all sessions are removed and user loses access to the pads on interaction. (Please see description above)
+### Session Renewal
+Currently there is no automatic session renewal upon interaction. Etherpad provides the `COOKIE_SESSION_REFRESH_INTERVAL` configuration variable, which specifies the time period after which a user's session is automatically renewed in an open tab. However, this variable is currently unset, and the default value of 1 day has no effect because it exceeds the `ETHERPAD_COOKIE__EXPIRES_SECONDS` value. Therefore, sessions are not automatically renewed.
 
-Currently on schulcloud user autologout, etherpad sessions are not removed automatically. But as long ETHERPAD_COOKIE__EXPIRES_SECONDS and JWT_TIMEOUT_SECONDS are set to the same value, all sessions should theoretically be invalid after autologout.
+### Session Removal
+When a user logs out of Schulcloud, all sessions are terminated, and the user loses access to the pads upon interaction. However, Etherpad sessions are not automatically removed upon user auto-logout in Schulcloud. As long as `ETHERPAD_COOKIE__EXPIRES_SECONDS` and `JWT_TIMEOUT_SECONDS` are set to the same value, all sessions should theoretically become invalid after auto-logout.
 
-A cookie with the name sessionID is stored for every session. Cookies are not programmatically removed after ETHERPAD_COOKIE__EXPIRES_SECONDS or schulcloud logout.
+### Cookie Management
+A cookie named sessionID is stored for each session. These cookies are not programmatically removed after the `ETHERPAD_COOKIE__EXPIRES_SECONDS` period or upon Schulcloud logout.
 
 ### Legacy Topics