breedr/IMPLEMENTATION_PLAN.md

# Implementation Plan: Enhanced Litters & Pedigree Features

## Project Overview
Complete implementation of litter management features and interactive pedigree visualization with family tree functionality.

## Phase 1: Interactive Pedigree Tree ✅ (Priority 1)

### 1.1 Core Pedigree Component
- [ ] Install react-d3-tree dependency
- [ ] Create PedigreeTree component with D3 visualization
- [ ] Implement data transformation from API to tree format
- [ ] Add zoom and pan controls
- [ ] Implement color coding (blue for males, pink for females)
- [ ] Add node click navigation
- [ ] Display node information (name, registration, birth year, sex)
- [ ] Show 5 generations by default

### 1.2 Pedigree Page Enhancement
- [ ] Replace placeholder with full PedigreeTree component
- [ ] Add generation selector (3, 4, 5 generations)
- [ ] Add COI display prominently
- [ ] Add "View as PDF" export button (future)
- [ ] Add "Print" button with print-friendly view
- [ ] Add loading states
- [ ] Add error handling for missing data
- [ ] Add breadcrumb navigation

### 1.3 Pedigree Features
- [ ] Collapsible/expandable nodes
- [ ] Tooltip on hover with full details
- [ ] Highlight common ancestors
- [ ] Show linebreeding indicators
- [ ] Add legend for colors and symbols
- [ ] Responsive design for mobile

---

## Phase 2: Enhanced Litter Management (Priority 2)

### 2.1 Litter Detail Page
- [ ] Create LitterDetail.jsx page
- [ ] Display litter overview card
  - [ ] Sire and dam information with photos
  - [ ] Breeding date
  - [ ] Expected whelping date (63 days)
  - [ ] Actual whelping date
  - [ ] Puppy count (expected vs actual)
  - [ ] COI calculation for the pairing
- [ ] Add timeline view of litter events
- [ ] Add notes section

### 2.2 Puppy Management
- [ ] Create PuppyBatchAdd component
  - [ ] Quick add multiple puppies form
  - [ ] Auto-increment names (Puppy 1, Puppy 2, etc.)
  - [ ] Bulk set common fields (breed, birth date)
  - [ ] Individual customization per puppy
- [ ] Puppy list view within litter
- [ ] Individual puppy cards with quick actions
- [ ] Drag-and-drop photo upload per puppy
- [ ] Bulk actions (delete, export)

### 2.3 Litter Photo Gallery
- [ ] Create LitterGallery component
- [ ] Upload litter photos (not tied to specific puppy)
- [ ] Display in grid/carousel view
- [ ] Photo captions and dates
- [ ] Delete/reorder photos
- [ ] Lightbox view for full-size images

### 2.4 Whelping Countdown
- [ ] Create CountdownWidget component
- [ ] Calculate days until expected whelping
- [ ] Show progress bar
- [ ] Alert when within 7 days
- [ ] Update when actual date recorded
- [ ] Show "days since birth" after whelping

### 2.5 Enhanced Litter List
- [ ] Add "Create New Litter" button
- [ ] Add filters (upcoming, current, past)
- [ ] Add search by parent names
- [ ] Add sorting (date, puppy count)
- [ ] Show countdown for upcoming litters
- [ ] Show puppy count badge
- [ ] Add quick actions (edit, view, delete)
- [ ] Add litter status badges (planned, pregnant, whelped)

### 2.6 Litter Form Enhancement
- [ ] Create comprehensive LitterForm component
- [ ] Add expected puppy count field
- [ ] Add notes/comments field
- [ ] Add breeding method dropdown (natural, AI, etc.)
- [ ] Add progesterone level tracking
- [ ] Add ultrasound confirmation date
- [ ] Validation for logical dates
- [ ] Auto-calculate expected whelping

---

## Phase 3: Litter Statistics & Analytics (Priority 3)

### 3.1 Litter Statistics Dashboard
- [ ] Create LitterStats component
- [ ] Display on Dashboard and LitterDetail pages
- [ ] Show average litter size
- [ ] Show male/female ratio
- [ ] Show breeding success rate
- [ ] Show most productive pairings
- [ ] Show genetic diversity metrics
- [ ] Charts using Chart.js or Recharts

### 3.2 Parent Performance
- [ ] Track individual sire/dam statistics
- [ ] Show on DogDetail page
- [ ] Number of litters produced
- [ ] Total offspring count
- [ ] Average litter size
- [ ] Success rate
- [ ] Link to all their litters

---

## Phase 4: Integration & Polish (Priority 4)

### 4.1 Dog Profile Integration
- [ ] Add "View Pedigree" button on DogDetail page
- [ ] Add "Litters" tab on DogDetail page
- [ ] Show offspring list
- [ ] Show parent information with links
- [ ] Show siblings

### 4.2 Navigation Enhancement
- [ ] Add Pedigree to main navigation
- [ ] Add Litters to main navigation
- [ ] Add breadcrumbs to all pages
- [ ] Add back buttons where appropriate

### 4.3 Performance Optimization
- [ ] Lazy load pedigree tree data
- [ ] Implement API caching for pedigree
- [ ] Optimize image loading for galleries
- [ ] Add loading skeletons
- [ ] Debounce search inputs

### 4.4 Error Handling & UX
- [ ] Add error boundaries
- [ ] Add retry mechanisms
- [ ] Add empty states for all lists
- [ ] Add confirmation dialogs for destructive actions
- [ ] Add success/error toast notifications
- [ ] Add form validation with helpful messages

---

## Technical Implementation Details

### Dependencies to Install
```json
{
  "react-d3-tree": "^3.6.2",
  "react-toastify": "^9.1.3",
  "date-fns": "^2.30.0"
}
```

### API Endpoints Needed

#### Existing (verify functionality)
- GET `/api/litters` - List all litters
- POST `/api/litters` - Create litter
- GET `/api/litters/:id` - Get litter details
- PUT `/api/litters/:id` - Update litter
- DELETE `/api/litters/:id` - Delete litter
- GET `/api/pedigree/:id` - Get pedigree tree

#### New Endpoints to Create
- POST `/api/litters/:id/puppies/batch` - Batch add puppies
- GET `/api/litters/:id/photos` - Get litter photos
- POST `/api/litters/:id/photos` - Upload litter photo
- DELETE `/api/litters/:id/photos/:photoId` - Delete litter photo
- GET `/api/litters/statistics` - Get litter statistics
- GET `/api/dogs/:id/offspring` - Get dog's offspring
- GET `/api/dogs/:id/litters` - Get dog's litters (as parent)

### Database Schema Changes

#### Add to `litters` table:
```sql
ALTER TABLE litters ADD COLUMN expected_puppy_count INTEGER;
ALTER TABLE litters ADD COLUMN actual_puppy_count INTEGER;
ALTER TABLE litters ADD COLUMN notes TEXT;
ALTER TABLE litters ADD COLUMN breeding_method VARCHAR(50);
ALTER TABLE litters ADD COLUMN progesterone_level DECIMAL(5,2);
ALTER TABLE litters ADD COLUMN ultrasound_date DATE;
ALTER TABLE litters ADD COLUMN status VARCHAR(20) DEFAULT 'planned';
```

#### Create `litter_photos` table:
```sql
CREATE TABLE IF NOT EXISTS litter_photos (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  litter_id INTEGER NOT NULL,
  filename VARCHAR(255) NOT NULL,
  path VARCHAR(255) NOT NULL,
  caption TEXT,
  upload_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  display_order INTEGER DEFAULT 0,
  FOREIGN KEY (litter_id) REFERENCES litters(id) ON DELETE CASCADE
);
```

### Component Structure

```
client/src/
├── components/
│   ├── PedigreeTree.jsx (NEW)
│   ├── PuppyBatchAdd.jsx (NEW)
│   ├── LitterGallery.jsx (NEW)
│   ├── CountdownWidget.jsx (NEW)
│   ├── LitterStats.jsx (NEW)
│   └── LitterForm.jsx (ENHANCE)
├── pages/
│   ├── PedigreeView.jsx (REBUILD)
│   ├── LitterList.jsx (ENHANCE)
│   ├── LitterDetail.jsx (NEW)
│   └── DogDetail.jsx (ENHANCE)
└── utils/
    ├── pedigreeHelpers.js (NEW)
    └── dateHelpers.js (NEW)
```

---

## Testing Checklist

### Pedigree Tree
- [ ] Displays correctly for dogs with complete lineage
- [ ] Handles missing parents gracefully
- [ ] Zoom and pan work smoothly
- [ ] Node clicks navigate to correct dog
- [ ] COI displays correctly
- [ ] Colors are correct for male/female
- [ ] Responsive on mobile
- [ ] Print view works

### Litter Management
- [ ] Can create new litter
- [ ] Can add puppies individually
- [ ] Can batch add puppies
- [ ] Puppies auto-link to litter parents
- [ ] Can upload photos
- [ ] Countdown displays correctly
- [ ] Expected vs actual puppy count tracks
- [ ] Can edit litter details
- [ ] Can delete litter (with confirmation)
- [ ] Statistics calculate correctly

### Integration
- [ ] Pedigree accessible from dog profile
- [ ] Litters show on parent profiles
- [ ] Navigation works smoothly
- [ ] No console errors
- [ ] Loading states display
- [ ] Error states display

---

## Implementation Order (Suggested)

### Sprint 1 (4-6 hours): Pedigree Tree
1. Install react-d3-tree
2. Create PedigreeTree component
3. Rebuild PedigreeView page
4. Add controls and styling
5. Test with existing data

### Sprint 2 (4-6 hours): Litter Detail & Enhancements
1. Create database migration for litter enhancements
2. Create LitterDetail page
3. Create CountdownWidget
4. Enhance LitterList
5. Create LitterForm enhancements

### Sprint 3 (3-4 hours): Puppy Management
1. Create PuppyBatchAdd component
2. Add batch API endpoint
3. Integrate into LitterDetail
4. Test puppy workflow

### Sprint 4 (2-3 hours): Photo Gallery
1. Create database migration for litter_photos
2. Create LitterGallery component
3. Add photo upload API endpoints
4. Integrate into LitterDetail

### Sprint 5 (2-3 hours): Statistics & Integration
1. Create LitterStats component
2. Add statistics API endpoint
3. Add pedigree/litter links to DogDetail
4. Update navigation

### Sprint 6 (2 hours): Polish & Testing
1. Add error handling
2. Add loading states
3. Add confirmation dialogs
4. Test all workflows
5. Fix bugs
6. Update documentation

---

## Success Criteria

### Pedigree
- ✅ Interactive tree with 5 generations
- ✅ Zoom, pan, and navigation work smoothly
- ✅ COI displayed prominently
- ✅ Print-friendly view available
- ✅ Responsive design

### Litters
- ✅ Full litter lifecycle management (planned → pregnant → whelped)
- ✅ Batch puppy addition saves time
- ✅ Photo galleries enhance visual tracking
- ✅ Countdown helps with planning
- ✅ Statistics provide insights
- ✅ Integration with dogs is seamless

---

## Documentation Updates Needed

- [ ] Update README.md with new features
- [ ] Update ROADMAP.md with completion status
- [ ] Create USER_GUIDE.md section for litters
- [ ] Create USER_GUIDE.md section for pedigree
- [ ] Document API endpoints in API_DOCS.md
- [ ] Add screenshots to documentation

---

## Notes

- Prioritize pedigree tree first as it's highly visible and impressive
- Litter features build on each other, implement in order
- Consider adding unit tests for complex calculations (COI, dates)
- Keep accessibility in mind (keyboard navigation, screen readers)
- Consider adding undo/redo for batch operations