feature_flags

This table stores feature toggles that can be applied either globally across the platform or as a tenant-specific override. It is primarily used by the internal DirtView admin team to control feature rollout without requiring a new deployment.

Domain: Global Admin / Platform Control

Scope: Global or Tenant-specific

Status: Proposed

Last Updated: 11 Apr 2026

Mutable: Yes

Primary Owner: Internal Admin Dashboard

RLS Applies: No direct tenant RLS model

Write Access: Super Admin only

Purpose

The purpose of this table is to allow the DirtView team to enable or disable features dynamically, either for the whole platform or for specific tenants. This makes it possible to run pilot rollouts, support beta programs, temporarily disable unstable features, and selectively expose functionality without changing application code or redeploying.

What this table does

The feature_flags table acts as a configuration control layer for the product.

It supports two modes:

Global flag: applies to all tenants when tenant_id is NULL
Tenant-specific override: applies only to one tenant when tenant_id is set

At runtime, the backend checks whether a feature is enabled before exposing that feature in APIs, workflows, or UI configuration.

Why this table is defined

This table is defined because DirtView needs controlled feature rollout and operational flexibility.

Typical reasons include:

Closed beta access for selected pilot tenants
Gradual rollout of risky or incomplete modules
Emergency kill-switches for unstable external dependencies
Internal-only testing of new functionality
Tenant-specific enablement based on commercial agreement or plan tier

For example, the Drawings Beta can be enabled for only a small group of pilot tenants before wider release.

Columns

Column	Type	Required	Description	Example
`id`	uuid	Yes	Primary key for the feature flag record	`3c9d8e7a-...`
`tenant_id`	uuid	No	Nullable. If NULL, the flag is global. If set, the row is a tenant-specific override.	`tenant_123`
`flag_key`	text	Yes	Machine-readable feature name	`drawings_beta`
`is_enabled`	boolean	Yes	Controls whether the feature is enabled or disabled	`true`
`set_by_super_admin_id`	uuid	Yes	Super admin who created or last changed the flag	`admin_456`
`set_at`	timestamptz	Yes	Timestamp for the last update to this flag record	`2026-04-11 10:00:00+00`
`notes`	text	No	Optional explanation for why the flag was enabled or disabled	`Enabled for pilot customers only`

Relationships

tenant_id → tenants.id
Used only when the flag applies to a specific tenant.
set_by_super_admin_id → super_admins.id
Identifies which internal DirtView admin changed the flag.

How it is used

This table is usually read by backend services, not directly by tenant users.

Typical usage flow:

API or service checks whether a feature is enabled
System first looks for a tenant-specific override
If none exists, it falls back to the global flag
If neither exists, the system applies a default behavior

Examples of where this can be checked:

Before showing Drawings Beta in the UI
Before enabling OCR processing for drawing uploads
Before exposing a new annotation workflow
Before enabling experimental internal tools

Access and security

This table is not client-facing
Writes should be allowed only through the internal admin application
Tenant users should not update feature flags directly
Every change to this table should also create a corresponding entry in admin_audit_log
If exposed through an API, the API should be super-admin protected and should never rely on tenant-level permissions

Example scenarios

Scenario 1: Enable Drawings Beta for pilot tenants only

The system keeps the feature disabled globally, but creates specific tenant-level rows for selected pilot companies.

flag_key	tenant_id	is_enabled
`drawings_beta`	`NULL`	`false`
`drawings_beta`	`tenant_acme`	`true`
`drawings_beta`	`tenant_buildright`	`true`

Scenario 2: Emergency kill switch

Gemini OCR is temporarily failing. The team disables OCR globally by setting:

ocr_processing_enabled = false

Scenario 3: Internal UI experiment

A new annotation toolbar is enabled only for an internal test tenant before rollout to customers.

Notes and assumptions

Tenant override lookup rules should be documented clearly in backend code
The application should define what happens when no matching flag exists
Future enhancement: support environment-specific flags such as dev, staging, and production
Future enhancement: support percentage-based rollout or user-segment-based rollout
For performance, resolved feature flags may be cached in the API layer