> ## Documentation Index
> Fetch the complete documentation index at: https://docs.foff.twospoon.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Scopes: grouping Foff flags by shared hierarchy model

> Scopes group feature flags that share the same resolution hierarchy. Learn when to use one scope versus many, with a concrete employee-tool example.

A scope is a logical grouping of feature flags that all resolve using the same hierarchy model. If every flag in a set of flags follows the same chain of levels — for example, `Country → State → City → User` — those flags belong in one scope. When your application has multiple distinct hierarchy types, you create a separate scope for each one.

## Why scopes exist

Foff resolves flag values by walking up a hierarchy you provide at query time. For resolution to work correctly, all flags queried together must share the same hierarchy structure. Scopes enforce that guarantee: every flag inside a scope uses the same ordered hierarchy levels.

## Concrete example

Suppose you are building an internal company tool. Your access model organizes users like this:

```
Company → Department → Team → User
```

You create one scope — call it `employee-hierarchy` — and define all flags that apply to this structure inside it. When your app queries Foff for a specific user, it passes the full path (`company-id`, `department-id`, `team-id`, `user-id`) and Foff resolves the most specific override that matches.

Now imagine the same company also runs a customer-facing product with a completely different structure:

```
Organization → Project → User
```

Because the hierarchy is different, you create a second scope — `customer-hierarchy` — for those flags. The two scopes are fully independent: flags, overrides, and resolution logic do not bleed across them.

## One scope or multiple scopes?

| Situation                                                                   | Recommendation                                                              |
| --------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| All flags share the same hierarchy                                          | Use one scope                                                               |
| You have separate hierarchies (e.g., internal staff vs. external customers) | Create one scope per hierarchy                                              |
| You want to isolate production from staging configs                         | Create separate scopes (e.g., `production`, `staging`)                      |
| You have a single hierarchy but many unrelated products                     | A single scope still works; use feature naming conventions to organize them |

<Tip>
  Name your scopes after the hierarchy they represent or the environment they serve. Clear names like `production`, `staging`, `employee-hierarchy`, or `customer-hierarchy` make it obvious which scope to query from your application code.
</Tip>

## Next steps

With a scope created, you are ready to add features — the individual flags and config values — inside it.

<Card title="Features" icon="flag" href="/concepts/features">
  Learn how to create flags and set default values inside a scope.
</Card>