From 7c6158acd82217507eb78a9864dd5e496b8429f0 Mon Sep 17 00:00:00 2001 From: Jakob Holmgren Date: Wed, 13 May 2026 16:29:49 +0200 Subject: [PATCH] docs: add topology-based project structure decision tree Closes #7507. --- .../best-practices/structuring-your-projects.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/docs/best-practices/structuring-your-projects.md b/docs/docs/best-practices/structuring-your-projects.md index 9a642bce3e08..2863bdc0b9ff 100644 --- a/docs/docs/best-practices/structuring-your-projects.md +++ b/docs/docs/best-practices/structuring-your-projects.md @@ -16,6 +16,19 @@ Before diving into recommendations, it's helpful to understand how Flagsmith org For more details, see the [Data Model](/flagsmith-concepts/data-model) documentation. +## Decision tree: pick a structure by topology + +Most decisions land cleanly when you look at how your business products and teams map to Flagsmith. + +| Your topology | Recommended structure | +|---|---| +| Single business product, multiple surfaces (web + mobile + backend) | **Single project** — one shared source of truth across surfaces. Use tags, naming conventions, and tag-based RBAC to manage scope within it. | +| Multiple distinct business products under one organisation | **One project per business product.** Each product gets its own list of features and its own access boundary. | +| Independent service teams with no shared product context | **Split by team ownership.** Easy to refactor later via flag export between projects. | +| Default when uncertain | **Bias toward fewer projects.** Splitting later is reversible. Merging is harder. | + +The sections below explore the trade-offs in more depth. + ## When to create separate projects Consider creating separate projects when: