adds information about configuration to documentation

src/pages/concepts/configuration/index.mdx

@@ -6,34 +6,164 @@ import { Callout } from 'nextra/components'
   You can find the configuration file of the official instance [here →](https://gitlab.opencode.de/open-code/badgebackend/badge-api/-/blob/main/.badge-api.yaml)
 </Callout>
 
-The `.badge-api.yaml` configuration file defines a list of badges, their levels and their criteria. The file is structured as follows.
 
-Find an overview of the implemented checks [here →](/concepts/implemented-checks).<br />
-Details about manual checks can be found [here →](/concepts/configuration/manual-checks).
 
-```yaml filename=".badge-api.yaml" copy
+The badge api is configured using a yaml configuration file with the name `.badge-api.yaml`. The program looks for this file in the current working directory and inside `/etc/badge-api/`.
+
+The configuration file consists of several key sections, including:
+
+- **gitClients**: Contains the configuration for connecting to git providers.
+- **badges**: Defines the badges, their levels, checks, and associated thresholds.
+- **personalEmailDomains**: A list of personal email domains (required by the elephant and bus factor check).
+
+### Git Clients Configuration
+
+The `gitClients` section defines how the Badge API connects to GitLab repositories.
+
+```yaml
+gitClients:
+  - baseUrl: <git_server_url>
+    tokenFile: <path_to_token_file>
+    type: <git_server_type>
+    maxRequestsPerSecond: <requests_per_second>
+```
+
+- `baseUrl`: The URL of your GitLab instance (e.g., https://gitlab.opencode.de).
+- `tokenFile`: The file containing the access token (see Token Permissions).
+- `type`: The type of GitLab server (e.g., gitlab).
+- `maxRequestsPerSecond`: Maximum number of requests allowed per second to avoid rate-limiting.
+
+
+#### Token Permissions
+
+The token is used to authenticate the badge api against the git provider api. For regular usage the token does not need any special permissions. It is only used because even for open source projects **gitlab** requires authentication for `/member` endpoints.
+
+Nevertheless, there is a special case if you provide [manual checks](#manual-check-type) with a decision json file stored in a private repository. In this case, the badge api uses the provided token to access the json file as well (if the baseURL matches). For this operation the token needs to have at least the `read_repository` permission (project access token is fine as well). The same applies to `svgUrls` which are stored in private repositories.
+
+
+The api identifies the correct token by the provided `baseUrl` and `type` in the configuration file.
+
+
+### Badges Configuration
+
+The `badges` section defines various badges, their levels, and checks. A badge can have multiple levels, each with associated checks.
+
+```yaml
 badges:
-  - id: your-badge-name 
-    description: "Description of this badge"
-    # ORDERED list of levels of your badge (e.g. bronze, silver, gold)
+  - id: <badge_id>
+    description: <badge_description>
     levels:
-    - name: level-1-name
-      svgUrl: https://gitlab.opencode.de/.../raw/main/assets/badge-xy-level-1.svg
-      # Optional - if true, the checks of this level are not necessary for the next higher level, default is false
-      notNecessaryForNextHigherLevels: true
-      description: "Description of the level"
-      # List of checks for this level, these can be one of the implemented types (see /implemented-checks) or of type MANUAL
-      checks:
-      - type: PACKAGES
-        description: "Describe the check in context of your badge and level"
-        # sense of these options depends on the check
-        threshold:
-          timeRangeInMonths: 6
-          min: 1
-          max: 3
-      - type: MANUAL 
-        description: "Description of the manual check"
-        # For more details see /concepts/configuration/manual-checks
-        # URL to the JSON file that contains a list of granted projects or a regex pattern for granted projects 
-        decisionJsonUrl: "https://gitlab.opencode.de/.../raw/main/badges/manual-check.json"
+      - name: <level_name>
+        svgUrl: <url_to_badge_svg>
+        checks:
+          - type: <check_type>
+            description: <check_description>
+            threshold:
+              timeRangeInMonths: <number_of_months>
+              min: <minimum_value>
+              max: <maximum_value>
 ```
+
+Each badge can have different levels (e.g., `bronze`, `silver`, `gold`). For each level, there are checks that are applied to the project. A check can be based on the following types:
+
+- `COMMITS`: Checks if the project has a minimum number of commits in a defined time range.
+- `ISSUE_REACTION_TIME`: Measures the average time to respond to issues.
+- `BUS_FACTOR`: Checks the number of maintainers involved.
+- `RELEASES`: Checks the number of releases made in a specified period.
+- `ELEPHANT_FACTOR`: Checks if multiple companies are contributing to the project.
+- `PACKAGES`: Checks the number of packages released.
+- `CI_PIPELINES`: Checks the number of successful CI pipelines.
+
+Each check has a threshold with two optional parameters:
+
+- `min`: Minimum value required (e.g., number of commits, maintainers).
+- `max`: Maximum value allowed (e.g., issue response time).
+- `timeRangeInMonths`: Time period (in months) to evaluate the project activity.
+
+### Example configuration
+
+```yaml
+badges:
+  - id: maintained
+    description: This badge checks if a project is maintained.
+    levels:
+      - name: bronze
+        notNecessaryForNextHigherLevel: true
+        svgUrl: https://gitlab.opencode.de/open-code/badgebackend/badge-api/-/raw/main/assets/MAINTAINED-1.svg
+        checks:
+          - type: COMMITS
+            description: Checks if the number of commits during the last 6 month is greater than 5.
+            threshold:
+              timeRangeInMonths: 6
+              min: 5
+      - name: silver
+        svgUrl: https://gitlab.opencode.de/open-code/badgebackend/badge-api/-/raw/main/assets/MAINTAINED-2.svg
+        checks:
+          - type: ISSUE_REACTION_TIME
+            description: Checks if the average reaction time to issues is less than 7 days.
+            threshold:
+              timeRangeInMonths: 3
+              max: 7
+          - type: BUS_FACTOR
+            description: Checks if multiple maintainers are working on the project.
+            threshold:
+              timeRangeInMonths: 6
+              min: 1
+      - name: gold
+        svgUrl: https://gitlab.opencode.de/open-code/badgebackend/badge-api/-/raw/main/assets/MAINTAINED-3.svg
+        checks:
+          - type: RELEASES
+            description: Checks if the number of releases during the last 6 month is greater than 1.
+            threshold:
+              timeRangeInMonths: 6
+              min: 1
+          - type: ELEPHANT_FACTOR
+            description: Checks if multiple companies are working on the project.
+            threshold:
+              timeRangeInMonths: 6
+              min: 1
+```
+
+### Manual check type
+
+Besides the predefined checks there is a `MANUAL` check type. This type of check requires external input or decision-making, which cannot be automatically evaluated by the API based on predefined metrics like commits, issues, or releases. Instead, it relies on an external JSON file to guide the decision-making process.
+
+Example of a manual check:
+
+```yaml
+badges:
+  - id: open-source
+    description: This badge checks if a project is open source.
+    levels:
+      - name: gold
+        svgUrl: https://gitlab.opencode.de/open-code/badgebackend/manual-badges/-/raw/main/badges/open-source.svg
+        checks:
+          - type: MANUAL
+            decisionJsonUrl: https://gitlab.opencode.de/open-code/badgebackend/manual-badges/-/raw/main/badges/open-source.json
+            description: Checks if a project is open source. This check is decided manually by the Open-Code team.
+```
+
+In this case, the decisionJsonUrl points to a file (open-source.json) that contains the rules or decision criteria for determining if a project is open source. The file is hosted on a GitLab server, and the Badge API will access it at **start time**.
+
+The JSON file should have the following structure:
+
+```json
+{
+  "granted": <List of repository urls that are granted the badge>,
+  "grantedRegex": <List of regex patterns that are granted the badge>,
+}
+```
+
+Example decision JSON file:
+
+```json
+{
+  "granted": [
+    "https://gitlab.opencode.de/open-code/badgebackend/badge-api",
+    "https://gitlab.opencode.de/open-code/badgebackend/badge-frontend"
+  ],
+  "grantedRegex": [
+    "https://gitlab.opencode.de/open-code/badgebackend/.*"
+  ]
+}
+```
\ No newline at end of file

src/pages/concepts/official-badges/active-maintained-badge.mdx

@@ -10,7 +10,11 @@ import { Callout } from 'nextra/components'
 </Callout>
 
 
-<div className="flex justify-center mt-8"><img src="/assets/badges/maintenance/wartung-overview.png" className="h-48"/></div>
+<div className="flex gap-4 justify-center mt-8">
+<img src="/assets/badges/MAINTAINED-1.svg" className="h-48"/>
+<img src="/assets/badges/MAINTAINED-2.svg" className="h-48"/>
+<img src="/assets/badges/MAINTAINED-3.svg" className="h-48"/>
+</div>
 
 The active maintained badge is a badge that indicates the maintenance status of a repository.
 The badge is based on the following criteria:

src/pages/concepts/official-badges/reuse-badge.mdx

@@ -9,7 +9,11 @@ import { Callout } from 'nextra/components'
 **Status: In development**
 </Callout>
 
-<div className="flex justify-center mt-8"><img src="/assets/badges/reuse/reuse-overview.png" className="h-48"/></div>
+<div className="flex justify-center gap-4 mt-8">
+<img src="/assets/badges/REUSED-1.svg" className="h-48"/>
+<img src="/assets/badges/REUSED-2.svg" className="h-48"/>
+<img src="/assets/badges/REUSED-3.svg" className="h-48"/>
+</div>
 
 The reuse badge is a badge that indicates the reuse status of a repository. 
 The badge is based on the following criteria:

src/pages/concepts/official-badges/security-badge.mdx

@@ -9,7 +9,11 @@ import { Callout } from 'nextra/components'
 **Status: In development**
 </Callout>
 
-<div className="flex justify-center mt-8"><img src="/assets/badges/sec/sec-overview.png" className="h-48"/></div>
+<div className="flex justify-center gap-4 mt-8">
+<img src="/assets/badges/SECURITY-1.svg" className="h-48"/>
+<img src="/assets/badges/SECURITY-2.svg" className="h-48"/>
+<img src="/assets/badges/SECURITY-3.svg" className="h-48"/>
+</div>
 
 The active maintained badge is a badge that indicates the security status of a repository.
 The badge is based on the following criteria:

src/pages/introduction.mdx

@@ -14,10 +14,6 @@ provide you a detailed explanation of the result too.
 
 ## Official Badges on openCode
 
-<div className="flex justify-center mt-8 bg-gray-100 py-6 px-2 rounded-lg">
-    <img src="/assets/badges/badges-overview.png" alt="Badges overview" className="h-32"/>
-</div>
-
 Learn about the different types of badges that are available on openCode and what they mean in the [concepts section](/concepts).
 
 ## Getting started