jason/breedr
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

qs

Browse Source
This commit is contained in:
jason
2026-03-12 07:40:50 -05:00
parent e4e3b44fcf
commit c483096c63
1 changed files with 50 additions and 309 deletions
Download Patch File Download Diff File Expand all files Collapse all files

359
QUICKSTART.md
View File

@@ -1,340 +1,81 @@
# BREEDR Quick Start Guide
## Litter Management & Pedigree Visualization
# BREEDR Quick Start Guide (v0.8.0)
## Installation
Welcome to BREEDR! This guide will help you get up and running with the most powerful kennel management and pedigree mapping features.
### 1. Pull the Feature Branch
---
## 🚀 Installation & Setup
### 1. The Easy Way (Docker)
Ensure you have Docker and Docker-Compose installed.
```bash
git checkout feature/litter-management-and-pedigree
git clone https://git.alwisp.com/jason/breedr.git
cd breedr
docker-compose up -d --build
```
Open your browser to `http://localhost:3000`.
### 2. Run Database Migration
### 2. Manual Development Setup
```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
# 1. Install project dependencies
npm install
cd ..
```
### 4. Start the Application
```bash
# 2. Start the dev environment (Frontend @ 5173, Backend @ 3000)
npm run dev
```
The server will start on `http://localhost:3000` and the client on `http://localhost:5173`
> **Note:** The database initializes automatically on first boot. No manual migrations are required.
---
## Feature 1: Litter Management
## 🐕 Managing Your Kennel
### Creating Your First Litter
### Adding or Importing Dogs
1. Go to the **Dogs** page.
2. Click **Add New Dog**.
3. Fill in the core details (Name, Registration, Breed, Sex).
4. **Pedigree Mapping**: You can select a Sire and Dam from your existing dogs.
5. **External Dogs**: Check "External Dog" if you are adding an ancestor that isn't in your kennel.
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
### Champion Tracking
- Use the **Champion Toggle** in the Add/Edit form to mark titled dogs.
- They will appear with a `✪` star in dropdowns and display a gold badge on their profile.
- Their offspring will automatically display the "Champion Bloodline" badge.
---
## Feature 2: Interactive Pedigree Tree
## 🧬 Breeding Tools
### Viewing a Pedigree
### 1. Pedigree Visualization
- Click **Pedigree** on any dog detail page.
- **Ancestors View**: Default interactive 5-generation tree.
- **Descendants View**: Toggle the switch in the header to see the "Reverse Pedigree" (offspring lineage).
- Use the mouse wheel or on-screen buttons to zoom and pan.
1. **From Dog List:**
- Click on any dog
- Click "View Pedigree" button
### 2. Trial Pairing Simulator
- Go to the **Pairing Simulator** via the flask icon in the navbar.
- Select a potential Sire and Dam.
- **COI Calculation**: Instantly see the Wright's Inbreeding Coefficient.
- **Ancestry Check**: The system flags common ancestors and provides a risk badge (Low < 5%, Moderate 5-10%, High > 10%).
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]
```
### 3. Heat Cycle Calendar
- Use the **Calendar** to track female heat cycles.
- **Phase Colors**: Automatically segments cycles into Proestrus, Optimal, Late, and Diestrus.
- **Projected Whelping**: Log a breeding date to see a indigo "Whelping Window" and expected due dates directly on the main calendar grid.
---
## 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
## ⚙️ Kennel Customization
- Visit the **Settings** page.
- Configure your Kennel Name, Tagline, Address, and Contact info.
- This information updates your site branding and navbar automatically.
---
## 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
- **COI shows 0.00%?**: Ensure you have both parents mapped and that they have shared ancestors.
- **Image not loading?**: Ensure `br-logo.png` is in the `static/` folder for branding.
- **Database "No such column"?**: Simply restart the app; the auto-init logic will fix the schema.
---
## 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! 🐶**