qs
This commit is contained in:
359
QUICKSTART.md
359
QUICKSTART.md
@@ -1,340 +1,81 @@
|
|||||||
# BREEDR Quick Start Guide
|
# BREEDR Quick Start Guide (v0.8.0)
|
||||||
## Litter Management & Pedigree Visualization
|
|
||||||
|
|
||||||
## 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
|
```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
|
```bash
|
||||||
node server/db/migrate_litter_id.js
|
# 1. Install project dependencies
|
||||||
```
|
|
||||||
|
|
||||||
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
|
npm install
|
||||||
cd ..
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4. Start the Application
|
# 2. Start the dev environment (Frontend @ 5173, Backend @ 3000)
|
||||||
```bash
|
|
||||||
npm run dev
|
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**
|
### Champion Tracking
|
||||||
- Click "Litters" in the navigation menu
|
- Use the **Champion Toggle** in the Add/Edit form to mark titled dogs.
|
||||||
- Click "Add New Litter" button
|
- 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.
|
||||||
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
|
## 🧬 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:**
|
### 2. Trial Pairing Simulator
|
||||||
- Click on any dog
|
- Go to the **Pairing Simulator** via the flask icon in the navbar.
|
||||||
- Click "View Pedigree" button
|
- 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**
|
### 3. Heat Cycle Calendar
|
||||||
- Shows dog's ancestry tree
|
- Use the **Calendar** to track female heat cycles.
|
||||||
- 5 generations displayed
|
- **Phase Colors**: Automatically segments cycles into Proestrus, Optimal, Late, and Diestrus.
|
||||||
- Color-coded by sex:
|
- **Projected Whelping**: Log a breeding date to see a indigo "Whelping Window" and expected due dates directly on the main calendar grid.
|
||||||
- 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
|
## ⚙️ Kennel Customization
|
||||||
|
- Visit the **Settings** page.
|
||||||
### Workflow 1: Breeding a Litter
|
- Configure your Kennel Name, Tagline, Address, and Contact info.
|
||||||
|
- This information updates your site branding and navbar automatically.
|
||||||
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
|
## ❓ Troubleshooting
|
||||||
|
- **COI shows 0.00%?**: Ensure you have both parents mapped and that they have shared ancestors.
|
||||||
### For Litter Management
|
- **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.
|
||||||
✅ **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! 🐶**
|
**Happy Breeding! 🐶**
|
||||||
|
|||||||
Reference in New Issue
Block a user