Skip to main content

​
Overview

Categories help you organize transactions and understand your spending patterns. Each category has a type (income or expense) and optional visual styling.

​
Category Properties

PropertyTypeDescription
idStringLocal UUID (primary key)
serverIdString?Server-assigned ID after sync
nameStringCategory name (e.g., “Food”, “Salary”)
typeStringEither income or expense
colorint?Color value for UI (ARGB format)
iconString?Icon identifier (Flutter icon name)
syncStatusSyncStatusCurrent sync state

​
Creating Categories

​
Using the Cache Manager

final cache = CacheManager.instance;

// Expense category
final foodCategory = await cache.createCategory(
  name: 'Food & Dining',
  type: 'expense',
  color: 0xFFFF5722,  // Orange
  icon: 'restaurant',
);

// Income category
final salaryCategory = await cache.createCategory(
  name: 'Salary',
  type: 'income',
  color: 0xFF4CAF50,  // Green
  icon: 'attach_money',
);

​
Direct Repository Access

final category = Category(
  id: cache.generateId(),
  name: 'Transportation',
  type: 'expense',
  color: 0xFF2196F3,  // Blue
  icon: 'directions_car',
  createdAt: DateTime.now(),
  updatedAt: DateTime.now(),
);

await cache.categories.save(category);

​
Querying Categories

​
Get All Categories

final allCategories = await cache.categories.findAll();

​
Filter by Type

// Get only expense categories
final expenseCategories = await cache.categories.findByType('expense');

// Get only income categories
final incomeCategories = await cache.categories.findByType('income');

​
Find by ID

final category = await cache.categories.findById('category-uuid');

​
Common Category Examples

​
Expense Categories

  • 🍔 Food & Dining
  • 🚗 Transportation
  • 🏠 Housing
  • 💡 Utilities
  • 🎬 Entertainment
  • 🛒 Shopping
  • 🏥 Healthcare

​
Income Categories

  • 💼 Salary
  • 🎁 Gifts
  • 📈 Investments
  • 🏠 Rental Income
  • 💰 Other Income

​
Color Format

Colors are stored as 32-bit ARGB integers: 
// Format: 0xAARRGGBB
final red = 0xFFFF0000;      // Red
final green = 0xFF00FF00;    // Green
final blue = 0xFF0000FF;     // Blue

// In Flutter, you can use:
final color = Color(0xFFFF5722);

​
Updating Categories

final category = await cache.categories.findById(categoryId);
if (category != null) {
  final updated = category.copyWith(
    name: 'Updated Name',
    color: 0xFF9C27B0,  // Change to purple
  );
  await cache.categories.save(updated);
}

​
Deleting Categories

// Soft delete (recommended)
await cache.categories.delete(categoryId);

// Hard delete
await cache.categories.delete(categoryId, hardDelete: true);
When you delete a category, existing transactions will have their categoryId set to null (via ON DELETE SET NULL constraint).

​
Best Practices

  1. Keep it simple - Start with 5-10 categories
  2. Be consistent - Use the same categories month-to-month
  3. Use colors - Visual cues help identify categories quickly
  4. Review regularly - Merge or split categories as needed