Documentation: Flagsmith Concepts section

docs/docs/flagsmith-concepts/_category_.json

@@ -0,0 +1,5 @@
+{
+    "label": "Flagsmith Concepts",
+    "position": 4,
+    "collapsed": true
+}

docs/docs/flagsmith-concepts/data-model.md

@@ -0,0 +1,53 @@
+---
+title: Data Model
+sidebar_label: Data Model
+sidebar_position: 10
+---
+
+Flagsmith uses a flexible data model to help you manage feature flags and remote configurations across multiple projects, environments, and user groups.
+
+Here's a high-level overview of the Flagsmith data model. 
+
+![Image](/img/flagsmith-model.svg)
+
+## Key Concepts
+
+Below you'll find a quick explanation of the main building blocks that make up the Flagsmith data model.
+
+### Organisations
+
+Organisations allow you and other team members to manage projects and their features. A user can be a member of multiple organisations.
+
+### Projects
+
+Projects contain one or more environments that share a single set of features. Organisations can have any number of projects.
+
+### Environments
+
+Environments are a way to separate the configuration of your features. For example, a feature might be enabled in your project's Development and Staging environments but turned off in your Production environment. A project can have any number of environments.
+
+### Features
+
+Features are shared across all environments within a project, but their values/states can be modified per environment. Features can be toggled on/off or assigned values (e.g., string, integer, boolean, or multivariate values).
+
+### Identities
+
+Identities are individual users associated with each environment. Registering identities within the client application allows you to manage features for individual users. Identity features can be overridden from your environment defaults. For example, [email protected] would be a different identity in your development environment to the one in production, and they can have different features enabled for each environment.
+
+For more information, see [Identities](/basic-features/managing-identities).
+
+### Traits
+
+You can store any number of traits against an identity. Traits are key-value pairs that can store any type of data. Some examples of traits that you might store against an identity include:
+- The number of times the user has logged in.
+- Whether they have accepted the application terms and conditions.
+Their theme preference (eg. dark mode)
+- Whether they have performed certain actions within your application.
+
+For more information, see [Traits](/basic-features/managing-identities.md#identity-traits).
+
+### Segments
+
+Segments define a group of users by traits such as login count, device, location, or any number of custom-defined traits. Similar to individual users, you can override environment defaults for features for a segment. For example, you might show certain features for a "power user" segment.
+
+For more information, see [Segments](/basic-features/segments.md).

docs/docs/flagsmith-concepts/identities.md

@@ -0,0 +1,109 @@
+---
+title: Identities
+sidebar_label: Identities
+sidebar_position: 30
+---
+
+Feature flags are great, but they can be a very blunt tool, only allowing you to enable or disable flags across your entire user base. In order to target users more precisely, and to be able to perform [staged feature roll-outs](/guides-and-examples/staged-feature-rollouts.md) or [A/B and multivariate tests](/advanced-use/ab-testing.md), you need to _identify your users_.
+
+Identities are created within Flagsmith automatically the first time they are identified from your client SDKs. Generally, you would make a call to identify a user with a unique string or identifier whenever they log into your application or site. The SDK will then send an API message to the Flagsmith API, with the relevant identity information.
+
+:::tip
+
+The SDK part of the Flagsmith API is public by design; the environment key is intended to be public. When identifying users, it is important to use an identity value that is not easy to guess. For example, if you used an incrementing integer to identify your users, it would be trivial to request identities by enumerating this integer. This would effectively provide public access to any user traits that are associated with users.
+
+We strongly recommend using an unguessable, unidentifiable identity key, such as a [GUID](https://en.wikipedia.org/wiki/Universally_unique_identifier), when identifying your users, to prevent unintentionally leaking identity trait data.
+
+:::
+
+## Identity Overrides
+
+Once you have uniquely identified a user, you can then override features for that user from your environment defaults. For example, you've pushed a feature into production, but the relevant feature flag is still hiding that feature from all of your users. You can now override that flag for your own user, and test that feature. Once you are happy with everything, you can roll that feature out to all of your users by enabling the flag itself.
+
+Identities are specific and individual for each environment within your project. For example, [email protected] would be a different identity in your development environment to the one in production, and they can have different features enabled for each environment.
+
+## Identity Feature Flags
+
+By default, identities receive the default flags for their environment. The main use-case for identities is to be able to override flags and configs on a per-identity basis. You can do this by navigating to the users page, finding the user
+and modifying their flags.
+
+## Identity Traits
+
+You can also use Flagsmith to store 'traits' against identities. traits are key/value pairs that are associated with individual identities for a particular environment. traits have two purposes outlined below, but the main use case is to drive [segments](./segments).
+
+:::important
+
+The maximum size of each individual trait value is **_2000 bytes_**. You cannot store more data than that in a single trait, and the API will return a 500 error if you try to do so.
+
+:::
+
+### Using Traits to Drive Segments
+
+Let's say you are working on a mobile app, and you want to control a feature based on the version of the application that the identity is using. When you integrate the Flagsmith SDK, you would pass the application version number to the Flagsmith platform as a trait key/value pair:
+
+```java
+String identifier = "user_512356"
+Map<String, Object> traits = new HashMap<String, Object>();
+traits.put("app_version", YourApplication.getVersion());
+
+Flags flags = flagsmith.getIdentityFlags(identifier, traits);
+```
+
+Here we are setting the trait key `app_version` with the value of `YourApplication.getVersion()`.You can now create a [segment](./segments) that is based on the application version and manage features based on the application version.
+
+Traits are completely free-form. You can store any number of traits, with any relevant information you see fit, in the platform and then use segments to control features based on these trait values.
+
+## Identity and Trait Storage
+
+Identities are persisted within the Flagsmith platform, along with any traits that have been assigned to them. When flags are evaluated for an identity, the full complement of traits stored within the platform are used, even if they were not all sent as part of the request.
+
+This can be useful if, at runtime, your application does not have all the relevant trait data available for that particular identity; any traits provided will be combined with the traits stored within Flagsmith before the evaluation engine runs.
+
+There are some [exceptions to this rule](/clients#server-side-sdks) with Server-side SDKs running in local evaluation mode.
+
+:::info
+
+Note that, when using our SaaS platform, there might be a short delay from the initial request to write or update traits for an identity and them being used in subsequent evaluations.
+
+:::
+
+### Using Traits as a Data-store
+
+Traits can also be used to store additional data about your users that would be cumbersome to store within your application. Some possible uses for traits could be:
+
+- Storing whether the user has accepted a new set of terms and conditions.
+- Storing the last viewed page of the application so that you can resume the users place later, across any device.
+
+Generally if they are lower-value pieces of information about your user, it might be simpler/easier to store them in Flagsmith rather than in your core application.
+
+Traits are stored natively as either numbers, strings or booleans.
+
+## Traits Powering Segments
+
+Traits can be used within your application, but they can also be used to power [segments](/basic-features/segments.md).
+
+## Trait Value Data Types
+
+:::tip
+
+You can remove a trait by sending `null` as the trait value.
+
+:::
+
+Trait values can be stored as one of four different data types:
+
+- Boolean
+- String (max length 2000 bytes)
+- Int (32 bit signed)
+- Float (typically has a range of around 1E-307 to 1E+308 with a precision of at least 15 digits)
+
+If you need to store 64 bit integers or very high precision floats we suggest storing them as strings and then doing the type conversion within the SDK.
+
+## Bulk Uploading Identities and Traits
+
+Identities are lazily created within Flagsmith. There might be instances where you want to push identity and trait data into the platform outside of a user session. We have a [code example for this](/clients/rest#bulk-uploading-identities-and-traits).
+
+For more information, see:
+
+- [Managing identities](/basic-features/managing-identities)
+

docs/docs/flagsmith-concepts/platform-architecture.md

@@ -0,0 +1,60 @@
+---
+title: Platform Architecture
+sidebar_label: Platform Architecture
+sidebar_position: 20
+---
+
+# Flagsmith Platform Architecture
+
+Flagsmith architecture supports a range of deployment models to suit different organisational needs, from fully managed SaaS to self-hosted and on-premises solutions.
+
+## Conceptual Overview
+
+The most important components in Flagsmith's architecture are:
+
+- **Frontend dashboard**: A web interface for managing projects, environments, feature flags, and user permissions. This is where most configuration and management tasks are performed.
+- **Core API**: RESTful API that powers the dashboard and SDKs. These endpoints are used for automation, integrations, and direct management of Flagsmith resources.
+- **Edge API**: A globally distributed API for low-latency flag evaluation, especially useful for applications with users around the world.
+- **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.
+
+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.
+
+## 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:
+
+### 1. SaaS (Cloud-Hosted)
+
+- **Managed by Flagsmith**: No infrastructure to manage; get started instantly.
+- **Automatic scaling, security, and updates**: All handled by the Flagsmith team.
+- **Global Edge API**: Provides low-latency flag delivery worldwide.
+- **Best for**: Teams who wish to focus on product development and avoid infrastructure overhead.
+
+![SaaS Architecture](/img/saas-architecture.svg)
+
+*The diagram above shows the SaaS deployment model, where all infrastructure is managed by Flagsmith and the Edge API ensures global low-latency delivery.*
+
+### 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.
+- **Full control**: You manage scaling, security, updates, and integrations.
+- **Customisation**: Integrate with your own authentication, analytics, and infrastructure.
+- **Best for**: Teams with specific compliance, data residency, or custom integration requirements.
+
+### 3. On-Premises (Enterprise Edition)
+
+- **Deployed in your private data centre or isolated cloud**: For maximum control and data sovereignty.
+- **Enterprise features**: Advanced authentication (Okta, LDAP, SAML, ADFS), custom fields, support for additional databases (Oracle, MySQL), and more.
+- **Orchestration support**: Kubernetes, OpenShift, AWS ECS, GCP AppEngine, Azure Container Instances, and more.
+- **Best for**: Organisations with strict regulatory, security, or data sovereignty requirements.
+
+![Self-Hosted / On-Prem Architecture](/img/architecture.svg)
+
+*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.*
+
+## What's next
+- [Deployment Options](/deployment)
+- [Version Comparison](/version-comparison)
+- [Enterprise Edition](/deployment/configuration/enterprise-edition)