Care Center Architecture and Technical Guide

The Care Center is built with a modular, configuration-driven architecture that supports extensible care management across different entity types (habitats, crittrs, plants, logs).

👨‍💻 New Developer? Start with our Developer Quickstart to understand the core workflows and technical patterns.

👥 User Perspective? See how users interact with this system in our Care Center User Guide.

Core Architecture

Component Hierarchy

CareCenter.tsx (main container)
├── IOSHeaderWithTabs (navigation)
├── Tab-specific components
│   ├── HabitatsCareRefactored
│   ├── CrittrsCareRefactored  
│   ├── PlantsCareRefactored
│   └── LogsCareRefactored
└── Modal components (Create*, PetNameTags)

Key Interfaces

interface CareItemConfig<T> {
  itemType: string;
  displayName: string;
  pluralName: string; 
  queryKey: string;
  tableName: string;
  querySelect?: string;
  defaultSort: string;
  nameField: string;
  filters: FilterConfig[];
  actions: ActionConfig[];
  cardConfig: CardConfig;
  emptyState: EmptyStateConfig;
}

Data Flow

1. Tab Selection

• User selects tab → setActiveTab() → loads corresponding config
• Each tab uses same CareListContainer with different config

2. Data Fetching

• usePagination hook handles infinite scroll loading
• Supabase queries use config-defined tableName and querySelect
• Real-time subscriptions update when logs are created

3. Filtering & Search

• useFilterState manages search term and type filters
• CareFilterBar renders config-defined filter options
• Custom filters support dynamic options (e.g., haven filtering)

4. Status Calculation

• calculateFrequencyStatus() computes care status percentages
• frequency-status.ts defines 5-level color system
• Progress indicators update based on last care timestamps

Configuration System

Filter Configuration

{
  key: 'habitat_type',
  type: 'select',
  label: 'Filter by type', 
  options: [
    { value: 'aquarium', label: 'Aquarium' },
    // ...
  ]
}

Action Configuration

{
  id: "log-misting",
  icon: MistingIcon,
  label: "Log Misting",
  description: "Record misting session", 
  context: "menu" // "menu" | "swipe-left" | "swipe-right"
}

Status System (5-Level Color System)

The status calculation is based on percentage of time elapsed since last care action relative to the frequency setting:

• Level 1 (0-20%): Purple #B058F9 - Recently cared for
• Level 2 (20-50%): Light Blue #2CC7F6 - Still good
• Level 3 (50-85%): Green #3AB652 - Getting close
• Level 4 (85-100%): Orange #F9B43E - Care needed
• Level 5 (100%+): Red #E74E40 - Overdue

Status levels and colors are defined in src/config/frequency-status.ts with type-specific labels (e.g., "✨ Sparkling!" for habitat cleaning, "💧 Perfectly Misted" for misting).

Key Hooks

usePagination<T>

Handles infinite scroll data loading with Supabase integration:

• Page size: 50 items
• Automatic loading on scroll
• Real-time invalidation

useFilterState

Manages persistent filter state:

• Search term persistence across sessions
• Type filter state management
• Clear filters functionality

useActionHandler

Centralized action processing:

• Universal log modal handling
• Delete confirmation flows
• Toast notifications

useSorting

Multi-criteria sorting system:

• Alphabetical, date-based, care priority
• Favorites-first option
• Direction toggle support

Real-time Features

Supabase Subscriptions

supabase
  .channel('care-log-updates')
  .on('postgres_changes', {
    event: 'INSERT',
    schema: 'public', 
    table: 'logs'
  }, (payload) => {
    queryClient.invalidateQueries([config.queryKey]);
  })
  .subscribe();

Mobile Optimizations

Responsive Grid

• Mobile: grid-cols-1 (single column)
• Tablet: grid-cols-1 md:grid-cols-2
• Desktop: lg:grid-cols-3

Touch Interactions

• Long press: Action drawer
• Swipe gestures: Quick actions
• Pull-to-refresh: Data synchronization

Testing Approach

Unit Tests

• Hook behavior (usePagination, useFilterState)
• Status calculation functions
• Filter and sort logic

Integration Tests

• Component interaction flows
• Modal workflows (create, log, delete)
• Real-time subscription handling

E2E Tests

Located in e2e/specs/crittr-care.spec.ts:

• Full user workflows
• Cross-device behavior
• Action completion verification

Performance Considerations

Optimization Strategies

• Infinite scroll prevents large data loading
• Memoized filter and sort calculations
• Component memoization for stable renders
• Debounced search input

Bundle Impact

• Config-driven approach reduces code duplication
• Shared components across all care types
• Tree-shakeable icon imports

Extension Points

Adding New Care Types

1. Create config file following CareItemConfig<T> interface
2. Add component in /care/ directory
3. Register in CareCenter.tsx tab configuration
4. Define actions and filters specific to type

Custom Status Systems

Override calculateFrequencyStatus or add custom status fields to handle specialized care tracking requirements.

Related Documentation

User Guides

• Care Center User Guide - User-facing navigation and workflows
• Pet Management Guide - Complete crittr creation and tracking
• Habitat Management Guide - Habitat creation and organization
• Growth Tracking Guide - Measurement workflows and charts

Developer Guides

• Developer Quickstart - Core workflows and implementation patterns
• Growth Tracking Architecture - Measurement system technical implementation
• Developer Home - Complete technical documentation overview

Implementation Details

• Component Location: src/components/care/CareCenter.tsx
• Configuration Files: src/components/care/configs/
• Hook Implementations: src/hooks/ (usePagination, useFilterState, useActionHandler, useSorting)
• Status Configuration: src/config/frequency-status.ts