breedr/QUICKSTART.md

BREEDR Quick Start Guide

Litter Management & Pedigree Visualization

Installation

1. Pull the Feature Branch

git checkout feature/litter-management-and-pedigree

2. Run Database Migration

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

cd client
npm install
cd ..

4. Start the Application

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:

   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
• Roadmap: ROADMAP.md
• Installation: INSTALL.md
• README: 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! 🐶