# BREEDR Quick Start Guide
## Litter Management & Pedigree Visualization

## Installation

### 1. Pull the Feature Branch
```bash
git checkout feature/litter-management-and-pedigree
```

### 2. Run Database Migration
```bash
node server/db/migrate_litter_id.js
```

You should see:
```
Running litter_id migration...
✓ Added litter_id column to dogs table
✓ Created index on litter_id
Migration completed successfully!
```

### 3. Install Dependencies
```bash
cd client
npm install
cd ..
```

### 4. Start the Application
```bash
npm run dev
```

The server will start on `http://localhost:3000` and the client on `http://localhost:5173`

---

## Feature 1: Litter Management

### Creating Your First Litter

1. **Navigate to Litters**
   - Click "Litters" in the navigation menu
   - Click "Add New Litter" button

2. **Fill in Litter Details**
   - **Sire (Father)**: Select from dropdown of male dogs
   - **Dam (Mother)**: Select from dropdown of female dogs
   - **Breeding Date**: Date of breeding (required)
   - **Whelping Date**: Expected/actual birth date (optional)
   - **Expected Puppy Count**: Estimated number of puppies
   - **Notes**: Any additional breeding information

3. **Save the Litter**
   - Click "Create Litter"
   - Litter appears in the list with format: "Sire x Dam - Date"

### Adding Puppies to a Litter

#### Method 1: Link to Existing Litter (Recommended)

1. **Click "Add New Dog"**
2. **Enter Puppy Details**
   - Name (required)
   - Breed (required)
   - Sex (required)
   - Birth Date
   - Color
   - Microchip

3. **Select Parent Method**
   - Choose "Link to Litter" radio button
   - Select the litter from dropdown
   - Parents are automatically filled!

4. **Save**
   - Click "Add Dog"
   - Puppy is now linked to the litter
   - Parent relationships are automatically created

#### Method 2: Manual Parent Selection

1. **Click "Add New Dog"**
2. **Enter Puppy Details**
3. **Select Parent Method**
   - Choose "Manual Parent Selection" radio button
   - Select Sire from male dogs dropdown
   - Select Dam from female dogs dropdown

4. **Save**
   - Puppy is created with selected parents
   - No litter association

### Viewing Litter Details

1. **Click on a Litter** in the list
2. **See Litter Information:**
   - Sire and Dam details
   - Breeding and whelping dates
   - List of all puppies in the litter
   - Actual puppy count vs expected

### Editing a Litter

1. Click "Edit" on the litter
2. Update breeding/whelping dates
3. Modify notes
4. **Note:** Cannot change sire/dam after creation

---

## Feature 2: Interactive Pedigree Tree

### Viewing a Pedigree

1. **From Dog List:**
   - Click on any dog
   - Click "View Pedigree" button

2. **Pedigree Opens in Modal**
   - Shows dog's ancestry tree
   - 5 generations displayed
   - Color-coded by sex:
     - Blue nodes = Males ♂
     - Pink nodes = Females ♀

### Navigating the Tree

#### Zoom Controls
- **Zoom In**: Click "+" button or mouse wheel up
- **Zoom Out**: Click "-" button or mouse wheel down
- **Reset View**: Click reset button to center tree

#### Panning
- **Click and Drag**: Move the tree around
- **Mouse Wheel**: Zoom in/out

#### Node Information
Each node displays:
- Dog name (large text)
- Registration number
- Birth year
- Sex symbol (♂ or ♀)

### Reading the Tree

```
                        Great-Great-Grandpa ♂
                   Great-Grandpa ♂
                        Great-Great-Grandma ♀
              Grandpa ♂
                        Great-Great-Grandpa ♂
                   Great-Grandma ♀
                        Great-Great-Grandma ♀
         Sire ♂
                        Great-Great-Grandpa ♂
                   Great-Grandpa ♂
                        Great-Great-Grandma ♀
              Grandma ♀
                        Great-Great-Grandpa ♂
                   Great-Grandma ♀
                        Great-Great-Grandma ♀
Dog Name
         Dam ♀
              [... similar structure for dam's side]
```

---

## Common Workflows

### Workflow 1: Breeding a Litter

1. ✓ Select breeding pair (sire and dam)
2. ✓ Create litter record with breeding date
3. ✓ Track whelping date when puppies are born
4. ✓ Add each puppy:
   - Link to the litter
   - Enter individual details
   - Assign registration numbers
5. ✓ View pedigree of any puppy to see full ancestry

### Workflow 2: Recording Historical Dogs

1. ✓ Add foundation dogs (no parents)
2. ✓ Add their offspring using manual parent selection
3. ✓ Continue building the family tree
4. ✓ View pedigrees to verify relationships

### Workflow 3: Planning a Breeding

1. ✓ View pedigrees of potential sire and dam
2. ✓ Check for common ancestors
3. ✓ Use trial pairing tool (coming soon)
4. ✓ Create litter when breeding occurs

---

## Tips & Best Practices

### For Litter Management

✅ **Do:**
- Create the litter record BEFORE adding puppies
- Enter accurate breeding dates for record keeping
- Use meaningful notes (progesterone timing, heat cycle info)
- Link puppies to litters for automatic parent relationships

❌ **Don't:**
- Don't change sire/dam after litter creation (create new litter instead)
- Don't forget to update whelping date when puppies arrive
- Avoid mixing litter-linked and manually-parented puppies

### For Pedigree Viewing

✅ **Do:**
- Zoom out to see the full tree at once
- Use drag to focus on specific branches
- Click nodes to see additional details
- Reset view if you get lost

❌ **Don't:**
- Don't try to edit from pedigree view (use dog edit form)
- Avoid excessive zooming (can make nodes too small)

### Data Entry Tips

1. **Registration Numbers**: Enter consistently (e.g., "AKC-12345")
2. **Microchips**: Use full 15-digit number
3. **Birth Dates**: Critical for age calculations and sorting
4. **Breed Names**: Keep consistent spelling and capitalization
5. **Colors**: Use standard color terminology for your breed

---

## Troubleshooting

### "No such column: sire" Error

**Problem:** Getting this error when adding a dog

**Solution:** 
1. Make sure you ran the migration:
   ```bash
   node server/db/migrate_litter_id.js
   ```
2. Restart the server
3. Try again

### Pedigree Tree Not Loading

**Problem:** Pedigree modal shows "Loading..." forever

**Possible Causes:**
- Dog has no parents recorded
- Network issue
- Server not running

**Solution:**
1. Check browser console for errors
2. Verify server is running
3. Ensure dog has at least one parent recorded

### Parents Not Auto-Populating

**Problem:** Selected a litter but parents didn't fill in

**Solution:**
1. Refresh the page
2. Make sure litter has valid sire and dam
3. Try selecting the litter again

### Can't See All Generations

**Problem:** Pedigree tree only shows 2-3 generations

**This is normal if:**
- Older generations don't have parents recorded
- Foundation dogs have no ancestry
- You need to add more historical data

---

## Keyboard Shortcuts

*Coming in future release*

- `Ctrl/Cmd + N` - New Dog
- `Ctrl/Cmd + L` - New Litter  
- `Ctrl/Cmd + P` - View Pedigree
- `Esc` - Close Modal

---

## Next Features Coming Soon

🔜 **Trial Pairing Simulator**
- Calculate COI before breeding
- See common ancestors
- Risk assessment

🔜 **Heat Cycle Tracking**
- Track progesterone levels
- Breeding date recommendations
- Calendar view

🔜 **PDF Pedigree Export**
- Print-ready pedigrees
- Custom formatting
- Multiple generations

---

## Getting Help

- **Documentation:** [FEATURE_IMPLEMENTATION.md](./FEATURE_IMPLEMENTATION.md)
- **Roadmap:** [ROADMAP.md](./ROADMAP.md)
- **Installation:** [INSTALL.md](./INSTALL.md)
- **README:** [README.md](./README.md)

---

## Video Tutorials

*Coming soon - check back for video walkthroughs of these features!*

1. Creating Your First Litter
2. Adding Puppies to a Litter
3. Navigating Pedigree Trees
4. Advanced Breeding Records

---

## Congratulations!

You're now ready to use BREEDR's litter management and pedigree visualization features. Start by creating a litter or viewing a pedigree tree!

**Happy Breeding! 🐶**