docs: improve developer docs

1 files changed, 37 insertions, 13 deletions

diff --git a/share/man/DEVELOPMENT.md b/share/man/DEVELOPMENT.md
index 3e21bf7..f8a00bb 100644
--- a/share/man/DEVELOPMENT.md
+++ b/share/man/DEVELOPMENT.md
@@ -1,13 +1,18 @@
 # Development
 
-Sparkle uses [Envoy proxy](https://www.envoyproxy.io/) to redirect
-unauthenticated requests to the GitLab Identity Provider and then retrieves an
-`id_token`, `access_token` and `refresh_token` using an OpenID Connect workflow
-to inject these tokens as cookies before forwarding the request to Sparkle.
+Sparkle uses [Envoy Proxy](https://www.envoyproxy.io/) to manage authentication
+via GitLab's Identity Provider (IdP). When a user makes a request without valid
+authentication cookies, Envoy redirects the request to the IdP. It then completes
+an OpenID Connect (OIDC) flow to obtain an `id_token`, `access_token`, and
+`refresh_token`, sets them as cookies, and forwards the request to Sparkle.
 
-This flow allows Sparkle to focus on application logic without needing to
-directly manage session cookies, exchange a refresh token for a new access token
-and directly access the `client_id` and `client_secret`.
+This architecture enables Sparkle to focus solely on application logic, without needing to:
+
+* Handle session cookies manually,
+* Exchange refresh tokens for new access tokens, or
+* Access client credentials like `client_id` or `client_secret` directly.
+
+## Request Flow Overview
 
 ```plaintext
 +-------------+           +---------------+                  +-----------------+                +-------+
@@ -37,14 +42,34 @@ and directly access the `client_id` and `client_secret`.
     |<--- Final Response --------|                                    |                             |
 ```
 
-Configuration is injected into envoy and sparkle via environment variables.
-Please see the [Envoy installation documentation](https://www.envoyproxy.io/docs/envoy/latest/start/install)
-to install the appropriate version of Envoy on your operating system. The version
-of envoy that you need to install can be found in the `Dockerfile` in the root
-of this repository.
+## Configuration
+
+Both Envoy and Sparkle are configured via environment variables. You can copy the
+`.env` file to `.env.local` and fill in the required values:
+
+```bash
+cp .env .env.local
+```
+
+The following environment variables must be defined:
+
+| Variable Name          | Description                                      |
+| ---------------------- | ------------------------------------------------ |
+| `APP_ENV`              | Sparkle environment (default: `development`)     |
+| `BIND_ADDR`            | Address Sparkle listens on (default: `:8080`)    |
+| `OAUTH_CLIENT_ID`      | The client ID registered with GitLab IdP         |
+| `OAUTH_CLIENT_SECRET`  | The corresponding client secret                  |
+| `OAUTH_REDIRECT_URL`   | Redirect URI configured in your GitLab OAuth app |
+| `OIDC_ISSUER`          | The issuer URL (e.g., `http://gdk.test:3000`)    |
+
+You can refer to the `Dockerfile` in the root of this repository to determine the
+exact version of Envoy required. To install Envoy locally, follow the [official
+installation guide](https://www.envoyproxy.io/docs/envoy/latest/start/install).
 
 ## Usage
 
+You can run Sparkle and Envoy either natively or in Docker:
+
 * **Run Sparkle + Envoy on the host machine:**
 
   ```bash
@@ -56,4 +81,3 @@ of this repository.
   ```bash
   $ make run-image
   ```
-