From c483096c6315f769ab2232a6d83777c265d7f261 Mon Sep 17 00:00:00 2001 From: jason Date: Thu, 12 Mar 2026 07:40:50 -0500 Subject: [PATCH] qs --- QUICKSTART.md | 359 +++++++------------------------------------------- 1 file changed, 50 insertions(+), 309 deletions(-) diff --git a/QUICKSTART.md b/QUICKSTART.md index 85eac95..75e1801 100644 --- a/QUICKSTART.md +++ b/QUICKSTART.md @@ -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! 🐶**