feat: Refactoring Documentation

.github/copilot-instructions.md

@@ -0,0 +1,64 @@
+# OneGround Developer Portal - AI Assistant Instructions
+
+## Project Overview
+
+This repository hosts the [dev.oneground.nl](https://dev.oneground.nl) developer portal, built with **Docusaurus 3** (React static site generator). It documents the implementation of Dutch case management APIs (ZGW - Zaakgericht Werken).
+
+## Technology Stack
+
+- **Framework**: Docusaurus 3.x
+- **Language**: TypeScript (`.ts`, `.tsx`)
+- **UI/Components**: React 19, Infima (CSS framework), custom CSS modules
+- **Content**: Markdown/MDX (`.md`, `.mdx`)
+- **Formatting**: Prettier
+
+## Critical Workflows
+
+- **Development Server**: `npm start` (Hot reloading enabled)
+- **Production Build**: `npm build` (Outputs to `build/`)
+- **Formatting**: `npm run format`
+    - **CRITICAL**: Always run this command before finishing a task. The CI/CD pipeline enforces strict formatting and will fail if code is not formatted with Prettier.
+
+## Project Structure & Architecture
+
+- **Configuration**:
+    - `docusaurus.config.ts`: Main site config, plugins, presets, and theme config.
+    - `sidebars.ts`: Documentation sidebar structure.
+- **Content**:
+    - `docs/`: Main documentation files (Markdown/MDX).
+    - `blog/`: Blog posts (Markdown/MDX).
+    - `static/`: Static assets (images, robots.txt) - copied directly to build root.
+- **Source Code**:
+    - `src/pages/`: React components that become standalone pages (e.g., `index.tsx` is the homepage).
+    - `src/components/`: Reusable React components.
+    - `src/css/custom.css`: Global custom styles (overrides Infima variables).
+
+## Coding Conventions
+
+- **Links**: When linking between documentation pages, use relative file paths (e.g., `[Link](./doc-file.md)`), not URL paths. Docusaurus resolves them automatically.
+- **Sidebars**: New documentation pages must be added to `sidebars.ts` unless using autogenerated sidebars (this project uses manual definition).
+- **Images**: Place specific images in `static/img` and reference them via `/img/...`.
+- **React Components**: Use functional components with TypeScript.
+- **Styling**: Prefer updating `src/css/custom.css` for global changes or using CSS modules/Infima utility classes for components.
+
+## Docusaurus Specifics
+
+- **Swizzle**: Use `npm run swizzle` only if you need to deeply customize internal Docusaurus components (avoid if possible).
+- **Frontmatter**: Ensure valid frontmatter (id, title, description) in Markdown files.
+- **Admonitions**: Use `:::note`, `:::tip`, `:::warning` syntax for callouts.
+
+## Common Tasks
+
+- **Adding a Doc**:
+    1. Create file in `docs/`.
+    2. Add entry to `sidebars.ts` in the appropriate category.
+    3. Run `npm run format`.
+- **Adding a Blog Post**:
+    1. Create file in `blog/` with date prefix `YYYY-MM-DD-title.md`.
+    2. Run `npm run format`.
+
+## Examples
+
+- **Sidebar Config**: See `sidebars.ts` for nested category structure.
+- **Homepage**: See `src/pages/index.tsx`.
+- **Config**: See `docusaurus.config.ts` for plugin and preset options.

blog/2025-03-27-integrating-signing-software-with-zgw.md

@@ -59,7 +59,7 @@ The pattern described here is already implemented and used in production setting
 
 #### Authentication on the ZGW requests
 
-The requests to the ZGW components use the standard authentication for the ZGW API: a JWT generated based on a ClientId and secret. See the [OneGround documentation](/docs/usage-of-clientids) or the general [ZGW documentation](https://vng-realisatie.github.io/gemma-zaken/themas/achtergronddocumentatie/authenticatie-autorisatie) for details.
+The requests to the ZGW components use the standard authentication for the ZGW API: a JWT generated based on a ClientId and secret. See the [OneGround documentation](/docs/general/authentication) or the general [ZGW documentation](https://vng-realisatie.github.io/gemma-zaken/themas/achtergronddocumentatie/authenticatie-autorisatie) for details.
 
 #### Authentication on the trigger message
 
@@ -73,7 +73,7 @@ Before the documents are presented to the signer, this person should authenticat
 
 To initiate the signing process, the TSA or ZAC should post a trigger message to the signing software in this format:
 
-```
+```javascript
 {
     "naam": "...", // Name of signing transaction, can be displayed to the signer(s) by the signing software
     "eigenaar": "lisa@breda.dev", // e-mail of user that initiates the signing transaction
@@ -121,7 +121,7 @@ Some details about properties that might not be clear from the description:
 
 If the trigger message is received correctly, the signing software should respond with status code 200 and this message:
 
-```
+```jsonc
 {
     "transaction_id": "2opbDxqSB8BX3137ulqdw2q9_Mw=" // unique id of this signing transaction; format to be determined by the signing software
 }
@@ -135,7 +135,7 @@ Note that signing documents is a very asynchronous sequence: it might be several
 
 When signing is completed successfully, the request to the NRC should be:
 
-```
+```javascript
 {
     "kanaal": "documentacties",
     "hoofdObject": ""$url"", // ZRC url of the case
@@ -151,7 +151,7 @@ When signing is completed successfully, the request to the NRC should be:
 
 When signing has failed, is cancelled or has otherwise not completed successfully, the request to the NRC should be:
 
-```
+```javascript
 {
     "kanaal": "documentacties",
     "hoofdObject": ""$url"", // ZRC url of the case

blog/2025-11-14-oauth2-token-endpoint.md

@@ -131,7 +131,7 @@ By centralizing token creation, we ensure consistent security practices for all
 
 Of course, we understand that this may require some adjustments on each customer application, so we are still supporting legacy integration during this transition period. Additionally, we are expecting that in the future (like ZGW 2.x) self-signed tokens will be deprecated in favor of centralized OAuth2 flows. Our approach not only enhances security today but also ensures your integration remains compliant and robust for years to come.
 
-You can read more about our implementation and how to use the OAuth2 Token Endpoint in our [ClientID Management and JWT Authentication in OneGround](../docs/usage-of-clientids) documentation.
+You can read more about our implementation and how to use the OAuth2 Token Endpoint in our [ClientID Management and JWT Authentication in OneGround](../docs/general/authentication) documentation.
 
 ## Conclusion
 

docs/authorization/ac-configuration.md

@@ -0,0 +1,53 @@
+---
+title: "Configuration & Tooling"
+description: "Guidance on using the OneGround configuration tool for Authorizations, including profiles and best practices."
+keywords: ["configuration", "tooling", "authorizations", "profiles", "OneGround", "limitations"]
+slug: /authorization/configuration
+---
+
+# Configuration & Tooling
+
+:::info OneGround Unlimited Only
+The configuration tool described in this section is exclusive to **OneGround Unlimited** (the managed SaaS solution). It is not available in the open-source version of the components.
+:::
+
+Authorizations in OneGround Unlimited are managed via the detailed configuration tool. This tool simplifies the assignment of permissions using predefined profiles and enforces specific best practices for stability.
+
+## Authorization Profiles
+
+Instead of manually configuring every granular permission scope, the tool utilizes **Authorization profiles**. These profiles perform two main functions:
+
+1. **Simplification**: They group logical sets of permissions together.
+2. **Suggestion**: They guide you toward meaningful authorization sets for common use cases.
+
+## Best Practices
+
+### One Client ID per Application
+
+We strongly advise configuring only **one Client ID per Application**.
+
+- **Reason**: This establishes a clear 1-to-1 relationship between your configuration and the external consumer.
+- **Benefit**: It allows you to adjust Authorizations for a specific application without unintended side effects on other consumers sharing the same resource.
+
+### Restrict Permissions (Least Privilege)
+
+Always restrict Authorizations as much as possible.
+
+- **Risk**: Granting broad access (e.g., 'all Authorizations') can have severe consequences, such as an application having the permission to **delete all cases**.
+- **Advice**: Only assign the profiles strictly necessary for the application's function.
+
+## Tool Limitations & Design Decisions
+
+The OneGround configuration tool implements specific constraints to ensure system stability.
+
+### Single Client ID Enforcement
+
+While the ZGW API standard allows multiple Client IDs for a single Application entity, our tool restricts this to one. This decision was made to keep the configuration view simple and unambiguous for administrators.
+
+### Case Type Granularity
+
+The tool does **not** support restricting Authorizations to specific Case Types (Zaaktypes).
+
+- **Background**: The API standard supports this feature.
+- **Issue**: In previous versions of our tooling, this granularity caused significant maintenance problems. Applications frequently lost access to cases when new versions of a Case Type were published, or conversely, could not access older versions.
+- **Solution**: By omitting this granularity in the tool, we ensure consistent access across all versions of a case type, preventing "breaking changes" in permissions during functional updates.

docs/authorization/ac-introduction.md

@@ -0,0 +1,52 @@
+---
+title: "Introduction to Authorizations"
+description: "Overview of the ZGW Authorizations (AC) system, managing application permissions and access control."
+keywords: [authorizations, introduction, AC, access control, ZGW, API, OneGround, permissions, ClientID]
+slug: /authorization/introduction
+---
+
+# Introduction to Authorizations
+
+The Authorizations system (often referred to as **AC** or Authorizations Component) is a fundamental part of the ZGW API landscape provided by OneGround. It manages the permissions for client applications, ensuring that they can only access or modify the data they are authorized for within the ZGW APIs (such as Zaken or Documenten).
+
+## How it works
+
+The AC acts as the central authority for checking permissions when an API request is made.
+
+1. **API Call**: A client application makes a request to a ZGW API (e.g., creating a Case), including a **Bearer Token**.
+2. **Identification**: The API validates the token and extracts the **Client ID**.
+3. **Verification**: The API consults the **AC** to verify if the application associated with that Client ID has the necessary authorizations for the requested operation.
+4. **Access**: If a valid authorization exists, the request is processed; otherwise, it is denied.
+
+## Getting Started
+
+To manage access for your applications, you typically use the OneGround configuration tool. The process involves:
+
+1. **Create an Application**: Define a logical application entity in the system.
+2. **Assign Client ID**: Link a unique Client ID (from your identity provider) to the application.
+3. **Configure Authorizations**: detailed permissions are assigned to the application. OneGround provides "Authorization profiles" to help select meaningful sets of permissions.
+
+> **Best Practice**: We advise using only **one Client ID per Application**. This creates a clear 1-to-1 relationship, making it easier to adjust authorizations for specific consumers without affecting others.
+
+## Key Concepts
+
+- **Applicatie (Application)**: A registry of a consumer system. In the ZGW standard, an application can have multiple Client IDs, but OneGround tooling enforces a simplified model.
+- **Client ID**: The unique identifier found in the authentication token (JWT) that identifies the calling software.
+- **Autorisatie (Authorization)**: A specific rule granting permission to perform certain actions (scopes) on certain resources.
+
+## Limitations and Advice
+
+When using the OneGround configuration tool, keep the following in mind:
+
+- **One Client ID per App**: While the standard allows multiple, the tool restricts this to simplify configuration and clarity.
+- **Granularity**: The tool is designed to prevent "Authorization Hell". While the API technically supports very granular authorizations (e.g., specific case types), the tool focuses on robust, workable profiles to avoid issues where applications lose access to relevant data (e.g., versioning conflicts with case types).
+- **Least Privilege**: Always restrict authorizations as much as possible. Giving an application "all Authorizations" might inadvertently grant permission to delete all cases.
+
+## Official Standards (VNG)
+
+The OneGround Authorizations system is implemented according to the standards defined by VNG Realisatie. The official standards provide the complete specification:
+
+- **[VNG Autorisaties Standard](https://vng-realisatie.github.io/gemma-zaken/standaard/autorisaties/)**  
+   The core specification for the Authorizations API (Autorisaties services). It defines how applications and authorizations should be structured and queried.
+
+For further technical details on how to configure authorizations in OneGround, please refer to the specific configuration guides.

docs/catalogs/ztc-introduction.md

@@ -0,0 +1,46 @@
+---
+title: "Introduction to Catalogs"
+description: "Overview of the ZGW Catalogs (ZTC) system, managing the definitions and blueprints for cases."
+keywords: [catalogs, introduction, ZTC, ZGW, API, OneGround, zaaktypen, blueprints]
+slug: /catalogs/introduction
+---
+
+# Introduction to Catalogs
+
+The Catalogs system (often referred to as **ZTC** or ZaakTypeCatalogus) is a foundational part of the ZGW API landscape provided by OneGround. It acts as the repository for all definitions (metadata) that describe how cases ("Zaken") and related objects should behave.
+
+## How it works
+
+Before an organization can work with cases, they must define _what_ those cases are. The ZTC stores these definitions.
+
+1. **Definition**: An administrator creates a **ZaakType** (Case Type) in the catalog. This defines properties like:
+    - What phases (Statustypen) the case goes through.
+    - What documents (InformatieObjectTypen) are relevant.
+    - What information is recorded (EigenschapTypen).
+2. **Execution**: When a client application creates a new Case (via the Zaken API), it must refer to a specific **ZaakType** URL from the ZTC.
+3. **Validation**: The Zaken API uses the definition in the ZTC to validate the case data and ensure the process follows the designed workflow.
+
+## Getting Started
+
+To effectively use the ZTC, you typically interact with a management interface or configuration tool to set up your catalogs.
+
+1. **Create a Catalog**: A logical grouping for your definitions (Catalogus).
+2. **Design Case Types**: Define the blueprints for your business processes (e.g., "Building Permit Application", "Complaint", "Internal Review").
+3. **Publish**: Once a Case Type is finalized, it is published so it can be used by consumer applications.
+
+## Key Concepts
+
+- **Catalogus (Catalog)**: A collection of types. An organization can have one or more catalogs.
+- **ZaakType (Case Type)**: The definition of a generic business process (e.g., "Vergunningaanvraag"). It determines the lifecycle and data structure of concrete Cases.
+- **InformatieObjectType (Information Object Type)**: The definition of a document type (e.g., "ID Card Copy", "Decision Document").
+- **BesluitType (Decision Type)**: The definition of a specific decision that can be taken within a case.
+- **StatusType**: Defines a possible state in the lifecycle of a case.
+
+## Official Standards (VNG)
+
+The OneGround Catalogs system is implemented according to the standards defined by VNG Realisatie. The official standards provide the complete specification:
+
+- **[VNG Catalogussen Standard](https://vng-realisatie.github.io/gemma-zaken/standaard/catalogi/)**  
+   The core specification for the Catalogs API (Catalogi services). It defines the resources and relations for case types, document types, and more.
+
+For further technical details, please refer to the specific documentation pages in this section.