diff --git a/QUICKSTART.md b/QUICKSTART.md new file mode 100644 index 0000000..85eac95 --- /dev/null +++ b/QUICKSTART.md @@ -0,0 +1,340 @@ +# 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! 🐶**