feat(flags): folder organization support (schema + api + dashboard)

[agent-sure]

Summary

Implements #271 with a minimal, shippable scope focused on folder organization (without changing flag evaluation logic).

What’s included

• Add optional folder field for flags in DB schema + migration (backward compatible)
• Extend flags API to support:
  • create with folder
  • update with folder
  • list filter by folder
• Dashboard flags UX for folder organization:
  • folder-based grouping/filtering
  • folder path editable in relevant flag flows

Explicitly unchanged

• No changes to flag evaluation/business logic, dependencies, SDK behavior

Acceptance checklist

• Schema includes optional folder support
• Backward compatibility preserved for existing flags
• API supports folder create/update/list filtering
• Dashboard has practical folder organization UX
• No business logic changes to flag evaluation
• Full lint/test suite in this environment

Verification notes

• Attempted local checks, but this runtime does not have bun available for project scripts (bun run lint failed due to missing bun).
• Please run full project checks in CI/maintainer environment.

[CLAassistant]

All committers have signed the CLA.

[vercel]

Someone is attempting to deploy a commit to the Databuddy OSS Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[dosubot]

Related Documentation

Checked 1 published document(s) in 1 knowledge base(s). No updates required.

^{How did I do? Any feedback?}  

[greptile-apps]

Greptile Overview

Greptile Summary

Implements folder organization for feature flags with a clean, minimal approach that maintains backward compatibility.

Key Changes:

• Added optional folder text column to flags table with efficient composite indexing
• Extended flags API to support folder filtering in list operations and folder assignment in create/update
• Implemented folder-based grouping and filtering UI in the dashboard with folder selector dropdown
• All folder values are normalized (trimmed and null-coerced) consistently across the stack
• Cache keys updated to include folder context for optimal performance

Implementation Quality:

• Backward compatible: existing flags without folders work seamlessly
• Consistent data handling: folder trimming and null normalization applied uniformly
• Query optimization: composite index on (website_id, folder) for efficient filtering
• UI polish: folder grouping with counts, "Unassigned" category for null folders, alphabetical sorting

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The implementation is clean, well-structured, and follows best practices. Database migration uses IF NOT EXISTS for safety, the folder field is optional maintaining backward compatibility, normalization logic is consistent across all layers, and the UI changes are additive without breaking existing functionality. No business logic changes to flag evaluation as promised.
• No files require special attention

Important Files Changed

Filename	Overview
packages/db/migrations/20260213_add_flags_folder.sql	Added optional folder text column to flags table with composite index on website_id and folder for efficient filtering
packages/db/src/drizzle/schema.ts	Added folder field to flags table schema and created composite index idx_flags_website_folder for query optimization
packages/rpc/src/routers/flags.ts	Added folder filtering to list API, folder caching support, and folder field handling in create/update operations with proper trimming and null normalization
apps/dashboard/app/(main)/websites/[id]/flags/_components/flags-list.tsx	Implemented folder grouping UI with folder normalization, sorting logic (unassigned last), and folder-based group headers with flag counts
apps/dashboard/app/(main)/websites/[id]/flags/page.tsx	Added folder filter dropdown with folder counts, folder-based filtering logic, and grouping display mode for organized flag management

Sequence Diagram

sequenceDiagram
    participant User
    participant Dashboard
    participant FlagSheet
    participant API
    participant DB

    User->>Dashboard: Select folder filter
    Dashboard->>Dashboard: Filter flags by folder
    Dashboard->>Dashboard: Group flags by folder
    Dashboard-->>User: Display filtered/grouped flags

    User->>Dashboard: Click "Create Flag"
    Dashboard->>FlagSheet: Open flag creation form
    User->>FlagSheet: Enter folder name (optional)
    FlagSheet->>FlagSheet: Validate & trim folder input
    User->>FlagSheet: Submit flag
    FlagSheet->>API: POST /flags/create {folder, ...}
    API->>API: Normalize folder (trim || null)
    API->>DB: INSERT flag with folder
    DB->>DB: Index on (website_id, folder)
    DB-->>API: Flag created
    API->>API: Invalidate cache for folder
    API-->>FlagSheet: Success
    FlagSheet-->>Dashboard: Close & refresh
    Dashboard->>API: GET /flags/list {websiteId, folder?}
    API->>DB: SELECT with folder filter
    DB-->>API: Filtered flags
    API-->>Dashboard: Flags list
    Dashboard-->>User: Display updated flags

Loading

_{Last reviewed commit: 48f2263}