# Feature flags

Typed code defaults with database overrides and separate capability gates.

## Declare a flag [#declare-a-flag]

`packages/flags/src/registry.ts` declares each key, kind, default value and description. `FlagKey` and `FlagValues` derive from that registry. Unknown database keys are ignored; a missing override falls back to the code default.

```ts
"home.greeting": {
  kind: "boolean",
  defaultValue: true,
  description: "Show the personalized greeting on the home screen.",
}
```

The evaluator applies platform and targeting context to typed rows. Parsing belongs at the database boundary. Clients consume the safe registry/evaluator exports; `/repo` owns the Drizzle reads and writes and must remain server-only.

## Boot and administration [#boot-and-administration]

`appConfig` combines evaluated flags and app-update configuration in one public boot request. Admin flag procedures use the current platform admin guard. Web uses `useFlags`; native boot reads the same server definitions.

A visibility flag is not a capability or authorization check. `billing.web` can show navigation only after server providers are configured; `ai.assistant` also requires a model provider. A hidden control never replaces membership or role authorization.

## Extend [#extend]

Add the key in code, use its inferred type, and translate any user-facing labels in every catalog. Test default behavior, absent/disabled overrides and invalid stored values. Keep optional features bootable with their flag off and no provider credentials.


## Key files [#key-files]

- [`packages/flags/src/registry.ts`](https://github.com/CarlosZiegler/doro/blob/main/packages/flags/src/registry.ts)
- [`packages/flags/src/evaluate.ts`](https://github.com/CarlosZiegler/doro/blob/main/packages/flags/src/evaluate.ts)
- [`packages/flags/src/repo.ts`](https://github.com/CarlosZiegler/doro/blob/main/packages/flags/src/repo.ts)
- [`packages/api/src/routers/app-config.ts`](https://github.com/CarlosZiegler/doro/blob/main/packages/api/src/routers/app-config.ts)
- [`apps/web/src/lib/flags.ts`](https://github.com/CarlosZiegler/doro/blob/main/apps/web/src/lib/flags.ts)