feat: add specific use cases

.vale/styles/Flipt/spelling-exceptions.txt

@@ -43,8 +43,10 @@ okta
 otlp
 performant
 PGBouncer
+pluggable
 postgres
 pprof
+Promtail
 protobuf
 protoc
 Quicksort
@@ -56,7 +58,9 @@ rollouts
 SCMs
 sdk
 sdks
+Splunk
 sqlite
+Turso
 unary
 uncomment
 uncompromised

authentication/overview.mdx

@@ -63,4 +63,4 @@ See the [Configuration: JWT Authentication](/configuration/authentication#json-w
 Currently, Flipt only supports authentication without any extended authorization capabilities.
 Authorization is something we're actively exploring and we will update this section as we settle on a design.
 
-We would appreciate your input into designing authorization. Head over to [our discord](https://flipt.io/discord) and let us know what you need from Flipt.
+We would appreciate your input into designing authorization. Head over to [our Discord](https://flipt.io/discord) and let us know what you need from Flipt.

configuration/observability.mdx

@@ -1,6 +1,6 @@
 ---
 title: Observability
-description: This document describes how to configure Flipt's observability mechanisms including metrics and tracing.
+description: This document describes how to configure Flipt's observability mechanisms including metrics, logging, and tracing.
 ---
 
 ## Metrics
@@ -34,6 +34,51 @@ We provide a set of [Grafana](https://grafana.com/) dashboards that you can use
 
 You can find the dashboards in our [grafana-dashboards](https://github.com/flipt-io/grafana-dashboards) repository.
 
+## Logging
+
+Flipt writes logs to STDOUT in two formats:
+
+- JSON
+- Console
+
+The format can be configured via the `log.encoding` configuration option.
+
+```yaml
+log:
+  encoding: json
+```
+
+For production deployments, we recommend using the JSON format as it's easier to parse and ingest into log aggregation systems such as Elasticsearch, Splunk, Loki, or DataDog.
+
+We've prepared an [example](https://github.com/flipt-io/flipt/tree/main/examples/audit/log) showing how to set up Flipt with Grafana Loki and Promtail to ingest and query logs.
+
+### JSON
+
+```json
+{
+  "L": "INFO",
+  "T": "2024-01-20T21:59:49-05:00",
+  "M": "finished unary call with code OK",
+  "server": "grpc",
+  "grpc.start_time": "2024-01-20T21:59:49-05:00",
+  "system": "grpc",
+  "span.kind": "server",
+  "grpc.service": "flipt.evaluation.EvaluationService",
+  "grpc.method": "Boolean",
+  "peer.address": "127.0.0.1:52635",
+  "grpc.code": "OK",
+  "grpc.time_ms": 0.146
+}
+```
+
+### Console
+
+```text
+2024-01-20T22:04:18-05:00	INFO	finished unary call with code OK	{"server": "grpc", "grpc.start_time": "2024-01-20T22:04:18-05:00", "system": "grpc", "span.kind": "server", "grpc.service": "flipt.evaluation.EvaluationService", "grpc.method": "Boolean", "peer.address": "127.0.0.1:53714", "grpc.code": "OK", "grpc.time_ms": 0.373}
+```
+
+More information about the available configuration options can be found in the [Logging configuration](/configuration/overview#logging) section.
+
 ## Tracing
 
 Flipt supports distributed tracing via the [OpenTelemetry](https://opentelemetry.io/) project.
@@ -42,7 +87,7 @@ Currently, we support the following tracing backends:
 
 - [Jaeger](https://www.jaegertracing.io/)
 - [Zipkin](https://zipkin.io/)
-- [OTLP](https://opentelemetry.io/docs/reference/specification/protocol/).
+- [OTLP](https://opentelemetry.io/docs/reference/specification/protocol/)
 
 Enable tracing via the values described in the [Tracing configuration](/configuration/overview#tracing) and point Flipt to your configured collector to record spans.
 

configuration/storage.mdx

@@ -5,14 +5,13 @@ description: This document describes how to configure Flipt's storage backend me
 
 ## Relational Database
 
-Flipt supports [SQLite](https://www.sqlite.org/index.html), [PostgreSQL](https://www.postgresql.org/), [CockroachDB](https://www.cockroachlabs.com/) and [MySQL](https://dev.mysql.com/) relational databases.
+Flipt supports the following relational databases:
 
-<Note>
-  As of [v1.29.0](https://github.com/flipt-io/flipt/releases/tag/v1.29.0), Flipt
-  also supports [libSQL](https://github.com/tursodatabase/libsql) which is a
-  fork of SQLite that can be accessed over a network via
-  [sqld](https://github.com/tursodatabase/libsql/tree/main/libsql-server).
-</Note>
+- [SQLite](https://www.sqlite.org/index.html)
+- [PostgreSQL](https://www.postgresql.org/)
+- [CockroachDB](https://www.cockroachlabs.com/)
+- [MySQL](https://dev.mysql.com/)
+- [LibSQL/Turso](https://turso.tech/)
 
 SQLite is enabled by default for simplicity, however, you should use PostgreSQL, MySQL, or CockroachDB if you intend to run multiple copies of Flipt in a high availability configuration.
 
@@ -22,8 +21,7 @@ The database connection can be configured as follows:
 
 <Note>
   The default location of the SQLite database is `/var/opt/flipt/flipt.db` on
-  Linux and `~/Library/Application Support/flipt/flipt.db` on macOS (since
-  v1.26.0).
+  Linux and `~/Library/Application Support/flipt/flipt.db` on macOS.
 </Note>
 
 ```yaml

mint.json

@@ -60,10 +60,18 @@
       "group": "Overview",
       "pages": [
         "introduction",
-        "usecases",
         "concepts"
       ]
     },
+    {
+      "group": "Use Cases",
+      "pages": [
+        "usecases/overview",
+        "usecases/cloudnative",
+        "usecases/edge",
+        "usecases/gitops"
+      ]
+    },
     {
       "group": "Self-Hosted",
       "pages": [

operations/architecture.mdx

@@ -48,10 +48,11 @@ the REST API.
 A guide to using the UI for the first time can be found in the
 [Getting Started](/introduction) documentation.
 
-## Database
+## Storage
 
-Flipt can be run with either SQLite, PostgreSQL, MySQL, or CockroachDB databases. The
-[Configuration](/configuration) documentation shows how to enable each database.
+Flipt can be run with a multitude of different databases and storage backends including non-traditional data stores like Git, OCI, S3, Azure, and Google Cloud Storage.
+
+See our [Storage](/configuration/storage) documentation for more information on all of the available storage backends.
 
 ## Technologies
 

usecases/cloudnative.mdx

@@ -0,0 +1,71 @@
+---
+title: CloudNative
+description: This document describes how Flipt thrives in a CloudNative environment.
+mode: wide
+---
+
+## Overview
+
+Flipt is a CloudNative feature flag solution. While Flipt can run in almost any environment, it is especially well suited for CloudNative environments.
+
+CloudNative means different things to different people. We define CloudNative as an environment that is:
+
+- **Containerized** - Flipt is distributed as a container image and can be deployed to any container orchestration platform.
+- **Dynamic** - Flipt is designed to be deployed and updated with minimal downtime.
+- **Scalable** - Flipt is designed to scale horizontally and vertically.
+- **Observable** - Flipt is designed to be observable. It exposes Prometheus metrics and logs in a structured format.
+- **Stateless** - Flipt is designed to be stateless. It supports multiple storage backends, including cloud object storage and SQL databases.
+
+## Kubernetes and Helm
+
+Flipt is mainly distributed as a container image. While it is a single binary and can run easily on bare metal, most users choose to deploy Flipt to a container orchestration platform such as Kubernetes.
+
+To deploy Flipt to Kubernetes, use our Helm chart as described in our [Kubernetes](/self-hosted/kubernetes) documentation.
+
+Flipt also integrates directly with Kubernetes service account tokens for authentication. This allows services deployed into the same Kubernetes cluster as Flipt to automatically gain authenticated access to the Flipt API without additional management of static client tokens.
+
+See our [Kubernetes Authentication](/authentication/methods#kubernetes) documentation for more information on how to configure Kubernetes service account authentication.
+
+## Metrics and Observability
+
+### Metrics
+
+Flipt exposes Prometheus metrics on the `/metrics` endpoint. These metrics are designed to be scraped by Prometheus and visualized in external tools such as Grafana.
+
+See the [Metrics Configuration](/configuration/observability#metrics) documentation for more information on the metrics exposed by Flipt and how to configure them.
+
+### Logging
+
+Flipt writes structured logs in JSON format. These logs are designed to be ingested by external log aggregation tools such as Elasticsearch, Splunk, and Grafana Loki.
+
+For more information on the logs exposed by Flipt and how to configure them, see the [Logging Configuration](/configuration/observability#logging) documentation.
+
+### Tracing
+
+Flipt exposes tracing information in the OpenTelemetry format. This allows you to trace requests through Flipt and into your application. Flipt also annotates the traces with information such as the feature flag and variant that was evaluated.
+
+For more information on the tracing exposed by Flipt and how to configure it, see the [Tracing Configuration](/configuration/observability#tracing) documentation.
+
+## Storage
+
+Flipt is designed to be stateless. It supports multiple storage backends, including cloud object storage, git, OCI, and SQL databases.
+
+Our [declarative storage](/configuration/storage#declarative) also allows you to easily migrate between storage backends. For example, you can start with a local SQLite database and migrate to a cloud object storage backend as your usage grows.
+
+## Security and Performance
+
+### Security
+
+Flipt supports multiple authentication methods, including static tokens, Kubernetes service account tokens, JWT, and OIDC.
+
+See our [Authentication](/authentication) documentation for more information on the authentication methods supported by Flipt.
+
+### Performance
+
+Flipt is written in Go and is designed to be performant. It's horizontally scalable and can be deployed to multiple replicas to handle increased load.
+
+Flipt also supports caching of feature flag evaluations. This allows you to cache the results of feature flag evaluations in memory to reduce the load on your storage backend.
+
+Finally, Flipt's GRPC API is meant to be used in a cloud environment such as Kubernetes. This allows you to deploy Flipt in the same Kubernetes cluster as your applications and take advantage of the low latency and high throughput of the Kubernetes network.
+
+See our [Architecture](/operations/architecture) and [Deployment](/operations/deployment) documentation for more information on how to deploy Flipt for performance and scalability.

usecases/edge.mdx

@@ -0,0 +1,50 @@
+---
+title: Edge/IoT
+description: This document describes how Flipt can be used in edge and IoT computing environments.
+mode: wide
+---
+
+## Overview
+
+Flipt is designed to be able to be used in an edge computing environment. This means that Flipt can be deployed to a device that's close to the end user. This is in contrast to a centralized computing environment where the application is deployed to a data center that's far away from the end user, such as a cloud provider.
+
+Because of Flipt's small footprint and single binary deployment, it's well suited for edge computing environments. Also, since the Flipt server is stateless, it can be deployed in a highly available configuration. This means that multiple Flipt servers can be deployed to the edge and requests can be load balanced across them, providing a highly available service to the end user.
+
+Our [Deployment](/operations/deployment) documentation provides more information on how to deploy Flipt in a highly available configuration.
+
+## Storage
+
+Flipt supports a variety of storage backends, allowing it to be deployed to a variety of edge computing environments.
+
+### Edge-Compatible Databases
+
+Flipt's pluggable data store architecture allows it to be deployed to a variety of edge computing environments without requiring traditional server-based relational databases. Specifically, Flipt's support for SQLite, [LibSQL](https://turso.tech/libsql), and [Turso](https://turso.tech/) allow it to run in environments where a traditional database is not available.
+
+See the [Database Support](/configuration/storage##relational-database) section for more information on Flipt's relational database support.
+
+### Declarative Storage
+
+Flipt's declarative storage backends allow it to run without a database at all. Flipt can be configured to load its feature flag data in the following ways:
+
+- From a file on the local filesystem
+- From a remote git repository
+- From an OCI compliant container image registry
+- From any of the 3 major cloud computing object storage services (AWS, Google Cloud, and Azure)
+
+These backends allow you to deploy Flipt to the edge and evaluate feature flags close to your end user.
+
+See the [Declarative Storage](/configuration/storage#declarative) section for more information on Flipt's declarative storage backends.
+
+## GRPC API
+
+GRPC is a high performance, open source, universal RPC framework. Flipt's GRPC API allows it to run in environments where HTTP isn't available or practical. This is especially useful in environments that require low latency and high throughput, such as IoT devices.
+
+See our [Architecture](/operations/architecture) section for more information on Flipt's GRPC API and overall architecture.
+
+## Client Side Evaluation
+
+Flipt's client-side evaluation SDKs allow feature flag evaluation to be performed directly from edge clients, without the need of making evaluation requests to the central Flipt server. This is especially useful in environments where the edge client isn't always connected to the internet, such as IoT devices.
+
+Client side evaluation has shown to be up to 1000x faster than traditional server side evaluation, and as such greatly decreases the number of network requests required. This is especially useful in environments where network bandwidth is limited (such as IoT devices), where there is sensitivity to latency (e.g. high throughput services), or on critical paths where transient failures must be avoided at all costs (e.g. during transaction processing).
+
+See our [Client Side Integration](/integration/client) documentation for more information.

usecases/gitops.mdx

@@ -0,0 +1,40 @@
+---
+title: GitOps
+description: This document describes how Flipt can be used with GitOps workflows
+mode: wide
+---
+
+## Overview
+
+GitOps is a way to do Continuous Delivery, it works by using Git as a single source of truth for declarative infrastructure and applications. With Git at the center of your delivery pipelines, developers can make pull requests to accelerate and simplify application deployments.
+
+Flipt is uniquely suited to work with GitOps workflows because of our declarative backends and ability to be configured completely via YAML, or JSON.
+
+We believe that feature flags are a form of configuration and should be treated as such. This means that feature flags should be able to be stored in the same repository as the code that uses them. This allows developers to make changes to both the code and the feature flags in the same pull request. This also allows developers to use the same GitOps tooling to deploy both their code and their feature flags to production.
+
+## Git Backend
+
+Flipt's declarative storage backends allow it to run without a database at all. Flipt can be configured to load its feature flag data in the following ways:
+
+- From a file on the local filesystem
+- From a remote **git repository**
+- From an OCI compliant container image registry
+- From from any of the 3 major cloud computing object storage services (AWS, Google Cloud, and Azure)
+
+Our git support enables you to evaluate feature flags across different branches and tags. This allows developers to test feature flags in a staging environment before merging them into production, or leverage preview environments to test feature flags in isolation.
+
+Read our [Get Going with GitOps](https://www.flipt.io/docs/guides/get-going-with-gitops) guide to learn how to get started with GitOps and Flipt.
+
+## CI/CD Integration
+
+Our [GitHub Action](/tooling/github-actions) allows you to easily integrate Flipt into your CI/CD pipelines. This allows you to install Flipt into your CI pipeline and run tests against your feature flags before deploying your code to production.
+
+You can either import your feature flag data from your repository into Flipt using our [Import Command](/cli/commands/import) or run Flipt over your repository directly using our [Local storage](/configuration/storage#local-2) backend.
+
+This allows you to import your feature flag data into Flipt before running your tests.
+
+## Validation
+
+Flipt's [Validate Command](/cli/commands/validate) allows you to validate your feature flag data against a schema. This allows you to ensure that your feature flag data is valid before deploying it to production. This is especially useful when using Flipt with GitOps workflows because it allows you to catch errors in your configuration in the CI stage.
+
+You can also add your own custom validation rules to the schema to ensure that your feature flag data is valid for your specific use case.

usecases.mdx → usecases/overview.mdx

@@ -1,9 +1,15 @@
 ---
-title: Use Cases
-description: This document describes some of the use cases for Flipt and feature flags in general.
+title: Overview
+description: This document describes some of the general use cases for Flipt and feature flags.
 mode: wide
 ---
 
+For more specific use cases that Flipt is suited for, see the following sections:
+
+- [CloudNative](/usecases/cloudnative/)
+- [Edge/IoT](/usecases/edge/)
+- [GitOps](/usecases/gitops/)
+
 ## Enhanced Development Experience
 
 Feature flags are extremely versatile and can quickly become an important tool in a developer’s toolbox. Some of the ways they can be used to enhance the development experience include: