Category Management#

Overview#

Categories in Sure are scoped to a Family and follow a two-level parent/child hierarchy: a top-level category can have subcategories, but subcategories cannot have children. Each category carries a name, color (hex), and a lucide_icon.

Data Model#

The categories table 1 has these key columns:

Hierarchy and Validations#

The Category model defines:

• has_many :subcategories (FK: parent_id) and belongs_to :parent — self-referential associations 2
• Depth limit: the category_level_limit validation fires if a subcategory tries to gain a parent (i.e., a third level) — "can't have more than 2 levels of subcategories"
• Name uniqueness scoped to family_id 3
• Color format: must match /\A#[0-9A-Fa-f]{6}\z/ 4
• Required fields: name, color, lucide_icon, family 5

Color Inheritance#

A before_save callback inherit_color_from_parent overwrites the subcategory's color with its parent's color at save time. This means any color value passed to a subcategory is silently ignored — the parent's color always wins. The AI assistant's function description explicitly notes this: "color is ignored for subcategories since color is inherited" 6.

Default Categories (Bootstrapping)#

Category.bootstrap! 7 calls find_or_create_by! for each of the 22 predefined defaults defined in default_categories:

Bootstrapping is not automatic — it must be triggered explicitly. The CategoriesController#bootstrap action 8 calls Current.family.categories.bootstrap! and is user-initiated. New families start with zero categories.

Creating Categories#

Web Form#

The categories form lets users:

• Enter a name
• Pick a color from Category::COLORS 9 or use a custom hex via a color picker
• Pick a Lucide icon from the full icon_codes list 10
• Assign an optional parent (rendered only when the category has no existing subcategories) 11

The color picker section is hidden for subcategories since color is inherited from the parent 12.

The controller's create action optionally links the new category directly to a transaction if transaction_id is present in params.

AI Assistant#

Assistant::Function::CreateCategory exposes a create_category function. Required param: name. Optional: color, icon, parent_id. If icon is omitted, Category.suggested_icon matches the name against ICON_KEYWORDS regexes. If parent_id is given, the function validates the UUID, looks up the parent, and sets it — triggering color inheritance on save.

CSV Bulk Import#

CategoryImport handles CSV-based bulk creation. Required column: name. Optional columns: color, parent_category, lucide_icon 13. Import logic runs two passes 14:

1. First pass: creates/updates each category as a root (no parent set)
2. Second pass: assigns parents, validating no self-parent cycles

Missing parents referenced in the CSV are auto-created as placeholder categories with UNCATEGORIZED_COLOR and the "shapes" icon 15.

CSV template structure 16:

name*,color,parent_category,lucide_icon
Food & Drink,#f97316,,carrot
Groceries,#407706,Food & Drink,shopping-basket
Salary,#22c55e,,briefcase

Merging Categories#

Category::Merger merges one or more source categories into a target, atomically:

• Reassigns all transactions to the target
• Reparents any subcategories of the source under the target
• Consolidates budget entries
• Destroys the source categories

Validations prevent merging a parent into its own subcategory, merging a category with subcategories into a subcategory, and cross-family merges. Triggered via CategoriesController#perform_merge.

Synthetic Categories#

"Uncategorized" and "Other Investments" are not database rows. They are in-memory Category objects built by Category.uncategorized and Category.other_investments, detectable by synthetic?. These are used in income statement and search filter logic. See the Transaction Categorization article for full details.

Key Source Files#