Developer Quickstart Guide 🛠️

This guide provides technical implementation details for the four core CrittrHavens workflows. Perfect for developers who want to understand the architecture behind Haven creation, Habitat management, Crittr profiles, and Feeding logs.

Architecture Overview

CrittrHavens uses a React + TypeScript + Supabase stack with the following key patterns:

React Query for server state management and caching
Zod schemas for form validation (src/lib/validations.ts)
Custom hooks for data operations (src/hooks/)
Feature-based components organized in src/components/

Workflow 1: Haven Creation

Interface Definition

// src/hooks/useHavens.tsx:6-17
export interface Haven {
  id: string;
  name: string;
  haven_type: string;
  description?: string;
  background: string;
  index_position: number;
  user_id: string;
  created_at: string;
  updated_at: string;
  split_slots: any[]; // Array of slot identifiers for split habitat management
}

Implementation Details

Component: src/components/CreateHavenModal.tsx
Hook: src/hooks/useHavens.tsx - Handles CRUD operations with optimistic updates
Database: havens table with RLS (Row Level Security) policies
Validation: Form validation with Zod in modal component

Key Features

Drag-and-drop reordering between haven slots
Background customization with preset themes
Split slot management for organizing multiple habitats per slot
Real-time sync across devices via Supabase subscriptions

Workflow 2: Habitat Setup with Frequencies

User Documentation: For user-friendly habitat management instructions, see the Habitat Management Guide.

Interface Definition

// src/hooks/useHavens.tsx:19-38
export interface Habitat {
  id: string;
  name: string;
  habitat_type: string;
  visual: Json; // 4-layer system: {habitat, background, foreground, glassReflection, shape}
  slot_position?: number;
  haven_id?: string;
  user_id: string;
  created_at: string;
  updated_at: string;
  sub_slot_index?: number | string;
  sub_slot_path?: string;
  // Frequency tracking for automated care schedules
  cleaning_frequency_hours?: number;
  misting_frequency_hours?: number;
  measurement_frequency_hours?: number;
  last_cleaned?: string;
  last_misted?: string;
  last_measured?: string;
}

Frequency System

The frequency system tracks care intervals in hours:

24 hours = Daily care
168 hours = Weekly care
720 hours = Monthly care
Custom intervals supported

Implementation Details

Component: src/components/CreateHabitatModal.tsx
Configuration: src/components/care/configs/habitatsConfig.ts
Slot Management: src/components/HavenSlot.tsx for drag-and-drop
Visual Assets: src/config/habitat-images.ts for theming

Advanced Features

Hierarchical slot paths for nested habitat organization
Sub-slot management for dividing enclosure spaces
Visual customization with preset habitat images
Care frequency automation with background tracking

Workflow 3: Crittr Management

Interface Definition

// src/components/care/configs/crittrsConfig.ts:15+
interface Crittr {
  id: string;
  name: string;
  species: string;
  sex?: string;
  morph?: string;
  feeding_schedule_hours?: number; // How often they eat
  feeding_amount?: string; // Typical portion size
  habitat_id?: string; // Which habitat they live in
  user_id: string;
  created_at: string;
  updated_at: string;
}

Implementation Details

Create Modal: src/components/CreateCrittrModal.tsx
Edit Modal: src/components/EditCrittrModal.tsx
Configuration: src/components/care/configs/crittrsConfig.ts
Details Page: src/pages/CrittrDetails.tsx

Data Management

Form handling with React Hook Form + Zod validation
Image uploads to Supabase Storage with automatic optimization
Relationship management between crittrs and habitats
QR code generation for physical pet tags

Advanced Features

Feeding schedule automation based on hours interval
Growth milestone tracking with age calculations
Health record integration linked to care logs
Export capabilities for vet reports

Workflow 4: Feeding Log Creation

Interface Definition

// src/components/care/configs/logsConfig.ts:5-15
interface Log {
  id: string;
  subject: string; // What the log is about (crittr name, habitat, etc.)
  log_type: string; // 'feeding', 'cleaning', 'misting', etc.
  content?: string; // Notes and observations
  quantity_change?: number; // Amount fed or used
  images?: string[]; // Photo attachments
  created_at: string;
  log_date?: string; // When the activity actually happened
  user_id: string;
}

Log Types and Color Coding

// src/components/care/configs/logsConfig.ts:17-27
const getLogTypeColor = (type: string) => {
  const colors: Record<string, string> = {
    feeding: 'bg-orange-100 text-orange-800',
    cleaning: 'bg-blue-100 text-blue-800',
    misting: 'bg-cyan-100 text-cyan-800',
    maintenance: 'bg-purple-100 text-purple-800',
    health: 'bg-red-100 text-red-800',
    observation: 'bg-green-100 text-green-800',
  };
  return colors[type.toLowerCase()] || 'bg-gray-100 text-gray-800';
};

Implementation Details

Component: src/components/ui/log-modal.tsx (unified modal for all log types)
Service: src/services/logService.ts for data operations
Validation: src/lib/log-validation.ts for form validation
Timeline: src/components/ui/logs-timeline.tsx for history display

Advanced Features

Photo attachments with automatic compression and 90-day cleanup
Real-time updates with optimistic UI updates
Search and filtering by date, type, and pet
Export capabilities to CSV for external analysis
Integration with task system for automated logging reminders

Data Flow Architecture

Query Management

// Example from useHavens hook
const { data, isLoading, error } = useQuery({
  queryKey: ['havens', user?.id],
  queryFn: fetchHavensWithHabitats,
  enabled: !!user?.id,
});

Mutation Patterns

// Optimistic updates for better UX
const createMutation = useMutation({
  mutationFn: createHaven,
  onMutate: async (newHaven) => {
    // Cancel outgoing refetches
    await queryClient.cancelQueries(['havens']);
    
    // Snapshot previous value
    const previousHavens = queryClient.getQueryData(['havens']);
    
    // Optimistically update
    queryClient.setQueryData(['havens'], (old) => [...old, newHaven]);
    
    return { previousHavens };
  },
  onError: (err, newHaven, context) => {
    // Rollback on error
    queryClient.setQueryData(['havens'], context.previousHavens);
  },
  onSettled: () => {
    // Refetch to ensure sync
    queryClient.invalidateQueries(['havens']);
  },
});

Database Schema

Key Relationships

Users → Havens (1:many)
Havens → Habitats (1:many)
Habitats → Crittrs (1:many)
Crittrs → Logs (1:many)

RLS Policies

All tables use Row Level Security to ensure users only access their own data:

-- Example RLS policy
CREATE POLICY "Users can only see their own havens" ON havens
  FOR ALL USING (auth.uid() = user_id);

Developer Quickstart Guide 🛠️

Architecture Overview

Workflow 1: Haven Creation

Interface Definition

Implementation Details

Key Features

Workflow 2: Habitat Setup with Frequencies

Interface Definition

Frequency System

Implementation Details

Advanced Features

Workflow 3: Crittr Management

Interface Definition

Implementation Details

Data Management

Advanced Features

Workflow 4: Feeding Log Creation

Interface Definition

Log Types and Color Coding

Implementation Details

Advanced Features

Data Flow Architecture

Query Management

Mutation Patterns

Database Schema

Key Relationships

RLS Policies

Testing Considerations

Key Test Files

Testing Strategy

Performance Optimizations

Caching Strategy

Code Splitting

See Also

User Documentation

Technical Documentation