web-breeder Application

Breeding Management & Animal Sales

Application Type: Authenticated Breeder Workspace
Port: 3001
Users: Breeders, organization members
Status: Planned
Technology: Next.js 15 + Material UI + @reptidex/ui + @reptidex/core

Purpose & Responsibilities

web-breeder is the comprehensive workspace for reptile breeders to manage their animals, track lineage, plan breeding programs, and operate their marketplace presence. It provides professional tools for serious breeders while remaining accessible to hobbyists.

Core Features

Animal Registry

Complete animal record management
Comprehensive metadata and health tracking
Photo and media organization
Animal identification and tagging
Acquisition and disposal tracking

Lineage & Genetics

Multi-generation pedigree tracking
Genetic prediction and analysis
Breeding compatibility assessment
Lineage verification and corrections
Family tree visualization

Breeding Program

Breeding pair formation and tracking
Clutch and offspring management
Breeding attempt logging and analytics
Seasonal breeding planning
Success rate optimization

Marketplace Management

Animal listing creation and management
Inventory tracking and availability
Sales pipeline and inquiry handling
Pricing optimization tools
Performance analytics

Application Architecture

Technology Stack

Core Technologies

Framework & Runtime:

Next.js 15 with App Router and Server Components
React 18 with concurrent features and suspense
TypeScript for complete type safety
Material UI components via @reptidex/ui

Shared Dependencies:

@reptidex/ui: Material UI theme, components, design system
@reptidex/core: API clients, business logic, state management

Data & State:

React Query for server state with real-time updates
Zustand for complex UI state management
React Hook Form for advanced form handling
Optimistic updates for breeding data

Application Structure

app/
├── (auth)/                   # Authentication layout group
│   ├── login/               # Breeder login
│   ├── register/            # Account creation
│   └── forgot-password/     # Password reset
├── dashboard/               # Main dashboard overview
├── animals/                 # Animal management
│   ├── page.tsx            # Animal registry list
│   ├── new/                # Add new animal
│   ├── [id]/               # Animal detail pages
│   │   ├── edit/           # Edit animal information
│   │   ├── photos/         # Photo management
│   │   ├── health/         # Health records
│   │   └── lineage/        # Lineage tracking
│   └── import/             # Bulk animal import
├── breeding/                # Breeding program management
│   ├── pairs/              # Breeding pairs
│   ├── clutches/           # Clutch tracking
│   ├── calendar/           # Breeding calendar
│   └── analytics/          # Breeding analytics
├── lineage/                 # Lineage and genetics
│   ├── pedigrees/          # Pedigree management
│   ├── genetics/           # Genetic analysis
│   └── predictions/        # Breeding predictions
├── marketplace/             # Sales and listings
│   ├── listings/           # Manage listings
│   ├── inquiries/          # Customer inquiries
│   ├── sales/              # Sales tracking
│   └── analytics/          # Sales analytics
├── media/                   # Photo and file management
│   ├── gallery/            # Photo organization
│   ├── upload/             # Bulk upload
│   └── library/            # Media library
├── organization/            # Organization management
│   ├── profile/            # Public profile setup
│   ├── members/            # Team management
│   └── settings/           # Organization settings
└── settings/                # Account and preferences
    ├── profile/            # Personal profile
    ├── notifications/      # Notification preferences
    ├── billing/            # Subscription management
    └── integrations/       # Third-party integrations

Core Functionality

Animal Management System

Comprehensive Animal Registry

Animal Data Management:

const AnimalRegistryPage = () => {
  const { data: animals, isLoading } = useAnimals({
    filters: useBreederFilters(),
    sorting: useBreederSorting(),
  });

  const { mutate: createAnimal } = useCreateAnimal();
  const { mutate: bulkUpdate } = useBulkUpdateAnimals();

  return (
    <AnimalRegistryLayout>
      <AnimalFilters />
      <AnimalDataGrid 
        animals={animals}
        onSelectionChange={handleSelection}
        onBulkAction={handleBulkAction}
      />
      <AnimalQuickActions />
    </AnimalRegistryLayout>
  );
};

Features:

Advanced filtering and sorting
Bulk operations and batch updates
Quick entry forms for common data
Photo upload with automatic organization
Health record tracking with reminders
Custom fields for specific species

Breeding Program Management

Professional Breeding Tools

Breeding Pair Management:

const BreedingPairForm = () => {
  const form = useForm({
    resolver: zodResolver(breedingPairSchema),
    defaultValues: {
      sireId: '',
      damId: '',
      pairingDate: new Date(),
      expectedClutchDate: null,
      notes: '',
      breedingGoals: []
    }
  });

  const { data: geneticPrediction } = useGeneticPrediction({
    sireId: form.watch('sireId'),
    damId: form.watch('damId'),
    enabled: !!(form.watch('sireId') && form.watch('damId'))
  });

  return (
    <Form {...form}>
      <AnimalSelector name="sireId" label="Sire" gender="male" />
      <AnimalSelector name="damId" label="Dam" gender="female" />
      <DatePicker name="pairingDate" label="Pairing Date" />
      
      {geneticPrediction && (
        <GeneticPredictionCard prediction={geneticPrediction} />
      )}
      
      <BreedingGoalsSelector name="breedingGoals" />
      <FormActions />
    </Form>
  );
};

Breeding Features:

Genetic compatibility analysis
Breeding outcome predictions
Clutch tracking with hatch rates
Breeding calendar and scheduling
Success rate analytics
Breeding goal tracking

Lineage & Genetics System

Advanced Lineage Tracking

Pedigree Visualization:

const PedigreeTreeView = ({ animalId }: { animalId: string }) => {
  const [generations, setGenerations] = useState(5);
  const { data: pedigree } = usePedigreeData(animalId, generations);
  const { mutate: updateLineage } = useUpdateLineage();

  const handleNodeEdit = (nodeId: string, updates: any) => {
    updateLineage({
      animalId: nodeId,
      updates,
      onSuccess: () => queryClient.invalidateQueries(['pedigree', animalId])
    });
  };

  return (
    <PedigreeContainer>
      <PedigreeControls 
        generations={generations}
        onGenerationsChange={setGenerations}
      />
      <InteractivePedigreeTree
        data={pedigree}
        onNodeEdit={handleNodeEdit}
        onNodeClick={handleNodeClick}
        maxGenerations={generations}
      />
      <PedigreeAnalysis data={pedigree} />
    </PedigreeContainer>
  );
};

Lineage Features:

Interactive pedigree tree visualization
Multi-generation lineage tracking (up to 10 generations)
Lineage verification and correction tools
Genetic diversity analysis
Inbreeding coefficient calculations
Family tree exports (PDF, SVG)

User Interface Design

Dashboard Overview

Breeder Dashboard

Dashboard Components:

const BreederDashboard = () => {
  const { data: overview } = useDashboardOverview();
  const { data: recentActivity } = useRecentActivity();
  const { data: upcomingTasks } = useUpcomingTasks();

  return (
    <DashboardLayout>
      <DashboardHeader greeting={getTimeBasedGreeting()} />
      
      <Grid container spacing={3}>
        <Grid item xs={12} md={8}>
          <AnimalOverviewCard data={overview.animals} />
          <BreedingStatusCard data={overview.breeding} />
          <MarketplacePerformanceCard data={overview.marketplace} />
        </Grid>
        
        <Grid item xs={12} md={4}>
          <UpcomingTasksCard tasks={upcomingTasks} />
          <RecentActivityFeed activity={recentActivity} />
          <QuickActionsCard />
        </Grid>
      </Grid>
    </DashboardLayout>
  );
};

Dashboard Features:

Real-time animal inventory overview
Breeding program status and alerts
Marketplace performance metrics
Upcoming tasks and reminders
Recent activity feed
Quick action shortcuts

Data Management Interface

Advanced Data Entry

Smart Form System:

const SmartAnimalForm = ({ animalId }: { animalId?: string }) => {
  const isEditing = !!animalId;
  const { data: animal } = useAnimal(animalId, { enabled: isEditing });
  
  const form = useForm({
    resolver: zodResolver(animalSchema),
    defaultValues: animal || getDefaultAnimalValues(),
  });

  const species = form.watch('speciesId');
  const { data: speciesTraits } = useSpeciesTraits(species);
  const { data: morphSuggestions } = useMorphSuggestions(species);

  return (
    <Form {...form}>
      <BasicInformationSection />
      <SpeciesSelector onSpeciesChange={handleSpeciesChange} />
      
      {speciesTraits && (
        <MorphSelector 
          traits={speciesTraits}
          suggestions={morphSuggestions}
        />
      )}
      
      <PhysicalCharacteristics />
      <AcquisitionDetails />
      <PhotoUploadSection />
      <NotesSection />
      
      <FormActions 
        onSave={handleSave}
        onSaveAndAddAnother={handleSaveAndAddAnother}
      />
    </Form>
  );
};

Form Features:

Dynamic forms based on species selection
Auto-complete for morph combinations
Photo upload with drag-and-drop
Real-time validation and error handling
Save and continue workflows
Bulk data entry tools

Business Logic Integration

Data Synchronization

Real-time Data Management

Optimistic Updates:

const useOptimisticAnimalUpdate = () => {
  const queryClient = useQueryClient();
  
  return useMutation({
    mutationFn: updateAnimal,
    onMutate: async (variables) => {
      // Cancel outgoing refetches
      await queryClient.cancelQueries(['animals']);
      
      // Snapshot previous value
      const previousAnimals = queryClient.getQueryData(['animals']);
      
      // Optimistically update
      queryClient.setQueryData(['animals'], (old: Animal[]) =>
        old.map(animal => 
          animal.id === variables.id 
            ? { ...animal, ...variables.updates }
            : animal
        )
      );
      
      return { previousAnimals };
    },
    onError: (err, variables, context) => {
      // Rollback on error
      queryClient.setQueryData(['animals'], context?.previousAnimals);
    },
    onSettled: () => {
      // Refetch after mutation
      queryClient.invalidateQueries(['animals']);
    },
  });
};

Real-time Features:

Optimistic UI updates for better UX
Real-time collaboration for organizations
Conflict resolution for concurrent edits
Offline support with sync on reconnect
Background data synchronization

Breeding Analytics

Breeding Intelligence

Analytics Dashboard:

const BreedingAnalytics = () => {
  const { data: analytics } = useBreedingAnalytics({
    timeRange: '1y',
    includeProjections: true
  });

  return (
    <AnalyticsLayout>
      <SuccessRateChart data={analytics.successRates} />
      <SeasonalTrendsChart data={analytics.seasonalData} />
      <GeneticDiversityMap data={analytics.diversity} />
      <BreedingProjections data={analytics.projections} />
      
      <InsightsPanel>
        <RecommendationCard 
          title="Breeding Recommendations"
          insights={analytics.recommendations}
        />
        <AlertCard 
          title="Genetic Health Alerts"
          alerts={analytics.geneticAlerts}
        />
      </InsightsPanel>
    </AnalyticsLayout>
  );
};

Analytics Features:

Breeding success rate tracking
Seasonal performance analysis
Genetic diversity monitoring
Breeding outcome predictions
Performance recommendations
Health and genetic alerts

Marketplace Integration

Listing Management

Professional Marketplace Tools

Listing Creation Workflow:

const CreateListingWizard = () => {
  const [currentStep, setCurrentStep] = useState(0);
  const { data: eligibleAnimals } = useEligibleAnimals();
  
  const steps = [
    'Animal Selection',
    'Listing Details',
    'Photos & Media',
    'Pricing & Terms',
    'Review & Publish'
  ];

  const form = useForm({
    resolver: zodResolver(listingSchema),
    mode: 'onChange'
  });

  return (
    <WizardLayout>
      <WizardStepper steps={steps} currentStep={currentStep} />
      
      <Form {...form}>
        {currentStep === 0 && (
          <AnimalSelectionStep animals={eligibleAnimals} />
        )}
        {currentStep === 1 && (
          <ListingDetailsStep />
        )}
        {currentStep === 2 && (
          <PhotoManagementStep />
        )}
        {currentStep === 3 && (
          <PricingTermsStep />
        )}
        {currentStep === 4 && (
          <ReviewPublishStep />
        )}
      </Form>
      
      <WizardNavigation 
        onNext={handleNext}
        onPrevious={handlePrevious}
        onPublish={handlePublish}
      />
    </WizardLayout>
  );
};

Marketplace Features:

Guided listing creation wizard
Professional photo management
Pricing optimization suggestions
Listing performance tracking
Automated availability updates
Customer inquiry management

Sales Pipeline

Customer Relationship Management

Sales Management:

const SalesPipeline = () => {
  const { data: inquiries } = useInquiries();
  const { data: activeSales } = useActiveSales();
  const { mutate: updateInquiry } = useUpdateInquiry();

  const handleInquiryUpdate = (inquiryId: string, status: string) => {
    updateInquiry({
      inquiryId,
      status,
      timestamp: new Date(),
    });
  };

  return (
    <SalesLayout>
      <InquiryKanbanBoard 
        inquiries={inquiries}
        onStatusChange={handleInquiryUpdate}
      />
      
      <ActiveSalesTracker sales={activeSales} />
      
      <CustomerCommunication 
        onSendMessage={handleSendMessage}
        onScheduleFollowup={handleScheduleFollowup}
      />
    </SalesLayout>
  );
};

Sales Features:

Inquiry-to-sale pipeline tracking
Customer communication history
Automated follow-up reminders
Sales performance analytics
Payment tracking integration
Customer feedback collection

Performance & User Experience

Performance Optimization

Application Performance

Performance Strategies:

Route-based code splitting for large datasets
Virtual scrolling for animal lists
Image lazy loading with priority loading
Form debouncing for search and filters
Optimistic updates for immediate feedback
Background data prefetching

Caching Strategy:

// React Query configuration for breeder app
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5 * 60 * 1000, // 5 minutes
      gcTime: 30 * 60 * 1000,   // 30 minutes
      refetchOnWindowFocus: false,
      retry: (failureCount, error) => {
        if (error.status === 404) return false;
        return failureCount < 3;
      },
    },
    mutations: {
      retry: 1,
    },
  },
});

Accessibility & Usability

User Experience Design

Accessibility Features:

WCAG 2.1 AA compliance throughout
Keyboard navigation for all interactions
Screen reader optimization
High contrast mode support
Focus management for complex forms
Accessible data tables and charts

Usability Enhancements:

Contextual help and tooltips
Progressive disclosure for complex features
Undo/redo functionality for data entry
Bulk operations with confirmation
Customizable dashboard layouts
Keyboard shortcuts for power users

Security & Data Protection

Security Implementation

Security Measures

Authentication & Authorization:

// Route protection for breeder pages
const BreederProtectedRoute = ({ children }: { children: React.ReactNode }) => {
  const { user, isLoading } = useAuth();
  const router = useRouter();

  useEffect(() => {
    if (!isLoading && (!user || !user.isBreeder)) {
      router.push('/login?redirect=' + encodeURIComponent(router.asPath));
    }
  }, [user, isLoading, router]);

  if (isLoading) return <LoadingSpinner />;
  if (!user?.isBreeder) return null;

  return <>{children}</>;
};

Data Protection:

Role-based access control
Organization-scoped data isolation
Encrypted sensitive data fields
Audit logging for all changes
GDPR compliance tools
Data export and deletion features

Testing & Quality Assurance

Testing Strategy

Comprehensive Testing

Unit Testing:

import { renderWithProviders } from '@/test-utils';
import { screen, waitFor } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import AnimalForm from './AnimalForm';

describe('AnimalForm', () => {
  it('submits animal data correctly', async () => {
    const user = userEvent.setup();
    const onSubmit = jest.fn();
    
    renderWithProviders(<AnimalForm onSubmit={onSubmit} />);
    
    await user.type(screen.getByLabelText('Animal Name'), 'Test Python');
    await user.selectOptions(screen.getByLabelText('Species'), 'ball-python');
    await user.click(screen.getByRole('button', { name: 'Save Animal' }));
    
    await waitFor(() => {
      expect(onSubmit).toHaveBeenCalledWith({
        name: 'Test Python',
        species: 'ball-python',
        // ... other expected data
      });
    });
  });
});

Integration Testing:

API integration tests with MSW
User workflow testing
Data synchronization testing
Performance regression testing
Accessibility testing automation

Deployment & Infrastructure

Production Deployment

Deployment Configuration

Docker Configuration:

FROM node:18-alpine AS base
WORKDIR /app

# Install dependencies
COPY package.json pnpm-lock.yaml ./
RUN corepack enable pnpm && pnpm install --frozen-lockfile

# Build application
COPY . .
RUN pnpm build

# Production runtime
FROM node:18-alpine AS runner
WORKDIR /app
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

COPY --from=base /app/public ./public
COPY --from=base --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=base --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs
EXPOSE 3001
ENV PORT 3001
CMD ["node", "server.js"]

Environment Variables:

# API Configuration
NEXT_PUBLIC_API_URL=https://api.reptidex.com
NEXT_PUBLIC_WS_URL=wss://api.reptidex.com/ws

# Authentication
NEXT_PUBLIC_AUTH_DOMAIN=auth.reptidex.com
NEXTAUTH_URL=https://breeder.reptidex.com
NEXTAUTH_SECRET=xxx

# Feature Flags
NEXT_PUBLIC_FEATURE_FLAGS_KEY=xxx

# File Upload
NEXT_PUBLIC_UPLOAD_ENDPOINT=https://upload.reptidex.com
NEXT_PUBLIC_CDN_URL=https://cdn.reptidex.com

# Analytics
NEXT_PUBLIC_ANALYTICS_KEY=xxx
NEXT_PUBLIC_MONITORING_KEY=xxx

web-breeder provides professional-grade tools for reptile breeders while maintaining ease of use, supporting everything from hobbyist operations to large commercial breeding facilities.

Getting Started

System Architecture

Backend Services

Frontend Applications

Shared Packages

Development Standards

Infrastructure & Operations

API Reference

​web-breeder Application

​Purpose & Responsibilities

​Core Features

Animal Registry

Lineage & Genetics

Breeding Program

Marketplace Management

​Application Architecture

​Technology Stack

​Application Structure

​Core Functionality

​Animal Management System

​Breeding Program Management

​Lineage & Genetics System

​User Interface Design

​Dashboard Overview

​Data Management Interface

​Business Logic Integration

​Data Synchronization

​Breeding Analytics

​Marketplace Integration

​Listing Management

​Sales Pipeline

​Performance & User Experience

​Performance Optimization

​Accessibility & Usability

​Security & Data Protection

​Security Implementation

​Testing & Quality Assurance

​Testing Strategy

​Deployment & Infrastructure

​Production Deployment

web-breeder Application

Purpose & Responsibilities

Core Features

Application Architecture

Technology Stack

Application Structure

Core Functionality

Animal Management System

Breeding Program Management

Lineage & Genetics System

User Interface Design

Dashboard Overview

Data Management Interface

Business Logic Integration

Data Synchronization

Breeding Analytics

Marketplace Integration

Listing Management

Sales Pipeline

Performance & User Experience

Performance Optimization

Accessibility & Usability

Security & Data Protection

Security Implementation

Testing & Quality Assurance

Testing Strategy

Deployment & Infrastructure

Production Deployment