feature flags with user targeting and audit logs

Here’s a solid design for feature flags with user targeting and audit logs.

Core requirements

You likely want:

• Feature flags: enable/disable functionality without redeploying
• User targeting: rules like “only users in org X”, “emails ending in @company.com”, “10% rollout”
• Audit logs: track who changed what, when, and why
• Optional: environments, segments, experimentation, kill switches

---

Data model

1) Feature flags

A flag is the top-level feature definition.

{
  "id": "flag_new_dashboard",
  "key": "new_dashboard",
  "name": "New Dashboard",
  "description": "Roll out the new dashboard",
  "enabled": true,
  "environment": "prod",
  "created_by": "user_123",
  "created_at": "2026-10-13T10:00:00Z",
  "updated_at": "2026-10-13T10:15:00Z"
}

2) Flag rules

Rules determine when a flag is on for a user.

{
  "id": "rule_1",
  "flag_key": "new_dashboard",
  "priority": 1,
  "conditions": [
    { "attribute": "org_id", "operator": "eq", "value": "org_42" },
    { "attribute": "email", "operator": "ends_with", "value": "@company.com" }
  ],
  "variation": true
}

3) User targeting segments

Reusable groups of users.

{
  "id": "segment_beta_testers",
  "name": "Beta Testers",
  "conditions": [
    { "attribute": "role", "operator": "eq", "value": "beta" }
  ]
}

4) Audit logs

Every create/update/delete action gets an entry.

{
  "id": "audit_1001",
  "actor_user_id": "user_123",
  "action": "flag.update",
  "resource_type": "feature_flag",
  "resource_id": "flag_new_dashboard",
  "before": { "enabled": false },
  "after": { "enabled": true },
  "reason": "Starting 5% rollout",
  "created_at": "2026-10-13T10:15:00Z",
  "ip_address": "203.0.113.10"
}

---

Targeting logic

Evaluation order is important:

1. Check if flag is globally disabled
2. Check explicit allow/deny rules
3. Check segment membership
4. Check percentage rollout
5. Fallback to default

Example rule types:

• eq
• neq
• in
• contains
• starts_with
• ends_with
• regex
• gt, lt
• percentage

Example percentage rollout:

• Hash user_id + flag_key
• Map to 0–99
• Enable if bucket < rollout percentage

This ensures consistent assignment per user.

---

API endpoints

Flags

• GET /flags
• POST /flags
• GET /flags/{key}
• PATCH /flags/{key}
• DELETE /flags/{key}

Rules / targeting

• POST /flags/{key}/rules
• PATCH /rules/{id}
• DELETE /rules/{id}

Segments

• GET /segments
• POST /segments
• PATCH /segments/{id}

Evaluation

• POST /evaluate
  • body: user context + flag key
  • returns whether flag is enabled and why

Audit

• GET /audit-logs?resource_type=feature_flag&resource_id=flag_new_dashboard
• GET /audit-logs?actor_user_id=user_123
• GET /audit-logs?date_from=...&date_to=...

---

Example evaluation request

{
  "flag_key": "new_dashboard",
  "user": {
    "id": "user_987",
    "email": "alice@company.com",
    "org_id": "org_42",
    "role": "member"
  }
}

Example response:

{
  "flag_key": "new_dashboard",
  "enabled": true,
  "matched_rule": "rule_1",
  "reason": "User belongs to org_42",
  "variation": true
}

---

Audit log design tips

Capture these fields:

• actor user
• action type
• timestamp
• resource identifier
• before/after values
• reason/comment
• source IP
• request ID / correlation ID
• environment

Good practices:

• append-only logs
• immutable records
• export to SIEM or data warehouse
• support retention policies
• redact sensitive values if needed

---

Security and governance

• RBAC: only admins can change production flags
• approval workflow for high-risk flags
• mandatory change reason for audit
• separate prod/staging environments
• signed/evaluated config snapshots
• cache with TTL for performance

---

Simple evaluation pseudocode

def evaluate(flag, user):
    if not flag.enabled:
        return False

    for rule in sorted(flag.rules, key=lambda r: r.priority):
        if matches_all(rule.conditions, user):
            return rule.variation

    if flag.rollout_percentage is not None:
        bucket = hash(user["id"] + flag["key"]) % 100
        return bucket < flag.rollout_percentage

    return flag.default_value

---

Recommended architecture

• Admin UI: manage flags, rules, and audit history
• Flag service: stores config and evaluates targeting
• SDKs: cached client-side/server-side evaluation
• Audit pipeline: write-on-change, queryable logs
• Metrics: track evaluations, rule matches, exposure counts

---

If you want, I can also provide:

1. a database schema (Postgres),
2. a REST API spec,
3. or an implementation example in Node.js/Python/Go.