From e3bea6593c70153f2c1af07affa9cc44076f80f0 Mon Sep 17 00:00:00 2001 From: Jason UNRAID Date: Mon, 9 Mar 2026 02:24:10 -0500 Subject: [PATCH] Clean: Remove outdated documentation --- DATABASE_MIGRATIONS.md | 345 -------------------------- DEPLOY_NOW.md | 466 ----------------------------------- FEATURE_IMPLEMENTATION.md | 368 --------------------------- FRONTEND_FIX_REQUIRED.md | 408 ------------------------------ IMPLEMENTATION_PLAN.md | 350 -------------------------- SPRINT1_PEDIGREE_COMPLETE.md | 305 ----------------------- migrate-now.sh | 37 --- 7 files changed, 2279 deletions(-) delete mode 100644 DATABASE_MIGRATIONS.md delete mode 100644 DEPLOY_NOW.md delete mode 100644 FEATURE_IMPLEMENTATION.md delete mode 100644 FRONTEND_FIX_REQUIRED.md delete mode 100644 IMPLEMENTATION_PLAN.md delete mode 100644 SPRINT1_PEDIGREE_COMPLETE.md delete mode 100644 migrate-now.sh diff --git a/DATABASE_MIGRATIONS.md b/DATABASE_MIGRATIONS.md deleted file mode 100644 index 28642ee..0000000 --- a/DATABASE_MIGRATIONS.md +++ /dev/null @@ -1,345 +0,0 @@ -# BREEDR Database Migrations - -## Automatic Migration System - -BREEDR now includes an **automatic migration system** that runs on every startup to ensure your database schema is always correct and up-to-date. - -## How It Works - -### On Every Startup - -1. **Initialize Database** - Creates tables if they don't exist -2. **Run Migrations** - Automatically fixes schema issues -3. **Validate Schema** - Verifies everything is correct -4. **Start Application** - Server begins accepting requests - -You don't need to do anything manually! - ---- - -## Migrations Included - -### Migration 001: Remove Old Parent Columns - -**Problem**: Old schema had `sire` and `dam` columns in the `dogs` table causing "no such column: sire" errors. - -**Solution**: -- Creates `parents` table for relationships -- Migrates existing sire/dam data to `parents` table -- Recreates `dogs` table without sire/dam columns -- Preserves all existing dog data - -**Automatic**: Runs only if old schema detected - -### Migration 002: Add Litter ID Column - -**Problem**: Dogs table missing `litter_id` column for linking puppies to litters. - -**Solution**: -- Adds `litter_id` column to `dogs` table -- Creates foreign key to `litters` table - -**Automatic**: Runs only if column is missing - ---- - -## Schema Version Tracking - -The migration system uses a `schema_version` table to track which migrations have been applied: - -```sql -CREATE TABLE schema_version ( - version INTEGER PRIMARY KEY, - applied_at DATETIME DEFAULT CURRENT_TIMESTAMP, - description TEXT -); -``` - -Each migration runs only once, even if you restart the server multiple times. - ---- - -## Correct Schema (Current) - -### Dogs Table (No sire/dam columns!) - -```sql -CREATE TABLE dogs ( - id INTEGER PRIMARY KEY AUTOINCREMENT, - name TEXT NOT NULL, - registration_number TEXT, - microchip TEXT, - sex TEXT CHECK(sex IN ('male', 'female')), - birth_date DATE, - breed TEXT, - color TEXT, - weight REAL, - height REAL, - notes TEXT, - litter_id INTEGER, - photo_urls TEXT, - is_active INTEGER DEFAULT 1, - created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, - updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, - FOREIGN KEY (litter_id) REFERENCES litters(id) ON DELETE SET NULL -); -``` - -### Parents Table (Relationships) - -```sql -CREATE TABLE parents ( - id INTEGER PRIMARY KEY AUTOINCREMENT, - dog_id INTEGER NOT NULL, - parent_id INTEGER NOT NULL, - parent_type TEXT NOT NULL CHECK(parent_type IN ('sire', 'dam')), - FOREIGN KEY (dog_id) REFERENCES dogs(id) ON DELETE CASCADE, - FOREIGN KEY (parent_id) REFERENCES dogs(id) ON DELETE CASCADE, - UNIQUE(dog_id, parent_type) -); -``` - ---- - -## How to Use - -### Normal Startup (Automatic) - -Just start your application normally: - -```bash -# With Docker -docker-compose up -d - -# Without Docker -cd server && npm start -``` - -Migrations run automatically! - -### Check Migration Logs - -Look at the server console output: - -``` -============================================================ -BREEDR Database Migration System -============================================================ -Database: /app/data/breedr.db - -Current schema version: 0 - -[Migration 001] Checking for old sire/dam columns... -[Migration 001] Found old schema with sire/dam columns -[Migration 001] Migrating to parents table... -[Migration 001] Backed up 15 dogs -[Migration 001] Migrated 8 sire relationships -[Migration 001] Migrated 8 dam relationships -[Migration 001] Dropped old dogs table -[Migration 001] Created new dogs table -[Migration 001] Restored 15 dogs -[Migration 001] ✓ Migration complete! - -[Migration 002] Checking for litter_id column... -[Migration 002] litter_id column already exists, skipping - -[Validation] ✓ Dogs table exists -[Validation] ✓ Dogs table has no sire/dam columns -[Validation] ✓ Parents table exists -[Validation] ✓ Litter_id column exists -[Validation] ✓ Litters table exists -[Validation] ✓ All schema checks passed! - -============================================================ -Schema version: 0 → 2 -Migration system complete! -============================================================ -``` - -### Manual Migration (If Needed) - -You can also run migrations manually: - -```bash -node server/db/migrations.js -``` - ---- - -## Fresh Install - -For a fresh installation: - -1. **No database file exists** → `init.js` creates correct schema -2. **Migrations check schema** → Everything already correct, no migration needed -3. **Application starts** → Ready to use! - -**Result**: Fresh installs automatically have the correct schema. - ---- - -## Upgrading from Old Version - -For existing installations with old schema: - -1. **Old database detected** → Migration system kicks in -2. **Data is backed up** → Safety first! -3. **Schema is updated** → Sire/dam data moved to parents table -4. **Data is restored** → All your dogs are preserved -5. **Application starts** → Now using correct schema! - -**Result**: Existing data is preserved and schema is fixed automatically. - ---- - -## Docker Integration - -### Dockerfile - -No changes needed! Migrations run automatically when the container starts. - -### docker-compose.yml - -No changes needed! Just restart: - -```bash -docker-compose restart -``` - -Or rebuild: - -```bash -docker-compose down -docker-compose up --build -d -``` - ---- - -## Troubleshooting - -### Migration Failed - -If you see an error: - -``` -⚠️ Database migration failed! -Error: [error message] -``` - -1. **Check the error message** - It will tell you what went wrong -2. **Check database file permissions** - Make sure the file is writable -3. **Check disk space** - Ensure you have enough space -4. **Try manual migration**: - ```bash - node server/db/migrations.js - ``` - -### Database is Locked - -If migrations fail with "database is locked": - -1. Stop all running instances of BREEDR -2. Check for zombie processes: `ps aux | grep node` -3. Kill any old processes: `kill ` -4. Restart BREEDR - -### Migration Keeps Running - -If the same migration runs every time: - -1. Check `schema_version` table: - ```sql - SELECT * FROM schema_version; - ``` -2. If empty, migration isn't being recorded -3. Check for database transaction issues -4. Manually add version: - ```sql - INSERT INTO schema_version (version, description) VALUES (1, 'Manual fix'); - ``` - -### Want to Start Fresh - -To completely reset the database: - -1. **Stop BREEDR** -2. **Backup your data** (optional): - ```bash - cp data/breedr.db data/breedr.db.backup - ``` -3. **Delete database**: - ```bash - rm data/breedr.db - ``` -4. **Restart BREEDR** - Fresh database will be created - ---- - -## Validation Checks - -The migration system validates your schema: - -- ✓ Dogs table exists -- ✓ Dogs table has no sire/dam columns -- ✓ Parents table exists -- ✓ Litter_id column exists -- ✓ Litters table exists - -If any check fails, you'll see a warning. - ---- - -## Adding New Migrations - -If you need to add a new migration: - -1. **Edit `server/db/migrations.js`** -2. **Add new migration function**: - ```javascript - migration003_yourNewMigration() { - console.log('[Migration 003] Doing something...'); - // Your migration code here - } - ``` -3. **Add to runMigrations()**: - ```javascript - if (currentVersion < 3) { - this.migration003_yourNewMigration(); - this.recordMigration(3, 'Description of migration'); - } - ``` -4. **Test thoroughly** before deploying - ---- - -## Best Practices - -1. **Let migrations run automatically** - Don't skip them -2. **Check logs on startup** - Verify migrations succeeded -3. **Backup before major updates** - Safety first -4. **Test in development** - Before deploying to production -5. **Monitor schema_version** - Know what version you're on - ---- - -## Schema Version History - -| Version | Description | Date | -|---------|-------------|------| -| 0 | Initial schema (may have sire/dam columns) | - | -| 1 | Migrated to parents table | March 2026 | -| 2 | Added litter_id column | March 2026 | - ---- - -## Summary - -✅ **Migrations run automatically on every startup** -✅ **No manual intervention needed** -✅ **Data is preserved during migrations** -✅ **Schema is validated after migrations** -✅ **Works with Docker and standalone** -✅ **Fresh installs get correct schema** -✅ **Old installs are automatically upgraded** - -**The "no such column: sire" error is now fixed automatically!** 🎉 diff --git a/DEPLOY_NOW.md b/DEPLOY_NOW.md deleted file mode 100644 index 2e9cdaa..0000000 --- a/DEPLOY_NOW.md +++ /dev/null @@ -1,466 +0,0 @@ -# 🚀 BREEDR v0.4.0 - Ready to Deploy! - -## ✅ What's Fixed - -### Database Migration System -- **Automatic migrations** run on every server startup -- Detects and fixes old `sire`/`dam` column schema -- Migrates existing data to `parents` table -- Adds missing `litter_id` column -- Validates schema after migration -- **NO MANUAL SQL REQUIRED!** - -### Frontend Form Fix -- Updated `DogForm.jsx` to ensure `sire_id` and `dam_id` are sent as `null` instead of empty strings -- Improved ID field handling with proper type conversion -- Better null value handling throughout the form - -### Features Included -- ✅ Interactive pedigree tree with D3 visualization -- ✅ Litter management with parent auto-linking -- ✅ Dual parent selection mode (litter or manual) -- ✅ Enhanced error handling -- ✅ Automatic database repairs - ---- - -## 📦 Files Changed in This Branch - -### Backend -- `server/db/migrations.js` - **NEW** Automatic migration system -- `server/index.js` - Runs migrations on startup -- `server/routes/dogs.js` - Already correct (uses `sire_id`/`dam_id`) - -### Frontend -- `client/src/components/DogForm.jsx` - **FIXED** Null value handling -- `client/src/components/PedigreeTree.jsx` - **NEW** D3 visualization -- `client/src/components/PedigreeTree.css` - **NEW** Styling -- `client/src/utils/pedigreeHelpers.js` - **NEW** Utility functions -- `client/src/pages/PedigreeView.jsx` - **UPDATED** Full page - -### Documentation -- `DATABASE_MIGRATIONS.md` - Complete migration guide -- `FRONTEND_FIX_REQUIRED.md` - Frontend fix reference -- `IMPLEMENTATION_PLAN.md` - Sprint planning -- `SPRINT1_PEDIGREE_COMPLETE.md` - Sprint 1 summary -- `DEPLOY_NOW.md` - **THIS FILE** Deployment guide - ---- - -## 🚀 How to Deploy - -### Step 1: Pull the Branch - -```bash -cd /path/to/breedr -git fetch origin -git checkout feature/enhanced-litters-and-pedigree -git pull origin feature/enhanced-litters-and-pedigree -``` - -### Step 2: Deploy with Docker (Recommended) - -```bash -# Stop current containers -docker-compose down - -# Rebuild with new code -docker-compose build - -# Start containers -docker-compose up -d - -# Watch logs to see migration -docker-compose logs -f breedr -``` - -**You should see:** -``` -============================================================ -BREEDR Database Migration System -============================================================ -[Migration 001] Checking for old sire/dam columns... -[Migration 001] Schema is already correct, skipping - OR -[Migration 001] Migrating to parents table... -[Migration 001] ✓ Migration complete! - -[Validation] ✓ All schema checks passed! -============================================================ - -BREEDR Server Running on port 3000 -``` - -### Step 3: Deploy Without Docker - -```bash -# Install dependencies -cd server && npm install -cd ../client && npm install - -# Build frontend -npm run build - -# Start server (migrations run automatically) -cd ../server -npm start -``` - ---- - -## ✔️ Post-Deployment Testing - -### 1. Server Startup -- [ ] Server starts without errors -- [ ] Migration logs show success -- [ ] No database errors in console - -### 2. Add Dog Form -- [ ] Open "Add New Dog" modal -- [ ] Form displays correctly -- [ ] Can select Sire from dropdown -- [ ] Can select Dam from dropdown -- [ ] Can link to a litter -- [ ] Submit creates dog successfully -- [ ] **No "sire column" error!** ✅ - -### 3. Edit Dog Form -- [ ] Open existing dog -- [ ] Click "Edit" -- [ ] Parents display correctly -- [ ] Can change parents -- [ ] Save works without errors - -### 4. Pedigree Tree -- [ ] Navigate to dog with parents -- [ ] Pedigree tree displays -- [ ] Can zoom and pan -- [ ] Can click nodes to navigate -- [ ] COI displays correctly -- [ ] Generation selector works - -### 5. Litter Features -- [ ] Can create new litter -- [ ] Can add puppy linked to litter -- [ ] Parents auto-populate from litter -- [ ] Litter selection dropdown works - ---- - -## 🔍 Troubleshooting - -### Issue: Migration doesn't run - -**Check:** -```bash -# View server logs -docker-compose logs breedr - -# Or if running locally -cat server.log -``` - -**Manual migration:** -```bash -# In Docker -docker exec breedr node /app/server/db/migrations.js - -# Locally -node server/db/migrations.js -``` - -### Issue: Still getting "sire column" error - -**Possible causes:** -1. Old frontend code cached in browser - - **Fix:** Hard refresh (Ctrl+Shift+R or Cmd+Shift+R) - - **Fix:** Clear browser cache - -2. Container not rebuilt - - **Fix:** `docker-compose down && docker-compose up --build -d` - -3. Wrong branch - - **Fix:** `git branch` to verify on `feature/enhanced-litters-and-pedigree` - -### Issue: Form shows blank screen - -**Cause:** Frontend build issue - -**Fix:** -```bash -cd client -rm -rf dist node_modules -npm install -npm run build -``` - -### Issue: Database locked error - -**Cause:** Multiple processes accessing database - -**Fix:** -```bash -# Stop all instances -docker-compose down -pkill -f "node.*server" - -# Restart -docker-compose up -d -``` - ---- - -## 📊 Database Schema (Current) - -### Dogs Table -```sql -CREATE TABLE dogs ( - id INTEGER PRIMARY KEY AUTOINCREMENT, - name TEXT NOT NULL, - registration_number TEXT, - microchip TEXT, - sex TEXT CHECK(sex IN ('male', 'female')), - birth_date DATE, - breed TEXT, - color TEXT, - weight REAL, - height REAL, - notes TEXT, - litter_id INTEGER, -- ✅ Links to litter - photo_urls TEXT, - is_active INTEGER DEFAULT 1, - created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, - updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, - FOREIGN KEY (litter_id) REFERENCES litters(id) -); --- ❌ NO sire or dam columns! -``` - -### Parents Table (Relationships) -```sql -CREATE TABLE parents ( - id INTEGER PRIMARY KEY AUTOINCREMENT, - dog_id INTEGER NOT NULL, - parent_id INTEGER NOT NULL, - parent_type TEXT NOT NULL CHECK(parent_type IN ('sire', 'dam')), - FOREIGN KEY (dog_id) REFERENCES dogs(id) ON DELETE CASCADE, - FOREIGN KEY (parent_id) REFERENCES dogs(id) ON DELETE CASCADE, - UNIQUE(dog_id, parent_type) -); -``` - ---- - -## 📈 What Changed - -### From Old Schema -```sql -CREATE TABLE dogs ( - ... - sire INTEGER, -- ❌ OLD - dam INTEGER, -- ❌ OLD - ... -); -``` - -### To New Schema -```sql -CREATE TABLE dogs ( - ... - litter_id INTEGER, -- ✅ NEW - ... -); - -CREATE TABLE parents ( -- ✅ NEW - dog_id INTEGER, - parent_id INTEGER, - parent_type TEXT -- 'sire' or 'dam' -); -``` - -**Why?** -- More flexible relationship model -- Easier to query ancestry -- Better data integrity -- Supports future features (multiple parents, etc.) - ---- - -## 📄 Migration Details - -### What Gets Migrated - -**Migration 001: Remove sire/dam columns** -1. Backup all dogs from old table -2. Extract sire relationships -3. Extract dam relationships -4. Drop old table -5. Create new table (without sire/dam) -6. Restore all dogs -7. Create parent relationships in `parents` table - -**Migration 002: Add litter_id column** -1. Check if column exists -2. If missing, add column -3. Create foreign key constraint - -### Data Preservation - -All existing dog data is preserved: -- ✅ Dog names -- ✅ Registration numbers -- ✅ Breeds, colors, dates -- ✅ Photos -- ✅ Notes -- ✅ **Parent relationships** (moved to `parents` table) - -**Nothing is lost!** - ---- - -## 📝 API Contract - -### POST /api/dogs - -**Request:** -```json -{ - "name": "Buddy", - "breed": "Golden Retriever", - "sex": "male", - "sire_id": 5, // ✅ ID or null - "dam_id": 8, // ✅ ID or null - "litter_id": 2, // ✅ ID or null - "birth_date": "2024-01-15", - "registration_number": "GR12345", - "microchip": "123456789", - "color": "Golden", - "notes": "Good temperament" -} -``` - -**Response:** -```json -{ - "id": 15, - "name": "Buddy", - "breed": "Golden Retriever", - "sex": "male", - "litter_id": 2, - "birth_date": "2024-01-15", - "registration_number": "GR12345", - "microchip": "123456789", - "color": "Golden", - "notes": "Good temperament", - "photo_urls": [], - "is_active": 1, - "created_at": "2026-03-09T06:15:00.000Z", - "updated_at": "2026-03-09T06:15:00.000Z" -} -``` - -**Note:** `sire` and `dam` objects are added by GET endpoint, not stored in table. - ---- - -## 🚀 After Successful Deployment - -### Verify Everything Works - -1. **Server Console** - - No errors - - Migration completed successfully - - Server listening on port 3000 - -2. **Browser Console** (F12) - - No JavaScript errors - - API calls succeed (200 status) - - No "sire" or "dam" column errors - -3. **Functionality** - - Add dog works - - Edit dog works - - Parents save correctly - - Pedigree tree displays - - Litters link properly - -### Next Steps - -1. **Merge to master** (after testing) - ```bash - git checkout master - git merge feature/enhanced-litters-and-pedigree - git push origin master - ``` - -2. **Tag release** - ```bash - git tag -a v0.4.0 -m "Database migration system + pedigree tree" - git push origin v0.4.0 - ``` - -3. **Update ROADMAP.md** with next sprint - -4. **Celebrate!** 🎉 The "sire column" error is gone forever! - ---- - -## 📊 Version Info - -**Current Version:** v0.4.0 -**Branch:** `feature/enhanced-litters-and-pedigree` -**Date:** March 9, 2026 - -### What's New -- ✅ Automatic database migration system -- ✅ Interactive pedigree tree visualization -- ✅ Litter management improvements -- ✅ Enhanced error handling -- ✅ **Fixed "sire column" error permanently** - -### Breaking Changes -- **None** - Migrations handle all schema updates automatically -- Existing data is preserved and migrated - ---- - -## ❓ Need Help? - -### Common Questions - -**Q: Will I lose my data?** -A: No! Migrations backup and restore all data. - -**Q: Do I need to run SQL manually?** -A: No! Everything is automatic on server startup. - -**Q: What if migration fails?** -A: Server won't start. Check logs, fix issue, restart. - -**Q: Can I rollback?** -A: Yes, checkout previous branch and restore database backup. - -**Q: Will this fix the sire error?** -A: Yes! 100%. The error is eliminated at the root cause. - -### Support - -If you encounter issues: - -1. Check this deployment guide -2. Review `DATABASE_MIGRATIONS.md` -3. Check server logs -4. Review `FRONTEND_FIX_REQUIRED.md` for frontend issues - ---- - -## 🎉 Summary - -✅ **Backend migrations** - Automatic, tested, safe -✅ **Frontend fixes** - Proper null handling -✅ **Pedigree tree** - Beautiful visualization -✅ **Litter management** - Enhanced features -✅ **Documentation** - Complete guides -✅ **Error fixed** - "sire column" error eliminated - -**Ready to deploy!** Just pull the branch and restart. 🚀 diff --git a/FEATURE_IMPLEMENTATION.md b/FEATURE_IMPLEMENTATION.md deleted file mode 100644 index 9f6fd0b..0000000 --- a/FEATURE_IMPLEMENTATION.md +++ /dev/null @@ -1,368 +0,0 @@ -# Feature Implementation: Litter Management & Interactive Pedigree - -## Overview - -This feature branch implements two major enhancements to the BREEDR system: - -1. **Complete Litter Management System** - Fixes the puppy addition issue and provides full litter tracking -2. **Interactive Pedigree Tree Visualization** - Beautiful, zoomable pedigree trees using react-d3-tree - -## Problem Solved - -### Original Issue -When attempting to add a puppy, users encountered the error: -``` -no such column: sire -``` - -This occurred because: -- The `dogs` table uses a `parents` relationship table for lineage -- The `litters` table existed but had no linkage mechanism to puppies -- The DogForm tried to reference non-existent direct parent columns - -## Implementation - -### 1. Database Migration - -**File:** `server/db/migrate_litter_id.js` - -Adds a `litter_id` column to the `dogs` table to link puppies to their litters: - -```sql -ALTER TABLE dogs ADD COLUMN litter_id INTEGER; -CREATE INDEX idx_dogs_litter ON dogs(litter_id); -``` - -To run the migration: -```bash -node server/db/migrate_litter_id.js -``` - -### 2. Enhanced Litter API - -**File:** `server/routes/litters.js` - -New endpoints: -- `POST /api/litters/:id/puppies/:puppyId` - Link puppy to litter -- `DELETE /api/litters/:id/puppies/:puppyId` - Remove puppy from litter -- Enhanced `GET /api/litters` - Returns litters with puppy counts - -Auto-linking logic: -- When a puppy is linked to a litter, sire/dam relationships are automatically created in the `parents` table -- Prevents orphaned data when litters are deleted - -### 3. Updated DogForm Component - -**File:** `client/src/components/DogForm.jsx` - -Key Features: -- **Dual Parent Selection Mode:** - - Option 1: Link to existing litter (auto-populates parents) - - Option 2: Manual parent selection (traditional method) -- Radio button toggle for selection mode -- Litter dropdown shows "Sire x Dam - Date" format -- Automatic breed inheritance from litter parents - -### 4. New LitterForm Component - -**File:** `client/src/components/LitterForm.jsx` - -Features: -- Create/edit litter records -- Select sire and dam from dropdown lists -- Track breeding date, whelping date, expected puppy count -- Notes field for breeding details -- Validation: ensures sire is male, dam is female - -### 5. Interactive Pedigree Visualization - -**Files:** -- `client/src/components/PedigreeView.jsx` -- `client/src/components/PedigreeView.css` - -**Features:** -- **Beautiful Tree Visualization:** - - Horizontal tree layout (left to right) - - Color-coded nodes: Blue for males, Pink for females - - Shows 5 generations by default - -- **Interactive Controls:** - - Zoom in/out buttons - - Reset view button - - Mouse wheel zoom support - - Click and drag to pan - - Click nodes for details - -- **Node Information:** - - Dog name (primary) - - Registration number - - Birth year - - Sex indicator (♂/♀) - -- **Uses COI Calculator Backend:** - - Leverages existing `/api/pedigree/:id` endpoint - - Recursive ancestor tree building - - Supports configurable generation depth - -## Usage - -### Adding a Puppy from a Litter - -1. Create a litter first: - - Navigate to Litters section - - Click "Add New Litter" - - Select sire and dam - - Enter breeding date - - Save - -2. Add puppies to the litter: - - Click "Add New Dog" - - Enter puppy details - - Select "Link to Litter" radio button - - Choose the litter from dropdown - - Parents are auto-populated - - Save - -### Viewing Pedigree Trees - -1. From any dog detail page: - - Click "View Pedigree" button - - Interactive tree opens in modal - - Use zoom/pan controls to navigate - - Click nodes to see details - -### Manual Parent Assignment - -For dogs not part of a formal litter: -1. Click "Add New Dog" -2. Enter dog details -3. Select "Manual Parent Selection" -4. Choose sire and dam from dropdowns -5. Save - -## Technical Details - -### Data Flow: Litter to Puppy - -``` -1. User creates litter (sire_id, dam_id, breeding_date) - ↓ -2. Litter gets unique ID - ↓ -3. User adds puppy with litter_id - ↓ -4. Backend auto-creates parent relationships: - - INSERT INTO parents (puppy_id, sire_id, 'sire') - - INSERT INTO parents (puppy_id, dam_id, 'dam') - ↓ -5. Puppy linked to litter and parents -``` - -### Pedigree Tree Data Structure - -```javascript -{ - name: "Dog Name", - attributes: { - sex: "male", - birth_date: "2020-01-15", - registration: "AKC12345", - breed: "Golden Retriever", - generation: 0 - }, - children: [ - { /* Sire node */ }, - { /* Dam node */ } - ] -} -``` - -### React-D3-Tree Configuration - -```javascript - -``` - -## Database Schema Updates - -### Before -```sql -CREATE TABLE dogs ( - id INTEGER PRIMARY KEY, - name TEXT NOT NULL, - -- ... other fields - -- NO litter_id column -); - -CREATE TABLE parents ( - dog_id INTEGER, - parent_id INTEGER, - parent_type TEXT -- 'sire' or 'dam' -); -``` - -### After -```sql -CREATE TABLE dogs ( - id INTEGER PRIMARY KEY, - name TEXT NOT NULL, - -- ... other fields - litter_id INTEGER -- NEW: Links to litters table -); - -CREATE INDEX idx_dogs_litter ON dogs(litter_id); -``` - -## API Changes - -### New Endpoints - -``` -POST /api/litters/:id/puppies/:puppyId -DELETE /api/litters/:id/puppies/:puppyId -``` - -### Modified Endpoints - -``` -GET /api/litters - Response now includes: - - actual_puppy_count: Real count from database - - puppies: Array of linked puppies - -POST /api/dogs - Accepts new field: - - litter_id: Optional litter association -``` - -## Dependencies - -### New npm packages added: -- `react-d3-tree@^3.6.2` - Tree visualization library - -### Existing dependencies leveraged: -- `lucide-react` - Icons for UI controls -- `axios` - API communication -- `react` - Component framework - -## Testing Checklist - -- [ ] Run database migration -- [ ] Create a new litter -- [ ] Add puppies to litter via DogForm -- [ ] Verify parent relationships auto-created -- [ ] View pedigree tree for a dog with 3+ generations -- [ ] Test zoom/pan controls in pedigree view -- [ ] Add dog with manual parent selection -- [ ] Edit existing dog and change litter assignment -- [ ] Delete litter and verify puppies remain (litter_id set to NULL) - -## Future Enhancements - -1. **Litter Dashboard:** - - Visual cards for each litter - - Photos of puppies - - Whelping countdown - -2. **Enhanced Pedigree Features:** - - Print to PDF - - Color coding by health clearances - - COI display on tree nodes - - Descendant tree (reverse pedigree) - -3. **Batch Operations:** - - Add multiple puppies at once - - Bulk photo upload for litter - - Auto-naming scheme (Litter Letter + Name) - -4. **Analytics:** - - Average litter size by pairing - - Color distribution predictions - - Genetic diversity metrics - -## Migration Path - -### From Current System - -1. Pull feature branch -2. Run migration: `node server/db/migrate_litter_id.js` -3. Install dependencies: `cd client && npm install` -4. Restart server -5. Existing dogs remain unchanged -6. Start creating litters for new puppies - -### Rollback Plan - -If issues arise: -1. The `litter_id` column can remain NULL -2. System continues to work with manual parent selection -3. No data loss occurs -4. Simply don't use litter feature until fixed - -## Architecture Decisions - -### Why litter_id Column? - -**Considered alternatives:** -1. ✗ Bridge table `litter_puppies` - Adds complexity, same result -2. ✗ JSON array in `litters.puppy_ids` - Poor query performance -3. ✓ **Foreign key in dogs table** - Simple, performant, standard pattern - -### Why Radio Button Toggle? - -**User Experience:** -- Clear visual distinction between modes -- Prevents accidental litter/manual mixing -- Familiar UI pattern -- Easy to understand for non-technical users - -### Why react-d3-tree? - -**Alternatives evaluated:** -- D3.js directly - Too much custom code required -- vis.js - Not React-friendly -- react-family-tree - Less flexible -- **react-d3-tree** - ✓ React-native, customizable, maintained - -## Performance Considerations - -1. **Pedigree Loading:** - - Recursive queries limited to 5 generations - - Indexes on `parents` table ensure fast lookups - - Tree data cached in component state - -2. **Litter Queries:** - - New index on `dogs.litter_id` enables fast filtering - - Puppy counts calculated efficiently via JOIN - -3. **Frontend Rendering:** - - React-d3-tree uses virtual DOM for smooth updates - - Lazy loading prevents rendering off-screen nodes - -## Security Notes - -- All parent/litter relationships validated server-side -- Gender validation prevents invalid pairings -- Foreign key relationships ensure referential integrity -- SQL injection prevented via parameterized queries - -## Contributing - -When extending these features: - -1. **Backend changes:** Update `server/routes/litters.js` -2. **Frontend forms:** Modify `client/src/components/LitterForm.jsx` or `DogForm.jsx` -3. **Visualization:** Edit `client/src/components/PedigreeView.jsx` -4. **Database:** Create new migration file following naming convention - -## Questions? - -See [ROADMAP.md](./ROADMAP.md) for feature priorities or check [README.md](./README.md) for general project info. diff --git a/FRONTEND_FIX_REQUIRED.md b/FRONTEND_FIX_REQUIRED.md deleted file mode 100644 index e2122b3..0000000 --- a/FRONTEND_FIX_REQUIRED.md +++ /dev/null @@ -1,408 +0,0 @@ -# Frontend Fix Required: Add Dog Form - -## Problem - -The database and API are correct, but the **Add Dog frontend form** is still trying to use old `sire`/`dam` column names. - -## Error Details - -Server logs show migration completed successfully: -``` -[Validation] ✓ Dogs table has no sire/dam columns -[Validation] ✓ Parents table exists -``` - -But when adding a dog, you still get the "no such column: sire" error. - -## Root Cause - -The frontend `DogForm` or `AddDogModal` component is sending: -- `sire` and `dam` (wrong) - -But the API expects: -- `sire_id` and `dam_id` (correct) - -## Files to Fix - -Look for these files in `client/src/`: -- `components/DogForm.jsx` -- `components/AddDogModal.jsx` -- `components/EditDogModal.jsx` -- `pages/DogManagement.jsx` - -Or any component that has the Add/Edit Dog form. - -## The Fix - -### 1. Check Form State - -Look for state variables like: -```javascript -const [formData, setFormData] = useState({ - name: '', - breed: '', - sex: '', - sire: '', // ❌ WRONG - should be sire_id - dam: '', // ❌ WRONG - should be dam_id - // ... -}); -``` - -**Change to:** -```javascript -const [formData, setFormData] = useState({ - name: '', - breed: '', - sex: '', - sire_id: null, // ✅ CORRECT - dam_id: null, // ✅ CORRECT - // ... -}); -``` - -### 2. Check Form Submission - -Look for the API call: -```javascript -const response = await fetch('/api/dogs', { - method: 'POST', - headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify({ - name: formData.name, - breed: formData.breed, - sex: formData.sex, - sire: formData.sire, // ❌ WRONG - dam: formData.dam, // ❌ WRONG - // ... - }) -}); -``` - -**Change to:** -```javascript -const response = await fetch('/api/dogs', { - method: 'POST', - headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify({ - name: formData.name, - breed: formData.breed, - sex: formData.sex, - sire_id: formData.sire_id, // ✅ CORRECT - dam_id: formData.dam_id, // ✅ CORRECT - // ... - }) -}); -``` - -### 3. Check Select Dropdowns - -Look for parent selection dropdowns: -```jsx - -``` - -**Change to:** -```jsx - -``` - -### 4. Check Edit Mode - -When editing an existing dog: -```javascript -// ❌ WRONG - trying to access old columns -setFormData({ - ...dog, - sire: dog.sire?.id || '', - dam: dog.dam?.id || '', -}); -``` - -**Change to:** -```javascript -// ✅ CORRECT - use correct field names -setFormData({ - ...dog, - sire_id: dog.sire?.id || null, - dam_id: dog.dam?.id || null, -}); -``` - -### 5. Check Litter Mode - -If the form has litter selection mode: -```javascript -if (useLitter && selectedLitter) { - dogData.sire = selectedLitter.sire_id; // ❌ WRONG field name - dogData.dam = selectedLitter.dam_id; // ❌ WRONG field name -} -``` - -**Change to:** -```javascript -if (useLitter && selectedLitter) { - dogData.sire_id = selectedLitter.sire_id; // ✅ CORRECT - dogData.dam_id = selectedLitter.dam_id; // ✅ CORRECT -} -``` - -## Quick Search & Replace - -In your frontend code, search for: - -1. **State initialization**: `sire: ''` → `sire_id: null` -2. **State initialization**: `dam: ''` → `dam_id: null` -3. **API payload**: `sire:` → `sire_id:` -4. **API payload**: `dam:` → `dam_id:` -5. **Form handlers**: `formData.sire` → `formData.sire_id` -6. **Form handlers**: `formData.dam` → `formData.dam_id` - -## Testing After Fix - -1. Open Add Dog modal -2. Fill in name, breed, sex -3. Select a sire from dropdown -4. Select a dam from dropdown -5. Click Submit -6. Should work without "sire column" error! - -## API Contract (For Reference) - -The server `POST /api/dogs` expects: -```json -{ - "name": "string", - "breed": "string", - "sex": "male" | "female", - "sire_id": number | null, - "dam_id": number | null, - "litter_id": number | null, - "registration_number": "string" | null, - "birth_date": "YYYY-MM-DD" | null, - "color": "string" | null, - "microchip": "string" | null, - "notes": "string" | null -} -``` - -## Why This Happens - -The database migration fixed the backend, but: -- Frontend code wasn't updated to use new field names -- Old form components still reference `sire`/`dam` -- API expects `sire_id`/`dam_id` (correct) - -## Example Complete Fix - -Here's a complete example of a corrected form: - -```jsx -import React, { useState, useEffect } from 'react'; - -function DogForm({ dog, onSubmit, onCancel }) { - const [formData, setFormData] = useState({ - name: '', - breed: '', - sex: 'male', - birth_date: '', - sire_id: null, // ✅ CORRECT - dam_id: null, // ✅ CORRECT - litter_id: null, - registration_number: '', - microchip: '', - color: '', - notes: '' - }); - - const [males, setMales] = useState([]); - const [females, setFemales] = useState([]); - - useEffect(() => { - // Load existing dogs for parent selection - fetch('/api/dogs') - .then(res => res.json()) - .then(dogs => { - setMales(dogs.filter(d => d.sex === 'male')); - setFemales(dogs.filter(d => d.sex === 'female')); - }); - - // If editing, populate form - if (dog) { - setFormData({ - ...dog, - sire_id: dog.sire?.id || null, // ✅ CORRECT - dam_id: dog.dam?.id || null, // ✅ CORRECT - birth_date: dog.birth_date || '', - registration_number: dog.registration_number || '', - microchip: dog.microchip || '', - color: dog.color || '', - notes: dog.notes || '' - }); - } - }, [dog]); - - const handleSubmit = async (e) => { - e.preventDefault(); - - const payload = { - name: formData.name, - breed: formData.breed, - sex: formData.sex, - sire_id: formData.sire_id, // ✅ CORRECT - dam_id: formData.dam_id, // ✅ CORRECT - litter_id: formData.litter_id, - birth_date: formData.birth_date || null, - registration_number: formData.registration_number || null, - microchip: formData.microchip || null, - color: formData.color || null, - notes: formData.notes || null - }; - - const url = dog ? `/api/dogs/${dog.id}` : '/api/dogs'; - const method = dog ? 'PUT' : 'POST'; - - try { - const response = await fetch(url, { - method, - headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify(payload) - }); - - if (!response.ok) { - const error = await response.json(); - throw new Error(error.error || 'Failed to save dog'); - } - - const savedDog = await response.json(); - onSubmit(savedDog); - } catch (error) { - console.error('Error saving dog:', error); - alert(error.message); - } - }; - - return ( -
- {/* Basic fields */} - setFormData({ ...formData, name: e.target.value })} - required - /> - - setFormData({ ...formData, breed: e.target.value })} - required - /> - - - - {/* Parent selection */} - - - - - - - {/* Other fields */} - setFormData({ ...formData, birth_date: e.target.value })} - /> - - setFormData({ ...formData, registration_number: e.target.value })} - /> - - setFormData({ ...formData, microchip: e.target.value })} - /> - - setFormData({ ...formData, color: e.target.value })} - /> - -