Feature Flags

vortos/vortos-feature-flags lets you deploy code and control who sees it separately. The feature lands in production behind a flag — disabled. You enable it for internal users, then 5%, then 50%, then everyone. If something goes wrong, you disable it in seconds without touching the codebase.

This is a different discipline from authorization. Authorization answers "is this user allowed to do this?" Feature flags answer "is this feature turned on for this user right now?" They solve different problems and should stay separate — see Authorization for RBAC.

Two packages

The platform ships as two independent Composer packages:

The engine has no UI dependency. You can run it headlessly and manage flags via CLI or the management API. The admin UI package is an optional add-on.

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Management layer                      │
│  CLI commands  ·  REST API  ·  Admin UI  ·  GitOps sync  │
└──────────────────────────┬──────────────────────────────┘
                           │ FlagWriteService (single write boundary)
                           ▼
┌─────────────────────────────────────────────────────────┐
│                     Storage layer                        │
│   FlagStorageInterface (DB)  ·  Audit log  ·  Read model │
└──────────────────────────┬──────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                   Evaluation layer                       │
│   FlagRegistry  →  FlagEvaluator  →  Redis cache (60s)   │
└──────────────────────────┬──────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                    Delivery layer                        │
│   isEnabled()  ·  variant()  ·  /api/flags  ·  SSE stream│
└─────────────────────────────────────────────────────────┘

Every write goes through FlagWriteService — a single boundary that validates, persists, emits audit entries, invalidates the cache, and notifies SSE consumers. Nothing writes to flag storage directly.

Reads hit Redis first (60-second TTL). Cache misses fall through to the database. A typical isEnabled() call costs under a millisecond.

Quick orientation

If you are new to the platform, read in this order:

1. Installation — get the packages installed and migrated
2. Concepts — understand flag kinds, value types, environments, and lifecycle
3. Managing Flags — CLI commands for day-to-day operations
4. Targeting Rules — percentage rollout, user lists, attribute matching
5. Variants — A/B testing and multi-variant experiments
6. Admin UI — browser-based management dashboard
7. Frontend — @vortos/flags React SDK

For production operations, continue with:

• Environments — separate rollout per environment
• Audit Log — full change history with actor and reason
• Change Requests — 4-eyes approval for protected environments
• Release Guardrails — policies that block risky rollbacks
• SDK Keys — API keys for CI/CD and SDK clients
• Webhooks — notify external systems on flag changes
• GitOps — manage flags as YAML in version control