From acd626b44d3faa58c11ae179b93e960446562c16 Mon Sep 17 00:00:00 2001 From: Gagan Trivedi Date: Wed, 14 Oct 2026 15:29:23 +0530 Subject: [PATCH 1/4] docs(experimentation): add experimentation architecture to platform architecture page --- .../platform-architecture.md | 22 ++++++ .../img/experimentation-architecture.svg | 71 +++++++++++++++++++ 2 files changed, 93 insertions(+) create mode 100644 docs/static/img/experimentation-architecture.svg diff --git a/docs/docs/flagsmith-concepts/platform-architecture.md b/docs/docs/flagsmith-concepts/platform-architecture.md index 89f54272b6f8..d1b12ab86bad 100644 --- a/docs/docs/flagsmith-concepts/platform-architecture.md +++ b/docs/docs/flagsmith-concepts/platform-architecture.md @@ -18,9 +18,31 @@ The most important components in Flagsmith's architecture are: - **SDKs**: Client libraries (available for many languages and platforms) that connect your applications and services to Flagsmith, enabling real-time feature flag evaluation and remote configuration. - **Integrations**: Optional connectors to third-party tools and services (e.g., analytics, notifications, monitoring). These can be configured via the dashboard or API. - **Database**: Stores all persistent data, such as organisations, projects, features, and audit logs. Managed by Flagsmith in SaaS, but by your team in self-hosted/on-prem deployments. +- **Ingestion server and Kafka**: Receive experiment events from SDKs and hold them until they are delivered to a warehouse. +- **Warehouse**: Stores experiment events and serves the queries behind experiment results. The architecture is REST-based, with both SDK clients and the dashboard interacting with the Core API. The platform is designed to be cloud-native, supporting containerisation and orchestration for scalability and reliability. +## Experimentation Architecture + +[Experiments](/experimentation) need exposure and conversion events from your application. These travel through a separate event pipeline into a data warehouse, where the Core API queries them to compute experiment results. + +![Experimentation Architecture](/img/experimentation-architecture.svg) + +*The diagram above shows how experiment events flow from your application to the warehouse, and how the Core API reads results back.* + +| Component | Role | +| --- | --- | +| Ingestion server | Checks each event batch's environment key, validates the events, and writes them to Kafka. | +| Kafka | Holds events between ingestion and delivery, so a slow or unavailable warehouse does not lose events. | +| Warehouse delivery | Inserts events into each environment's warehouse, retries failed inserts, and records delivery status. | +| Warehouse | Stores events. The Core API queries it for experiment results. | + +How this differs by deployment model: + +- **SaaS**: Flagsmith runs the whole pipeline, including a managed ClickHouse warehouse that reads events directly from Kafka. You can also connect your own warehouse. +- **Self-hosted**: You run the ingestion server, Kafka and warehouse delivery, and connect each environment to a warehouse you run. See [Connect a Warehouse](/experimentation/connect-a-warehouse) for supported warehouses. + ## Deployment Models Flagsmith can be deployed in three main ways, each with conceptual differences in management, control, and responsibility. The following diagrams illustrate the architecture for each model: diff --git a/docs/static/img/experimentation-architecture.svg b/docs/static/img/experimentation-architecture.svg new file mode 100644 index 000000000000..183fd595ce53 --- /dev/null +++ b/docs/static/img/experimentation-architecture.svg @@ -0,0 +1,71 @@ + + + + + + + + + + + + Flagsmith event infrastructure + + + + Your application + Flagsmith SDK + + + Ingestion server + validates events + + + Kafka + buffers events + + + Warehouse delivery + inserts and retries + + + Warehouse + SaaS: Flagsmith-managed ClickHouse + Self-hosted: your own warehouse + + + + Postgres + Flagsmith database + + + Dashboard + + + Core API + + + + + + + + + + + + + + + + + events + insert + managed warehouse reads Kafka directly (SaaS) + environment-key + lookup + warehouse connections, + delivery status + experiment results queries + + From 9d7dc39ba7cad0fd714214c64a47880a3717343b Mon Sep 17 00:00:00 2001 From: Gagan Trivedi Date: Wed, 14 Oct 2026 15:35:23 +0530 Subject: [PATCH 2/4] docs(experimentation): move experimentation into deployment models with SaaS and self-hosted diagrams --- .../platform-architecture.md | 42 +++++----- .../img/experimentation-architecture-saas.svg | 78 +++++++++++++++++++ ...erimentation-architecture-self-hosted.svg} | 9 +-- 3 files changed, 101 insertions(+), 28 deletions(-) create mode 100644 docs/static/img/experimentation-architecture-saas.svg rename docs/static/img/{experimentation-architecture.svg => experimentation-architecture-self-hosted.svg} (85%) diff --git a/docs/docs/flagsmith-concepts/platform-architecture.md b/docs/docs/flagsmith-concepts/platform-architecture.md index d1b12ab86bad..20b39eefce06 100644 --- a/docs/docs/flagsmith-concepts/platform-architecture.md +++ b/docs/docs/flagsmith-concepts/platform-architecture.md @@ -18,31 +18,13 @@ The most important components in Flagsmith's architecture are: - **SDKs**: Client libraries (available for many languages and platforms) that connect your applications and services to Flagsmith, enabling real-time feature flag evaluation and remote configuration. - **Integrations**: Optional connectors to third-party tools and services (e.g., analytics, notifications, monitoring). These can be configured via the dashboard or API. - **Database**: Stores all persistent data, such as organisations, projects, features, and audit logs. Managed by Flagsmith in SaaS, but by your team in self-hosted/on-prem deployments. -- **Ingestion server and Kafka**: Receive experiment events from SDKs and hold them until they are delivered to a warehouse. -- **Warehouse**: Stores experiment events and serves the queries behind experiment results. +- **Ingestion server**: Receives [experiment](/experimentation) events (exposures and conversions) from SDKs, checks each batch's environment key, validates the events, and writes them to Kafka. +- **Kafka**: Holds experiment events between ingestion and delivery, so a slow or unavailable warehouse does not lose events. +- **Warehouse delivery**: Inserts experiment events into each environment's warehouse, retries failed inserts, and records delivery status. +- **Warehouse**: Stores experiment events. The Core API queries it to compute experiment results. The architecture is REST-based, with both SDK clients and the dashboard interacting with the Core API. The platform is designed to be cloud-native, supporting containerisation and orchestration for scalability and reliability. -## Experimentation Architecture - -[Experiments](/experimentation) need exposure and conversion events from your application. These travel through a separate event pipeline into a data warehouse, where the Core API queries them to compute experiment results. - -![Experimentation Architecture](/img/experimentation-architecture.svg) - -*The diagram above shows how experiment events flow from your application to the warehouse, and how the Core API reads results back.* - -| Component | Role | -| --- | --- | -| Ingestion server | Checks each event batch's environment key, validates the events, and writes them to Kafka. | -| Kafka | Holds events between ingestion and delivery, so a slow or unavailable warehouse does not lose events. | -| Warehouse delivery | Inserts events into each environment's warehouse, retries failed inserts, and records delivery status. | -| Warehouse | Stores events. The Core API queries it for experiment results. | - -How this differs by deployment model: - -- **SaaS**: Flagsmith runs the whole pipeline, including a managed ClickHouse warehouse that reads events directly from Kafka. You can also connect your own warehouse. -- **Self-hosted**: You run the ingestion server, Kafka and warehouse delivery, and connect each environment to a warehouse you run. See [Connect a Warehouse](/experimentation/connect-a-warehouse) for supported warehouses. - ## Deployment Models Flagsmith can be deployed in three main ways, each with conceptual differences in management, control, and responsibility. The following diagrams illustrate the architecture for each model: @@ -58,6 +40,14 @@ Flagsmith can be deployed in three main ways, each with conceptual differences i *The diagram above shows the SaaS deployment model, where all infrastructure is managed by Flagsmith and the Edge API ensures global low-latency delivery.* +#### Experimentation on SaaS + +Flagsmith runs the whole experimentation pipeline. By default, experiment events are stored in a Flagsmith-managed ClickHouse warehouse, which reads them directly from Kafka. Environments can instead connect their own warehouse, in which case warehouse delivery inserts their events into it. + +![SaaS Experimentation Architecture](/img/experimentation-architecture-saas.svg) + +*The diagram above shows how experiment events flow on SaaS, to the managed warehouse or to your own.* + ### 2. Self-Hosted (Cloud or Private Cloud) - **Managed by your team**: Deploy Flagsmith on your own cloud infrastructure (e.g., AWS, GCP, Azure, DigitalOcean) using Docker, Kubernetes, or other orchestration tools. @@ -76,6 +66,14 @@ Flagsmith can be deployed in three main ways, each with conceptual differences i *The diagram above illustrates the Self-Hosted and On-Premises deployment models, where your team manages the infrastructure and has full control over security, compliance, and integrations.* +#### Experimentation on Self-Hosted and On-Premises + +Your team runs the ingestion server, Kafka and warehouse delivery alongside the Core API. There is no managed warehouse: each environment connects to a warehouse you run, and warehouse delivery inserts its events into it. See [Connect a Warehouse](/experimentation/connect-a-warehouse) for supported warehouses. + +![Self-Hosted Experimentation Architecture](/img/experimentation-architecture-self-hosted.svg) + +*The diagram above shows how experiment events flow on Self-Hosted and On-Premises deployments, where every component, including the warehouse, is run by your team.* + ## What's next - [Deployment Options](/deployment-self-hosting) - [Version Comparison](https://flagsmith.com/pricing) diff --git a/docs/static/img/experimentation-architecture-saas.svg b/docs/static/img/experimentation-architecture-saas.svg new file mode 100644 index 000000000000..564e354a39d2 --- /dev/null +++ b/docs/static/img/experimentation-architecture-saas.svg @@ -0,0 +1,78 @@ + + + + + + + + + + + + + Event pipeline, run by Flagsmith + + + + Your application + Flagsmith SDK + + + Ingestion server + validates events + + + Kafka + buffers events + + + Warehouse delivery + inserts and retries + + + + Managed warehouse + Flagsmith-run ClickHouse (default) + + + Your warehouse + optional, per environment + + + + Postgres + Flagsmith database + + + Dashboard + + + Core API + + + + + + + + + + + + + + + + + + events + insert + reads Kafka directly + environment-key + lookup + warehouse connections, + delivery status + experiment results queries + + + diff --git a/docs/static/img/experimentation-architecture.svg b/docs/static/img/experimentation-architecture-self-hosted.svg similarity index 85% rename from docs/static/img/experimentation-architecture.svg rename to docs/static/img/experimentation-architecture-self-hosted.svg index 183fd595ce53..add5eb462913 100644 --- a/docs/static/img/experimentation-architecture.svg +++ b/docs/static/img/experimentation-architecture-self-hosted.svg @@ -9,7 +9,7 @@ - Flagsmith event infrastructure + Event pipeline, run by your team @@ -29,9 +29,8 @@ inserts and retries - Warehouse - SaaS: Flagsmith-managed ClickHouse - Self-hosted: your own warehouse + Your warehouse + connected per environment @@ -50,7 +49,6 @@ - @@ -61,7 +59,6 @@ events insert - managed warehouse reads Kafka directly (SaaS) environment-key lookup warehouse connections, From 24b8f8b925bcfcca2b87e72e8f2d3d644fddb2ee Mon Sep 17 00:00:00 2001 From: Gagan Trivedi Date: Wed, 14 Oct 2026 15:58:39 +0530 Subject: [PATCH 3/4] docs(experimentation): tighten component descriptions and warehouse wording --- .../docs/flagsmith-concepts/platform-architecture.md | 12 ++++++------ .../static/img/experimentation-architecture-saas.svg | 4 ++-- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/docs/flagsmith-concepts/platform-architecture.md b/docs/docs/flagsmith-concepts/platform-architecture.md index 20b39eefce06..cf923b4d0326 100644 --- a/docs/docs/flagsmith-concepts/platform-architecture.md +++ b/docs/docs/flagsmith-concepts/platform-architecture.md @@ -18,10 +18,10 @@ The most important components in Flagsmith's architecture are: - **SDKs**: Client libraries (available for many languages and platforms) that connect your applications and services to Flagsmith, enabling real-time feature flag evaluation and remote configuration. - **Integrations**: Optional connectors to third-party tools and services (e.g., analytics, notifications, monitoring). These can be configured via the dashboard or API. - **Database**: Stores all persistent data, such as organisations, projects, features, and audit logs. Managed by Flagsmith in SaaS, but by your team in self-hosted/on-prem deployments. -- **Ingestion server**: Receives [experiment](/experimentation) events (exposures and conversions) from SDKs, checks each batch's environment key, validates the events, and writes them to Kafka. -- **Kafka**: Holds experiment events between ingestion and delivery, so a slow or unavailable warehouse does not lose events. -- **Warehouse delivery**: Inserts experiment events into each environment's warehouse, retries failed inserts, and records delivery status. -- **Warehouse**: Stores experiment events. The Core API queries it to compute experiment results. +- **Ingestion server**: A web service that receives events from SDKs (e.g. for [experimentation](/experimentation)) and writes them to Kafka. +- **Kafka**: Message bus used to reliably deliver events to the warehouse. +- **Warehouse delivery**: Inserts events into each environment's warehouse, retries failed inserts, and records delivery status. +- **Warehouse**: Analytical database that stores events and runs the aggregations the Core API requests. The architecture is REST-based, with both SDK clients and the dashboard interacting with the Core API. The platform is designed to be cloud-native, supporting containerisation and orchestration for scalability and reliability. @@ -42,7 +42,7 @@ Flagsmith can be deployed in three main ways, each with conceptual differences i #### Experimentation on SaaS -Flagsmith runs the whole experimentation pipeline. By default, experiment events are stored in a Flagsmith-managed ClickHouse warehouse, which reads them directly from Kafka. Environments can instead connect their own warehouse, in which case warehouse delivery inserts their events into it. +Flagsmith runs the whole experimentation pipeline. Events go to the Flagsmith-managed ClickHouse warehouse directly from Kafka, or to your own warehouse through warehouse delivery. ![SaaS Experimentation Architecture](/img/experimentation-architecture-saas.svg) @@ -68,7 +68,7 @@ Flagsmith runs the whole experimentation pipeline. By default, experiment events #### Experimentation on Self-Hosted and On-Premises -Your team runs the ingestion server, Kafka and warehouse delivery alongside the Core API. There is no managed warehouse: each environment connects to a warehouse you run, and warehouse delivery inserts its events into it. See [Connect a Warehouse](/experimentation/connect-a-warehouse) for supported warehouses. +Your team runs the ingestion server, Kafka and warehouse delivery alongside the Core API. Events go to your own warehouse through warehouse delivery. See [Connect a Warehouse](/experimentation/connect-a-warehouse) for supported warehouses. ![Self-Hosted Experimentation Architecture](/img/experimentation-architecture-self-hosted.svg) diff --git a/docs/static/img/experimentation-architecture-saas.svg b/docs/static/img/experimentation-architecture-saas.svg index 564e354a39d2..8cb4748257f1 100644 --- a/docs/static/img/experimentation-architecture-saas.svg +++ b/docs/static/img/experimentation-architecture-saas.svg @@ -32,11 +32,11 @@ Managed warehouse - Flagsmith-run ClickHouse (default) + Flagsmith-run ClickHouse Your warehouse - optional, per environment + e.g. your own ClickHouse From 0f13cc9bcbd2871ae58d50602d24ef476d096b90 Mon Sep 17 00:00:00 2001 From: Gagan Trivedi Date: Wed, 14 Oct 2026 16:05:01 +0530 Subject: [PATCH 4/4] docs(experimentation): remove stale note that results are only served from the managed warehouse --- docs/docs/experimentation/connect-a-warehouse.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/docs/experimentation/connect-a-warehouse.md b/docs/docs/experimentation/connect-a-warehouse.md index ad8fa891c2f0..6037c63ab9a6 100644 --- a/docs/docs/experimentation/connect-a-warehouse.md +++ b/docs/docs/experimentation/connect-a-warehouse.md @@ -106,9 +106,6 @@ Instead of the managed Flagsmith warehouse, you can store experiment events in y Connections use the ClickHouse HTTP(S) interface, with TLS enabled by default. -Experiment results and exposure queries are currently computed from the managed Flagsmith warehouse; serving results -directly from your own ClickHouse instance is not supported yet. - ## Coming soon Bring your own warehouse: connections for **Snowflake**, **BigQuery** and **Databricks**, so experiment results are