@bpmnkit/camunda-docspack 0.0.0

package/.llms/chunks/components.best-practices.architecture.data-flow.md

@@ -0,0 +1,27 @@
+# Data flow
+
+Understand how data moves through Camunda 8.8+ and why it matters when sizing your environment.
+
+Understand how data moves through Camunda 8.8+ and why it matters when sizing your environment.
+
+
+## About
+
+Camunda 8.8 introduced a consolidated [Orchestration Cluster](https://docs.camunda.io/docs/next/components/orchestration-cluster).
+This is an overview of Camunda 8.8+ architecture:
+
+![Camunda 8.8+ architecture overview](assets/architecture-8.8plus.jpg)
+
+<!-- Source: Miro board https://miro.com/app/board/uXjVGiNnJBc=/ -->
+
+See the [reference architecture](https://docs.camunda.io/docs/next/self-managed/reference-architecture/reference-architecture) for a component-topology overview.
+
+### How Camunda stores data
+
+Every record in Camunda passes through two distinct storage layers. Understanding the difference between them is the key to understanding sizing.
+
+- **[Primary storage](https://docs.camunda.io/docs/next/reference/glossary#primary-storage)** is the multi-Raft cluster in Camunda, with partitions as the scaling unit. Each partition has a Raft append-only log, RocksDB to store internal state, and snapshots for compaction. All writes land here first. It is durable and strongly consistent, but it is not directly queryable from outside the cluster. Each partition has exactly one leader responsible for both processing commands and exporting records.
+- **[Secondary storage](https://docs.camunda.io/docs/next/reference/glossary#secondary-storage)** is an external data storage where events are written, such as Elasticsearch, OpenSearch, or an RDBMS (available from 8.9). It is eventually consistent and populated asynchronously by the export pipeline. Everything Operate, Tasklist, Identity, and the REST Query API reads comes exclusively from secondary storage.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/data-flow

package/.llms/chunks/components.best-practices.architecture.data-flow.optimize-data-flow.md

@@ -0,0 +1,37 @@
+# Data flow — Optimize data flow
+
+Optimize sits on top of the export pipeline as a second-tier consumer. See it in violet in the diagram below:
+
+![Camunda 8.8+ architecture overview - Data Flow Optimize](assets/architecture-8.8plus-data-flow-optimize.jpg)
+
+1. The Elasticsearch/OpenSearch exporter writes raw engine events into per-partition Elasticsearch/OpenSearch indices.
+2. Optimize's **importer** reads from those indices and transforms the data into its own analytics indices.
+3. Optimize writes the analytics indices **back into the same or another Elasticsearch/OpenSearch cluster**.
+
+This means Optimize has an additional hop in the data flow compared to Operate and Tasklist, and it writes to secondary storage twice: once for the raw events and once for the analytics indices. As a result, data availability latency for Optimize is higher than for Operate and Tasklist, and the overall write load on Elasticsearch/OpenSearch is significantly higher when Optimize is enabled.
+
+Optimize's indices store variables differently from the raw export. Each variable is stored in its owning process instance document, and its value is indexed in several forms simultaneously. This allows Optimize's variable filters and reports to support the following query types without requiring separate reindexing:
+
+- An exact-match form.
+- A case-insensitive form.
+- A substring-searchable form.
+- A best-effort date form.
+- Best-effort numeric forms for long and double values.
+
+As a result, Optimize's storage cost per variable is significantly higher than the cost of the raw exported record. The storage cost increases further for high-cardinality string variables because the substring-searchable form scales with the number of distinct values:
+
+- Variables with a small number of repeated values, such as a status field, compress efficiently.
+- Variables with a different value for almost every process instance, such as a customer or order ID, compress poorly.
+
+See [Impact of Optimize](https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-your-environment#impact-of-optimize) for measured examples, including how object variable flattening compounds this by multiplying variable count rather than variable value size.
+
+**Note**
+This is exactly why the architecture was changed in 8.8: the Camunda Exporter now aggregates the data for Operate and Tasklist, which previously both used an Exporter-Importer architecture similar to Optimize. See this [blog post](https://camunda.com/blog/2025/02/one-exporter-to-rule-them-all-exploring-camunda-exporter/) for more details.
+
+See the [sizing guide](https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-your-environment#impact-of-optimize) for details on the impact of running Optimize and how to reduce it.
+
+**Note**
+Optimize is not supported with RDBMS backends. If Optimize is required, a separate Elasticsearch/OpenSearch instance must be present even if the core platform uses RDBMS.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/data-flow

package/.llms/chunks/components.best-practices.architecture.data-flow.performance-and-sizing-factors.md

@@ -0,0 +1,12 @@
+# Data flow — Performance and sizing factors
+
+The paths above map directly to the factors to consider when [sizing your environment](https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-your-environment):
+
+- **Partition count** bounds both command path throughput and export pipeline parallelism. More partitions means more parallel processing and exporting, up to the available hardware.
+- **Elasticsearch/OpenSearch resources** is the most common cause of operational delay and degradation. Monitor and scale storage before hitting performance bottlenecks.
+- **Optimize** significantly increases secondary storage write load. Size Elasticsearch/OpenSearch accordingly, or use a dedicated Elasticsearch/OpenSearch instance, if Optimize is enabled.
+
+For hardware recommendations based on these factors, see how to [size your environment](https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-your-environment).
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/data-flow

package/.llms/chunks/components.best-practices.architecture.data-flow.query-path.md

@@ -0,0 +1,13 @@
+# Data flow — Query path
+
+Operate, Tasklist, and the REST Query API (`GET /v2/...`) read exclusively from the configured secondary storage. They never read directly from the engine.
+See it in red in the diagram below:
+
+![Camunda 8.8+ architecture overview - Data Flow Query path](assets/architecture-8.8plus-data-flow-query.jpg)
+
+Query results depend on the performance of both the primary (processing path) and secondary storage (exporting pipeline). They are **eventually consistent**: there is always some lag between a command completing in the engine and the result being visible in search results or the UI. This is measured as the **data availability latency**.
+
+Data availability latency is bounded below by export pipeline lag; if the exporter is behind, data availability is behind. This can be caused by a slow or overloaded secondary storage.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/data-flow

package/.llms/chunks/components.best-practices.architecture.deciding-about-your-stack.customize-your-stack.md

@@ -0,0 +1,16 @@
+# Deciding about your stack — Customize your stack
+
+### Polyglot stacks
+
+You can develop process solutions as described with Java above also in any other programming language, including JavaScript. Use the [existing language clients and SDKs](https://docs.camunda.io/docs/next/apis-tools/working-with-apis-tools) for doing this.
+
+### Run Camunda 8 Self-Managed
+
+Run Camunda 8 on your Kubernetes cluster. For local development, a [Docker Compose configuration is available](https://docs.camunda.io/docs/next/self-managed/deployment/docker/docker), though not for production use. Learn more in the [deployment docs](https://docs.camunda.io/docs/next/self-managed/deployment/helm/install/quick-install).
+
+### Choose an LLM provider
+
+If your processes hand steps to [AI agents](https://docs.camunda.io/docs/next/reference/glossary#ai-agent), the LLM provider becomes part of your stack decision. Weigh hosting, data sensitivity, and cost as described in [choosing the right LLM](https://docs.camunda.io/docs/next/components/agentic-orchestration/choose-right-model-agentic). On Camunda 8 SaaS, you can also start with [Camunda-provided LLM](https://docs.camunda.io/docs/next/components/agentic-orchestration/camunda-provided-llm) and run agents without setting up a provider account first.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/deciding-about-your-stack

package/.llms/chunks/components.best-practices.architecture.deciding-about-your-stack.md

@@ -0,0 +1,69 @@
+# Deciding about your stack
+
+Our greenfield stack recommendation is a result of extensive discussions and evaluations. While not the only option, it is a solid choice if there are no specific reasons to choose an alternative.
+
+Your choice of programming language should align with your team's expertise; we suggest Java or JavaScript for their broad applicability and support, and have outlined the Java greenfield stack below with Camunda 8 SaaS.
+
+
+## The Java greenfield stack
+
+![greenfield stack architecture diagram](deciding-about-your-stack-assets/greenfield-architecture.png)
+
+This architecture diagram illustrates the flow of requests from a user's browser through Camunda SaaS, where workflows and decisions are orchestrated. The process then moves to the Spring Boot application, which is responsible for executing business logic, handling database interactions with PostgreSQL, and managing various components such as custom REST endpoints, BPMN/DMN definitions, and external task workers.
+
+### Why this stack?
+
+- SaaS simplifies workflow engine integration.
+- Spring Boot is widely adopted for Java application development.
+- Flexible for both on-premises and cloud environments.
+
+Discover more in our [getting started guide using Spring](https://docs.camunda.io/docs/next/guides/getting-started-example) or the [Camunda Spring Boot Starter instructions](https://docs.camunda.io/docs/next/apis-tools/camunda-spring-boot-starter/getting-started).
+
+### Set up the stack
+
+For a Java-based setup using Camunda 8 SaaS and Spring Boot, use the following stack:
+
+#### Camunda 8 SaaS account and cluster
+
+If you're new to Camunda SaaS, check out our [getting started guide](https://docs.camunda.io/docs/next/guides/introduction-to-camunda-8#getting-started) to set up your environment.
+
+After signing up, create a cluster by following [creating a cluster in Camunda 8](https://docs.camunda.io/docs/next/components/hub/organization/manage-clusters/create-cluster), which provides step-by-step instructions on setting up a new cluster in the Camunda 8 environment.
+
+#### Spring Boot
+
+Develop your own process solutions as [Spring Boot](https://spring.io/projects/spring-boot) applications. This involves setting up a new Spring Boot project, either manually or using tools like [Spring Initializr](https://start.spring.io/).
+
+Integrate the [Camunda Spring Boot Starter](https://docs.camunda.io/docs/next/apis-tools/camunda-spring-boot-starter/getting-started) into the Spring Boot project by adding necessary dependencies to the project’s `pom.xml` file, and configure the application to use Camunda services.
+
+#### Maven
+
+Use [Maven](https://maven.apache.org/) to manage the build lifecycle of the application.
+
+#### IDE selection
+
+Select an Integrated Development Environment (IDE) that supports Java development, Maven, and Spring Boot. Frequently used options include Visual Studio Code, IntelliJ IDEA, or Eclipse.
+
+#### Java runtime
+
+Install and use OpenJDK 17 as your Java runtime environment. Download it from the [official JDK 17 download page](https://jdk.java.net/17/).
+
+#### Modeling
+
+Download and use Camunda Modeler for designing and modeling business processes. Modeler is available [here](https://camunda.org/download/modeler/).
+
+#### Code integration
+
+Incorporate all Java code and BPMN process models into the Spring Boot project, ensuring that they are structured correctly and referenced properly within the application.
+
+### Run the process application:
+
+To run the process application, transfer the `jar` to the desired server.
+
+Start the application using the command `java -jar YourProcessApplication.jar`. Frequently, this deployment process is managed through Docker for ease of use.
+
+For a practical implementation, refer to our [example application on GitHub](https://github.com/camunda-community-hub/camunda-cloud-examples/tree/main/twitter-review-java-springboot), which demonstrates a typical setup for a Spring Boot-based process application with Camunda.
+
+<!-- This should be moved from the Community Hub -->
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/deciding-about-your-stack

package/.llms/chunks/components.best-practices.architecture.sizing-benchmarks.md

@@ -0,0 +1,22 @@
+# Run benchmarks
+
+Run your own benchmarks to validate Camunda 8 sizing for your specific workload.
+
+Run your own benchmarks to validate [Camunda 8 sizing](https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-your-environment) for your specific workload.
+
+
+## Reference benchmark scenario
+
+The sizing recommendations for [SaaS](https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-saas) and [Self-Managed](https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-self-managed) are based on a reference benchmark scenario. Your actual workload may differ significantly, so running your own benchmarks is the most reliable way to validate that your chosen configuration meets your needs.
+
+Camunda uses the following realistic benchmark scenario:
+
+- **Process model:** [bankCustomerComplaintDisputeHandling.bpmn](https://github.com/camunda/camunda/blob/main/load-tests/load-tester/src/main/resources/bpmn/realistic/bankCustomerComplaintDisputeHandling.bpmn) (a credit card fraud dispute handling process from the [Camunda Marketplace blueprint](https://marketplace.camunda.com/en-US/apps/449510/credit-card-fraud-dispute-handling)).
+- **Payload:** [realisticPayload.json](https://github.com/camunda/camunda/blob/main/load-tests/load-tester/src/main/resources/bpmn/realistic/realisticPayload.json) (~11 KB).
+- This setup produces approximately **101 tasks per second at 1 PI/s** due to internal sub-process instantiation (50 sub-process instances per root instance).
+
+**Note**
+The official sizing numbers on this page are produced using the [load-tester](https://github.com/camunda/camunda/tree/main/load-tests/load-tester) tool from the Camunda monorepo.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-benchmarks

package/.llms/chunks/components.best-practices.architecture.sizing-benchmarks.run-your-own-benchmarks.md

@@ -0,0 +1,41 @@
+# Run benchmarks — Run your own benchmarks
+
+Use the [Camunda 8 Benchmark project (c8b)](https://github.com/camunda-community-hub/camunda-8-benchmark), a Spring Boot application, to run load tests against your cluster.
+
+### Key features
+
+- Starts process instances at a configurable rate and **automatically adjusts based on backpressure**.
+- Completes tasks that appear in the process instances.
+- **Bring your own BPMN process model and payload**, which can be provided as URLs, such as GitHub Gists.
+- **Automatic job type discovery** from BPMN files.
+- Configurable **task completion delay** to simulate real worker behavior.
+- Built-in **Prometheus metrics and Grafana dashboards** for observability.
+
+### Quick start
+
+Run the following command against your cluster:
+
+```bash
+mvn spring-boot:run
+```
+
+With Docker:
+
+```bash
+docker run camundacommunityhub/camunda-8-benchmark:main
+```
+
+Customize it with your own process and payload:
+
+```bash
+benchmark.bpmnResource=url:https://your-gist-url/your-process.bpmn
+benchmark.payloadPath=url:https://your-gist-url/your-payload.json
+benchmark.processInstanceStartRate=25
+benchmark.taskCompletionDelay=200
+```
+
+**Important**
+To run meaningful benchmarks, use a **properly sized environment**. SaaS trial clusters and local developer machines have limited resources and will hit bottlenecks too early. Use either a correctly sized Camunda SaaS cluster (with help from your Camunda representative) or a properly provisioned Self-Managed Kubernetes environment.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-benchmarks

package/.llms/chunks/components.best-practices.architecture.sizing-benchmarks.what-to-measure.md

@@ -0,0 +1,17 @@
+# Run benchmarks — What to measure
+
+When running benchmarks, focus on these key metrics:
+
+- **Sustained throughput (tasks/second):** The rate your cluster can handle continuously without increasing backpressure.
+- **Backpressure rate:** Should remain below 10% for sustainable operation.
+- **Process instance latency (p99):** End-to-end time from instance creation to completion. Target depends on your SLO.
+- **Elasticsearch disk growth rate:** Helps you forecast disk capacity needs.
+- **Data availability latency:** The time between an event in the engine and its appearance in Operate/Tasklist.
+  - Note: to measure this, you have to compare the time from starting an instance and its availability in query APIs using the Orchestration Cluster REST API
+- **CPU usage and throttling:** High CPU usage or frequent throttling indicates a need for more CPU resources or additional brokers.
+- **Memory usage:** Sustained high memory usage suggests the need for larger memory limits or additional nodes.
+
+<!-- TODO: Define the exact SLO boundary used for "max throughput" in the official benchmark tables (e.g., "max sustainable throughput where backpressure remains below 10% and p99 process duration stays under 1 second"). If the exact boundary is not standardized, document the methodology. -->
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-benchmarks

package/.llms/chunks/components.best-practices.architecture.sizing-benchmarks.when-to-benchmark.md

@@ -0,0 +1,12 @@
+# Run benchmarks — When to benchmark
+
+Running your own benchmarks when:
+
+- Your process models or payload sizes **differ significantly** from the reference scenario.
+- **Latency or cycle time requirements** are critical to your use case.
+- You are running Optimize with **payloads larger than the reference ~11 KB** or retention periods **exceeding 6 months**. Larger payloads and longer retention amplify Elasticsearch disk consumption and Optimize import times.
+- You are **upgrading from a pre-8.8 version** and want to validate resource requirements.
+- You are using **RDBMS (PostgreSQL) as secondary storage** and want to validate throughput differences.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-benchmarks

package/.llms/chunks/components.best-practices.architecture.sizing-saas.data-retention.md

@@ -0,0 +1,14 @@
+# Size your SaaS cluster — Data retention
+
+The maximum throughput numbers should be considered peak loads, and the data retention configuration considered when defining the amount of data kept for completed instances in your cluster. See [Camunda 8 SaaS data retention](https://docs.camunda.io/docs/next/components/saas/data-retention) for the default retention times for Zeebe, Tasklist, Operate, and Optimize.
+
+- If process instances are completed and older than the configured retention time for an application, the data is removed.
+- If a process instance is older than the configured retention time but still active and incomplete, it continues to function at runtime and is _not_ removed.
+
+Camunda can adjust data retention on request (up to certain limits). Consider retention time adjustments and/or storage capacity increases if you plan to run more than \[max PI stored in ES\] / \[configured retention time\].
+
+**Note: Why is the total number of process instances stored that low?**
+This is related to the limited resources provided to Elasticsearch, which can cause performance problems when too much data is stored there. By increasing the available memory for Elasticsearch, you can also increase that number. At the same time, even with this rather low number, you can always guarantee the throughput of the core workflow engine during peak loads, as this performance is not affected. You can also increase memory for Elasticsearch later if needed.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-saas

package/.llms/chunks/components.best-practices.architecture.sizing-saas.md

@@ -0,0 +1,21 @@
+# Size your SaaS cluster
+
+Select the right Camunda 8 SaaS cluster size based on your needs.
+
+Select the right Camunda 8 SaaS cluster size based on your needs. For an overview of the factors that influence sizing, see [Size your environment](https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-your-environment).
+
+
+## Determine your cluster size
+
+Camunda 8 defines four [cluster sizes](https://docs.camunda.io/docs/next/components/concepts/clusters#cluster-size) (1x, 2x, 3x, and 4x) you can select after choosing your [cluster type](https://docs.camunda.io/docs/next/components/concepts/clusters#cluster-type).
+
+To do so, follow these steps:
+
+1. Calculate your throughput and storage requirements using the guidance in [Size your environment](https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-your-environment).
+2. Use the [sizing tables](#sizing-tables) to find the cluster size that meets your needs.
+
+**Note**
+To increase the cluster size beyond 4x, [reach out to Camunda](https://camunda.com/contact-us/). This requires custom sizing and pricing.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-saas

package/.llms/chunks/components.best-practices.architecture.sizing-saas.next-steps.md

@@ -0,0 +1,6 @@
+# Size your SaaS cluster — Next steps
+
+Validate your chosen configuration by [running your own benchmarks](https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-benchmarks).
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-saas

package/.llms/chunks/components.best-practices.architecture.sizing-saas.sizing-tables.md

@@ -0,0 +1,27 @@
+# Size your SaaS cluster — Sizing tables
+
+| Cluster size                                         |                              1x |                              2x |                              3x |                              4x |
+| :--------------------------------------------------- | ------------------------------: | ------------------------------: | ------------------------------: | ------------------------------: |
+| Max Throughput **Tasks/day** **\***                  |                             9 M |                            18 M |                            27 M |                            36 M |
+| Max Throughput **Tasks/second** **\***               |                             100 |                             200 |                             300 |                             400 |
+| Max Throughput **Process Instances/second** **\*\*** |                               5 |                              10 |                              15 |                              20 |
+| Max Total Number of PI stored (in ES) **\*\*\***     |                           200 k |                           400 k |                           600 k |                           800 k |
+| Approximate resources provisioned **\*\*\*\***       | 11 vCPU, 22 GB mem, 192 GB disk | 22 vCPU, 44 GB mem, 384 GB disk | 33 vCPU, 66 GB mem, 576 GB disk | 44 vCPU, 88 GB mem, 768 GB disk |
+
+<!-- TODO: Validate "with Optimize" numbers against 8.9 benchmarks. The numbers above were measured with Camunda 8.8. Also confirm whether the "max throughput" boundary condition is defined as backpressure < 10% and p99 process duration < 1s, or another SLO. -->
+
+**Note**
+The numbers in the tables were measured using Camunda 8 (version 8.8), [the benchmark project](https://github.com/camunda-community-hub/camunda-8-benchmark) running on its own Kubernetes cluster, and using a [realistic process](https://github.com/camunda/camunda/blob/main/load-tests/load-tester/src/main/resources/bpmn/realistic/bankCustomerComplaintDisputeHandling.bpmn) with this [payload](https://github.com/camunda/camunda/blob/main/load-tests/load-tester/src/main/resources/bpmn/realistic/reducedPayload.json) (~1.4 KB). To calculate day-based metrics, an equal distribution over 24 hours is assumed.
+
+**\*** Tasks (including service, send, and user tasks, among others) completed per day are the primary metric, as this is easy to measure and strongly influences resource consumption. This number assumes a constant load throughout the day. Tasks/day and Tasks/second are scaled linearly.
+
+**\*\*** Because tasks are the primary resource driver, the number of process instances supported by a cluster is calculated assuming an average of 10 tasks per process. As a customers, you can calculate a more accurate process instance estimate using your anticipated number of tasks per process.
+
+**\*\*\*** Maximum total number of historical process instances within the retention period.
+For active process instances, this is limited mostly by Zeebe resources; for historical instances, it is limited mostly by Elasticsearch resources. Calculated assuming a typical set of process variables per process instance. Note that it makes a difference whether you add one or two strings (requiring ~1 KB of space) to your process instances or attach a full JSON document containing 1 MB, as this data must be stored in various places, influencing memory and disk requirements. If this number increases, you can still retain the runtime throughput, but Tasklist, Operate, and/or Optimize may lag behind.
+The provisioned disk size is calculated as the sum of the disk size used by Zeebe and Elasticsearch.
+
+**\*\*\*\*** These are the resource limits configured in the Kubernetes cluster and are subject to change.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-saas

package/.llms/chunks/components.best-practices.architecture.sizing-self-managed.baseline-performance.md

@@ -0,0 +1,18 @@
+# Self-Managed resource planning — Baseline performance
+
+Considering this [baseline resource configuration](#baseline-resource-configuration), you can expect the following performance:
+
+| Metric                                          | Value                                          |
+| ----------------------------------------------- | ---------------------------------------------- |
+| Completed process instances per second          | 51 (includes root and child process instances) |
+| Completed flow node instances (FNIs) per second | 560                                            |
+| Completed tasks per second                      | 100                                            |
+| Data availability (query API latency)           | < 5 seconds                                    |
+
+**Important**
+These numbers were measured using Camunda's [load test application](https://github.com/camunda/camunda/tree/main/load-tests/load-tester) with a [realistic reference process](https://github.com/camunda/camunda/blob/main/load-tests/load-tester/src/main/resources/bpmn/realistic/bankCustomerComplaintDisputeHandling.bpmn) and [realistic payload](https://github.com/camunda/camunda/blob/main/load-tests/load-tester/src/main/resources/bpmn/realistic/realisticPayload.json) (~11 KB). For details on the testing methodology, see the [reliability testing documentation](https://github.com/camunda/camunda/blob/main/docs/testing/reliability-testing.md).
+
+The realistic reference process starts one root process instance, which spawns 50 sub-process instances via call activities. It covers a wide variety of BPMN elements, including call activities, multi-instance, sub-processes, and DMN. The process is based on the [Credit Card Fraud Dispute Handling](https://marketplace.camunda.com/en-US/apps/449510/credit-card-fraud-dispute-handling) blueprint from the Camunda Marketplace.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-self-managed

package/.llms/chunks/components.best-practices.architecture.sizing-self-managed.baseline-resource-configuration-with-optimize.md

@@ -0,0 +1,34 @@
+# Self-Managed resource planning — Baseline resource configuration — with-optimize
+
+When Optimize is enabled, additional resources are needed, especially for Elasticsearch, because Optimize's importer reads from and writes to Elasticsearch indices. See [Impact of Optimize](https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-your-environment#impact-of-optimize) for more details.
+
+<!-- TODO: Validate these resource numbers against 8.9 benchmarks. These numbers are based on the Optimize V2 experiment (minimum ES resources for realistic workload at 1 PI/s with 101 tasks/s). -->
+
+| Component                 |                     | Request | Limit |
+| ------------------------- | ------------------- | ------: | ----: |
+| **Orchestration Cluster** |                     |         |       |
+| Brokers                   | 3                   |         |       |
+| Partitions                | 3                   |         |       |
+| Replication factor        | 3                   |         |       |
+|                           | vCPU \[cores\]      |       3 |     3 |
+|                           | Memory \[GB\]       |       2 |     2 |
+|                           | Disk \[GB\]         |         |   128 |
+| **Connectors**            |                     |         |       |
+| #                         | 1                   |         |       |
+|                           | vCPU \[cores\]      |     0.2 |   0.2 |
+|                           | Memory limit \[GB\] |   0.512 |     1 |
+| **Optimize**              |                     |         |       |
+| #                         | 1                   |         |       |
+|                           | vCPU \[cores\]      |     0.6 |     2 |
+|                           | Memory limit \[GB\] |       1 |     2 |
+| **Elastic**               |                     |         |       |
+| #statefulset              | 3                   |         |       |
+|                           | vCPU \[cores\]      |       7 |     7 |
+|                           | Memory limit \[GB\] |       6 |     8 |
+|                           | Disk request \[GB\] |         |   512 |
+
+**Note**
+The numbers in the tables were measured using a [realistic process](https://github.com/camunda/camunda/blob/main/load-tests/load-tester/src/main/resources/bpmn/realistic/bankCustomerComplaintDisputeHandling.bpmn) with a [realistic payload](https://github.com/camunda/camunda/blob/main/load-tests/load-tester/src/main/resources/bpmn/realistic/realisticPayload.json) (~11 KB). To calculate day-based metrics, an equal distribution over 24 hours is assumed.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-self-managed

package/.llms/chunks/components.best-practices.architecture.sizing-self-managed.baseline-resource-configuration-without-optimize.md

@@ -0,0 +1,27 @@
+# Self-Managed resource planning — Baseline resource configuration — without-optimize
+
+The following configuration provides a baseline equivalent to a 1x SaaS cluster without Optimize enabled.
+
+<!-- TODO: Validate these resource numbers against 8.9 benchmarks. The Orchestration Cluster CPU request of 3 cores reflects the 8.8 streamlined architecture. Confirm max throughput and max stored PI for this configuration. -->
+
+| Component                 |                     | Request | Limit |
+| ------------------------- | ------------------- | ------: | ----: |
+| **Orchestration Cluster** |                     |         |       |
+| Brokers                   | 3                   |         |       |
+| Partitions                | 3                   |         |       |
+| Replication factor        | 3                   |         |       |
+|                           | vCPU \[cores\]      |       3 |     3 |
+|                           | Memory \[GB\]       |       2 |     2 |
+|                           | Disk \[GB\]         |         |   128 |
+| **Connectors**            |                     |         |       |
+| #                         | 1                   |         |       |
+|                           | vCPU \[cores\]      |     0.2 |   0.2 |
+|                           | Memory limit \[GB\] |   0.512 |     1 |
+| **Elastic**               |                     |         |       |
+| #statefulset              | 3                   |         |       |
+|                           | vCPU \[cores\]      |       3 |     3 |
+|                           | Memory limit \[GB\] |       2 |     2 |
+|                           | Disk request \[GB\] |         |   128 |
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-self-managed

package/.llms/chunks/components.best-practices.architecture.sizing-self-managed.baseline-resource-configuration.md

@@ -0,0 +1,10 @@
+# Self-Managed resource planning — Baseline resource configuration
+
+<Tabs groupId="optimize" defaultValue="with-optimize" values={
+[
+{ label: 'Without Optimize', value: 'without-optimize', },
+{ label: 'With Optimize', value: 'with-optimize', },
+]}>
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-self-managed

package/.llms/chunks/components.best-practices.architecture.sizing-self-managed.md

@@ -0,0 +1,31 @@
+# Self-Managed resource planning
+
+Provision Camunda 8 on your Self-Managed cluster with Kubernetes and Helm using these baseline configurations, then adjust sizing based on your workload.
+
+Provisioning Camunda 8 on your Self-Managed cluster depends on several factors. Use [Kubernetes with Helm](https://docs.camunda.io/docs/next/self-managed/deployment/helm/index) to deploy and manage your Self-Managed cluster.
+
+Use the configurations and guidance below as a baseline, then adjust based on your workload. For background on the factors that drive provisioning requirements, see [Size your environment](https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-your-environment).
+
+
+## Camunda 8.8+ resource consumption
+
+Camunda 8.8 introduced a streamlined architecture that consolidates the broker, gateway, Operate, Tasklist, and Identity into a single application, the [Orchestration Cluster](https://docs.camunda.io/docs/next/components/orchestration-cluster). This changes how you think about resource consumption compared to older versions.
+
+If you are upgrading from a pre-8.8 version, expect different resource profiles:
+
+- The Orchestration Cluster requires **more CPU per broker** compared to 8.7 (approximately 75% more CPU, for example, 2 to 3.5 cores, to maintain equivalent throughput).
+- Throughput at the default 2 CPU cores drops ~35% compared to 8.7.x.
+- With properly aligned resources (3.5 CPU cores), 8.8.x achieves similar throughput to 8.7.x with **significantly lower latency** (approximately a 2x improvement).
+- The streamlined architecture reduces operational complexity (fewer pods to manage) but consolidates resource consumption into fewer, larger pods.
+
+All components are clustered to provide high-availability, fault-tolerance, and resilience.
+
+The Orchestration Cluster scales horizontally by adding more nodes (pods). This is limited by the [number of partitions](https://docs.camunda.io/docs/next/components/zeebe/technical-concepts/partitions) configured for a cluster, as the work within one partition cannot be parallelized by design. Hence, you need to define enough partitions to utilize your hardware. The [number of partitions can be scaled up](https://docs.camunda.io/docs/next/self-managed/components/orchestration-cluster/zeebe/operations/cluster-scaling) after the cluster is initially provisioned, but not yet scaled down.
+
+Camunda 8 runs on Kubernetes. Every component runs as a pod with assigned resources. These resources can be scaled vertically (assigned more or fewer resources dynamically) within certain limits. Vertical scaling does not always increase throughput, since the components depend on each other.
+
+**Note**
+Camunda licensing does not depend on the provisioned hardware resources, making it easy to size according to your needs.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-self-managed

package/.llms/chunks/components.best-practices.architecture.sizing-self-managed.memory.md

@@ -0,0 +1,49 @@
+# Self-Managed resource planning — Memory
+
+Memory usage is determined by the Java heap size (by default, [25% of the maximum RAM](https://docs.oracle.com/en/java/javase/21/gctuning/ergonomics.html#GUID-DA88B6A6-AF89-4423-95A6-BBCBD9FAE781)) and native memory usage (also 25% by default); the JVM can use up to 50% of available RAM.
+
+Zeebe supports three RocksDB memory allocation strategies, configured using `CAMUNDA_DATA_PRIMARYSTORAGE_ROCKSDB_MEMORYALLOCATIONSTRATEGY`:
+
+- **`FRACTION`** (the default starting with 8.10): Total RocksDB memory is calculated as `..._MEMORYFRACTION` (default: `0.1`, or 10%) of the broker’s total system memory and is shared across all partitions on the broker.
+- **`PARTITION`** (the default before 8.10): Total RocksDB memory is calculated by multiplying the number of partitions on the broker by `CAMUNDA_DATA_PRIMARYSTORAGE_ROCKSDB_MEMORYLIMIT` (default: 512 MB).
+- **`BROKER`**: Total RocksDB memory is equal to `..._MEMORYLIMIT` and is shared across all partitions on the broker, regardless of the number of partitions.
+
+When hardcoding memory values using `PARTITION` or `BROKER`, consider the following:
+
+- Zeebe relies heavily on memory-mapped files, so sufficient OS page cache is required. Insufficient page cache degrades I/O performance.
+- Reserve 20-30% of total memory for the OS page cache as a starting point, adjusting based on observed performance. The right amount depends on partition count and system throughput.
+
+The minimum memory usage (using the `PARTITION` strategy) is:
+
+| Component          |                    Amount |
+| ------------------ | ------------------------: |
+| Java heap          |                       25% |
+| Java native memory |                       25% |
+| RocksDB            |  512 MB × partition count |
+| OS page cache      |                    20-30% |
+| **Sum**            | **x MB + 50% of max RAM** |
+
+When using `FRACTION`, replace the RocksDB row with `memory-fraction × total memory` (10% by default) instead.
+
+### Keep the default `FRACTION` strategy for primary storage
+
+As of 8.10, `FRACTION` is the shipped default for primary storage: no action is required to benefit from it on a new deployment.
+
+`FRACTION` scales with the broker's actual memory automatically, unlike `PARTITION` and `BROKER`, which are absolute limits: if you resize a broker's memory or change its partition count, you have to remember to retune the limit too, or RocksDB's share of memory silently stays where it was. This also mirrors the direction Camunda SaaS already takes for primary storage.
+
+If you're upgrading from a version before 8.10 and previously relied on the `PARTITION` default, your effective RocksDB memory allocation changes on upgrade unless you set the strategy explicitly. See the [8.10 release notes](https://docs.camunda.io/docs/next/reference/announcements-release-notes/8100/8100-release-notes#default-rocksdb-memory-allocation-strategy-changed-to-fraction) for details.
+
+```yaml
+camunda:
+  data:
+    primary-storage:
+      rocks-db:
+        memory-allocation-strategy: fraction
+        memory-fraction: 0.1
+```
+
+**Caution**
+`FRACTION` splits its budget across **all** partitions on a broker, the same way `BROKER` does. Unlike `PARTITION`, it does not scale up with partition count. On a broker with many partitions but modest total memory, a flat 10% fraction can allocate less RocksDB memory than a previously tuned fixed limit would have. An optional minimum-floor setting for `FRACTION` is proposed in [camunda/camunda#57768](https://github.com/camunda/camunda/issues/57768) (open) to address exactly this; until it ships, verify the resulting absolute memory is enough for your partition count, and fall back to an explicit `..._MEMORYLIMIT` if it isn't.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-self-managed

package/.llms/chunks/components.best-practices.architecture.sizing-self-managed.next-steps.md

@@ -0,0 +1,6 @@
+# Self-Managed resource planning — Next steps
+
+Validate your chosen configuration by [running your own benchmarks](https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-benchmarks).
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/sizing-self-managed