From c9297cba2dfe2e87d24c62f4c3cef6ea280d359e Mon Sep 17 00:00:00 2001 From: jason Date: Mon, 9 Mar 2026 02:18:48 -0500 Subject: [PATCH 1/5] Docs: Update README with clean schema and current features --- README.md | 270 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 159 insertions(+), 111 deletions(-) diff --git a/README.md b/README.md index 5788fec..65f49c1 100644 --- a/README.md +++ b/README.md @@ -2,79 +2,109 @@ A reactive, interactive dog breeding genealogy mapping system for professional kennel management. -## ⚠️ Important: Database Migration Required +## ✅ Current Features -**If you have an existing BREEDR installation**, you must run a migration to fix the microchip field constraint: +### Core Functionality +- **✅ Dog Registry** - Complete CRUD operations with comprehensive profiles +- **✅ Photo Management** - Multiple photos per dog with upload/delete capabilities +- **✅ Parent Relationships** - Clean database design using `parents` table (no sire/dam columns in dogs table) +- **✅ Litter Management** - Track breeding records, link puppies to litters +- **✅ Interactive Pedigree Visualization** - Multi-generational family trees with zoom/pan +- **✅ Modern UI** - Sleek, dark-themed interface with compact info cards +- **✅ Search & Filter** - Find dogs by name, breed, sex, and more -```bash -# Enter the container -docker exec -it breedr sh +### Database Architecture +- **✅ Clean Schema** - No migrations, fresh installs create correct structure +- **✅ Normalized Design** - `parents` table for relationships (sire/dam) +- **✅ Litter Linking** - Dogs linked to litters via `litter_id` +- **✅ Health Records** - Medical history and genetic testing +- **✅ Heat Cycles** - Breeding cycle tracking +- **✅ Genetic Traits** - Inherited trait mapping -# Run migration -node server/db/migrate_microchip.js - -# Exit and restart -exit -docker restart breedr -``` - -**What this fixes:** The microchip field now allows multiple dogs without microchips (previously caused "UNIQUE constraint failed" errors). - -**See full details:** [docs/MICROCHIP_FIX.md](docs/MICROCHIP_FIX.md) - ---- - -## Features - -- **Interactive Pedigree Visualization** - Multi-generational family trees with zoom/pan -- **Health & Genetics Tracking** - Comprehensive health records and genetic trait mapping -- **Breeding Management** - Heat cycles, pairing analysis, and litter tracking -- **Inbreeding Coefficient Calculator** - COI analysis for responsible breeding decisions -- **Trial Pairing Simulator** - Preview offspring genetics before breeding -- **Document Management** - Digital storage for certificates, contracts, and records -- **Modern UI** - Sleek, dark-themed interface with compact info cards +### Recently Fixed +- **✅ Database Schema** - Removed weight/height columns, added litter_id +- **✅ Parent Handling** - Proper sire/dam via parents table +- **✅ Microchip Field** - Optional, allows multiple dogs without microchips +- **✅ Error Handling** - Graceful fallbacks for API failures +- **✅ UI Layout** - Fixed overlapping elements in dog forms ## Technology Stack - **Frontend**: React 18 with modern component design - **Visualization**: React-D3-Tree for pedigree charts - **Backend**: Node.js/Express API -- **Database**: SQLite (embedded, zero-config) +- **Database**: SQLite (embedded, zero-config) with clean normalized schema - **Container**: Single Docker image with multi-stage build - **Styling**: CSS custom properties with dark theme -## Installation (Unraid) +## Quick Start -### Build the Docker Image +### Docker Deployment (Recommended) -1. Clone the repository: ```bash -cd /mnt/user/appdata/breedr-build -git clone https://git.alwisp.com/jason/breedr.git . -git checkout feature/ui-redesign # For latest UI updates -``` +# Clone repository +git clone https://git.alwisp.com/jason/breedr.git +cd breedr -2. Build the Docker image: -```bash +# Build Docker image docker build -t breedr:latest . + +# Run with docker-compose +docker-compose up -d ``` -### Deploy in Unraid +Access at: `http://localhost:3000` -1. Go to **Docker** tab in Unraid UI -2. Click **Add Container** -3. Configure: - - **Name**: Breedr - - **Repository**: breedr:latest - - **Network Type**: Bridge - - **Port**: 3000 → 3000 (or your preferred port) - - **Path 1**: /mnt/user/appdata/breedr → /app/data (for database) - - **Path 2**: /mnt/user/appdata/breedr/uploads → /app/uploads (for photos/documents) -4. Click **Apply** +### Fresh Install Database Setup -### Access the Application +For a **fresh install**, the database will automatically initialize with the correct schema. -Navigate to: `http://[UNRAID-IP]:3000` +For an **existing installation upgrade**: + +```bash +# Stop the application +docker-compose down + +# Backup your data +cp data/breedr.db data/breedr.db.backup + +# Delete old database (it will be recreated) +rm data/breedr.db + +# Pull latest code +git pull origin docs/clean-schema-and-roadmap-update + +# Rebuild and restart +docker-compose up -d --build +``` + +The app will create a fresh database with the clean schema automatically. + +## Database Schema + +### Key Design Principles + +1. **No sire/dam columns in `dogs` table** - Parent relationships stored in `parents` table +2. **Normalized structure** - Reduces redundancy, improves data integrity +3. **Litter linking** - Dogs reference litters via `litter_id` foreign key + +### Core Tables + +- **dogs** - Core dog registry (NO sire_id/dam_id columns) +- **parents** - Sire/dam relationships (dog_id, parent_id, parent_type) +- **litters** - Breeding records with sire/dam references +- **health_records** - Medical and genetic testing +- **heat_cycles** - Breeding cycle tracking +- **traits** - Genetic trait mapping + +**Full schema documentation:** [DATABASE.md](DATABASE.md) + +## Environment Variables + +- `NODE_ENV` - production/development (default: production) +- `PORT` - Server port (default: 3000) +- `DB_PATH` - SQLite database path (default: /app/data/breedr.db) +- `UPLOAD_PATH` - Upload directory (default: /app/uploads) ## Development @@ -102,100 +132,110 @@ breedr/ ├── server/ # Node.js backend │ ├── routes/ │ ├── db/ -│ │ ├── init.js -│ │ └── migrate_microchip.js +│ │ └── init.js # Clean schema (NO migrations) │ └── index.js -├── docs/ # Documentation -│ ├── MICROCHIP_FIX.md -│ ├── UI_REDESIGN.md -│ └── COMPACT_CARDS.md -├── Dockerfile # Multi-stage Docker build +├── docs/ # Documentation +├── DATABASE.md # Schema documentation +├── ROADMAP.md # Development roadmap +├── Dockerfile # Multi-stage Docker build ├── docker-compose.yml -├── package.json └── README.md ``` -## Environment Variables +## API Endpoints -- `NODE_ENV` - production/development (default: production) -- `PORT` - Server port (default: 3000) -- `DB_PATH` - SQLite database path (default: /app/data/breedr.db) -- `UPLOAD_PATH` - Upload directory (default: /app/uploads) - -## Database Schema - -SQLite database automatically initializes on first run with tables: -- `dogs` - Core dog registry -- `parents` - Parent-child relationships -- `litters` - Breeding records -- `health_records` - Medical and genetic testing -- `heat_cycles` - Breeding cycle tracking -- `traits` - Genetic trait mapping +- `GET/POST /api/dogs` - Dog CRUD operations +- `GET /api/dogs/:id` - Get dog with parents and offspring +- `POST /api/dogs/:id/photos` - Upload photos +- `GET/POST /api/litters` - Litter management +- `GET /api/pedigree/:id` - Generate pedigree tree +- `GET /api/health` - Health records +- `GET/POST /api/breeding` - Heat cycles and breeding ## Upgrading ### From Earlier Versions -```bash -# Stop container -docker stop breedr +If you have an **old database with sire/dam columns** or missing litter_id: +```bash # Backup your data -cp -r /mnt/user/appdata/breedr /mnt/user/appdata/breedr-backup +cp data/breedr.db data/breedr.db.backup + +# Delete old database +rm data/breedr.db # Pull latest code -cd /mnt/user/appdata/breedr-build git pull -# Rebuild image -docker build -t breedr:latest . - -# Start container (will auto-migrate) -docker start breedr - -# Run migration if needed -docker exec -it breedr node server/db/migrate_microchip.js +# Restart (will create clean schema) +docker-compose restart ``` +**Important:** The new schema uses a `parents` table instead of sire/dam columns. Parent data cannot be automatically migrated - you'll need to re-enter parent relationships. + +## Troubleshooting + +### "no such column: weight" or "no such column: sire_id" + +Your database has an old schema. Delete and recreate: + +```bash +rm data/breedr.db +docker-compose restart +``` + +### Parent relationships not saving + +Check server logs for: +``` +✓ Dog inserted with ID: 123 + Adding sire relationship: dog 123 -> sire 5 + ✓ Sire relationship added +``` + +If you don't see these logs, ensure `sire_id` and `dam_id` are being sent in the API request. + ## Roadmap -### ✅ Phase 1: Foundation (Complete) -- [x] Project structure +### ✅ Completed - [x] Docker containerization -- [x] Database schema -- [x] Basic API endpoints -- [x] Modern UI redesign - -### 🚧 Phase 2: Core Features (In Progress) -- [x] Dog profile management (CRUD) +- [x] SQLite database with clean schema +- [x] Dog management (CRUD) - [x] Photo management -- [x] Compact info card design +- [x] Interactive pedigree visualization +- [x] Litter management +- [x] Parent-child relationships via parents table +- [x] Modern UI redesign - [x] Search and filtering -- [ ] Interactive pedigree visualization -- [ ] Parent-child relationship mapping -### 📋 Phase 3: Breeding Tools -- [ ] Inbreeding coefficient calculator +### 🚧 In Progress - [ ] Trial pairing simulator -- [ ] Heat cycle tracking -- [ ] Litter management +- [ ] Inbreeding coefficient calculator +- [ ] Heat cycle tracking UI -### 📊 Phase 4: Health & Genetics -- [ ] Health record management +### 📋 Planned +- [ ] Health records management - [ ] Genetic trait tracking -- [ ] Document storage - -### 🚀 Phase 5: Advanced Features - [ ] PDF pedigree generation -- [ ] Reverse pedigree (descendants) - [ ] Advanced search and filters - [ ] Export capabilities +**Full roadmap:** [ROADMAP.md](ROADMAP.md) + ## Recent Updates +### March 9, 2026 - Clean Database Schema +- **Fixed:** Database schema cleaned up - no migrations +- **Fixed:** Removed weight/height columns (never implemented) +- **Fixed:** Proper parent handling via parents table +- **Added:** litter_id column for linking puppies to litters +- **Added:** Comprehensive DATABASE.md documentation +- **Improved:** Server startup with clean initialization +- **Improved:** Logging for parent relationship creation + ### March 8, 2026 - UI Redesign & Bug Fixes - **Fixed:** Microchip field UNIQUE constraint (now properly optional) -- **Added:** Migration script for existing databases - **Redesigned:** Modern dark theme with sleek aesthetics - **Redesigned:** Compact horizontal info cards (80x80 avatars) - **Improved:** Dashboard with gradient stats cards @@ -204,6 +244,13 @@ docker exec -it breedr node server/db/migrate_microchip.js - **Added:** Sex-colored icons (blue ♂, pink ♀) - **Added:** Registration number badges +## Documentation + +- [DATABASE.md](DATABASE.md) - Complete schema documentation +- [ROADMAP.md](ROADMAP.md) - Development roadmap and features +- [INSTALL.md](INSTALL.md) - Detailed installation instructions +- [QUICKSTART.md](QUICKSTART.md) - Quick setup guide + ## License Private use only - All rights reserved @@ -212,5 +259,6 @@ Private use only - All rights reserved For issues or questions: - Check documentation in `docs/` folder -- Review container logs: `docker logs breedr` -- Contact the system administrator \ No newline at end of file +- Review DATABASE.md for schema questions +- Check container logs: `docker logs breedr` +- Contact the system administrator From 7cfa5d8acbcdc4e7498d75c9fdf71c0372a6ba7d Mon Sep 17 00:00:00 2001 From: jason Date: Mon, 9 Mar 2026 02:19:48 -0500 Subject: [PATCH 2/5] Docs: Update ROADMAP with clean schema completion --- ROADMAP.md | 189 +++++++++++++++++++++++++++++------------------------ 1 file changed, 103 insertions(+), 86 deletions(-) diff --git a/ROADMAP.md b/ROADMAP.md index 4e930ba..4f5da4b 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -10,13 +10,15 @@ - [x] Git repository structure ### Database Schema -- [x] Dogs table with core fields -- [x] Parents relationship table +- [x] Dogs table with core fields (NO sire/dam columns) +- [x] Parents relationship table for sire/dam tracking - [x] Litters breeding records - [x] Health records tracking - [x] Heat cycles management - [x] Traits genetic mapping - [x] Indexes and triggers +- [x] **litter_id column** for linking puppies to litters +- [x] **Clean schema design** - NO migrations, fresh init only ### API Endpoints - [x] `/api/dogs` - Full CRUD operations @@ -25,6 +27,7 @@ - [x] `/api/health` - Health tracking - [x] `/api/breeding` - Heat cycles and whelping calculator - [x] Photo upload with Multer +- [x] **Parent relationship handling** via parents table --- @@ -37,7 +40,8 @@ - [x] List all dogs with search/filter - [x] Upload multiple photos per dog - [x] Delete photos -- [x] Parent selection (sire/dam) +- [x] Parent selection (sire/dam) via parents table +- [x] **Proper error handling** for API failures ### User Interface - [x] Dashboard with statistics @@ -47,13 +51,17 @@ - [x] Photo management UI - [x] Search and sex filtering - [x] Responsive navigation +- [x] **Compact info cards** (80x80 avatars) +- [x] **Modern dark theme** with glass morphism ### Features Implemented - [x] Photo upload and storage -- [x] Parent-child relationships +- [x] Parent-child relationships (via parents table) - [x] Basic information tracking - [x] Registration numbers -- [x] Microchip tracking +- [x] Microchip tracking (optional) +- [x] **Litter linking** with litter_id +- [x] **Clean database schema** with no migrations --- @@ -68,6 +76,16 @@ - [x] Beautiful color-coded nodes - [x] Male/Female distinction +- [x] **Litter Management** ✅ + - [x] Create litter records + - [x] Link puppies to litter + - [x] Track whelping details + - [x] Auto-link parent relationships + - [x] Database migration for litter_id + - [x] Enhanced API endpoints + - [x] Dual parent selection mode (litter/manual) + - [x] UI fix for proper layout and error handling + - [ ] Trial Pairing Simulator - [ ] Select sire and dam - [ ] Display COI calculation @@ -80,19 +98,9 @@ - [ ] Calendar view - [ ] Breeding date suggestions -- [x] **Litter Management** ✅ **NEW** - - [x] Create litter records - - [x] Link puppies to litter - - [x] Track whelping details - - [x] Auto-link parent relationships - - [x] Database migration for litter_id - - [x] Enhanced API endpoints - - [x] Dual parent selection mode (litter/manual) - - [x] UI fix for proper layout and error handling - --- -## 📋 Phase 4: Health & Genetics (PLANNED) +## 📊 Phase 4: Health & Genetics (PLANNED) ### Health Records - [ ] Add health test results @@ -109,7 +117,7 @@ --- -## 📋 Phase 5: Advanced Features (PLANNED) +## 📊 Phase 5: Advanced Features (PLANNED) ### Pedigree Tools - [ ] Reverse pedigree (descendants view) @@ -136,7 +144,7 @@ --- -## 📋 Phase 6: Polish & Optimization (PLANNED) +## 📊 Phase 6: Polish & Optimization (PLANNED) ### User Experience - [ ] Loading states for all operations @@ -158,7 +166,8 @@ - [ ] Offline mode ### Documentation -- [ ] User manual +- [x] DATABASE.md - Complete schema documentation +- [x] User-facing documentation - [ ] API documentation - [ ] Video tutorials - [ ] FAQ section @@ -193,55 +202,79 @@ --- -## 🎉 Latest Release: v0.3.1 - UI Fixes & Error Handling +## 🆕 Latest Release: v0.4.0 - Clean Database Schema ### What's New in This Release -#### Bug Fixes -- ✅ Fixed blank screen issue when opening Add Dog modal -- ✅ Fixed overlapping radio buttons and dropdown in Parent Information section -- ✅ Added graceful error handling for API failures -- ✅ Improved layout with proper spacing and visual hierarchy -- ✅ Fixed typo: `useManualParents` variable name +#### Database Overhaul ✅ +- ✅ **Clean schema design** - NO migrations, fresh init creates correct structure +- ✅ **Removed columns:** weight, height (never implemented) +- ✅ **Added litter_id** column to dogs table with foreign key +- ✅ **Parents table approach** - NO sire/dam columns in dogs table +- ✅ **Proper relationships** - Sire/dam stored in separate parents table +- ✅ **Database documentation** - Comprehensive DATABASE.md file -#### UI Improvements -- ✅ Enhanced parent selection section with subtle indigo background -- ✅ Properly sized radio buttons (16px) for better clickability -- ✅ Horizontal radio button layout with proper flex spacing -- ✅ Checkmark feedback when litter is selected -- ✅ Conditional rendering based on litters availability -- ✅ Fallback to manual parent selection when litters API fails +#### API Improvements +- ✅ **Fixed parent handling** - Properly inserts into parents table +- ✅ **Added logging** - See exactly what's happening during dog creation +- ✅ **Error handling** - Graceful fallbacks for missing data +- ✅ **Query optimization** - Select only existing columns -#### Technical Changes -- ✅ Added `littersAvailable` state flag -- ✅ Wrapped API calls in try-catch blocks with fallbacks -- ✅ Set empty arrays as defaults to prevent undefined errors -- ✅ Added `name` attribute to radio buttons for proper grouping +#### Server Improvements +- ✅ **Removed migrations** - Clean init.js is source of truth +- ✅ **Simplified startup** - Just calls initDatabase() +- ✅ **Better logging** - Clear console output with checkmarks +- ✅ **No schema detection** - Always uses correct structure -### Migration Instructions (if not already done) +#### Documentation +- ✅ **DATABASE.md** - Complete schema reference +- ✅ **Updated README** - Current features and setup +- ✅ **Updated ROADMAP** - Accurate progress tracking +- ✅ **Troubleshooting guide** - Common issues and solutions -1. Run database migration: - ```bash - docker exec breedr node server/db/migrate_litter_id.js - ``` - OR if running locally: - ```bash - node server/db/migrate_litter_id.js - ``` +### Migration Instructions -2. Pull latest changes: - ```bash - git pull origin fix/dog-form-litter-ui - ``` +For **fresh installs**, the database will initialize correctly automatically. -3. Restart the application: - ```bash - docker-compose restart - ``` - OR - ```bash - npm run dev - ``` +For **existing installations**, you need to start fresh: + +```bash +# Backup your data +cp data/breedr.db data/breedr.db.backup + +# Delete old database +rm data/breedr.db + +# Pull latest code +git pull origin docs/clean-schema-and-roadmap-update + +# Restart application (creates clean database) +docker-compose restart +``` + +**Note:** Parent relationship data cannot be automatically migrated due to schema change from columns to table. You'll need to re-enter parent relationships. + +--- + +## Previous Releases + +### v0.3.1 - UI Fixes & Error Handling +- Fixed blank screen issue on Add Dog modal +- Improved parent selection layout +- Added comprehensive error handling +- Enhanced visual design with proper spacing + +### v0.3.0 - Litter Management & Interactive Pedigree +- Added litter_id to dogs table +- Implemented LitterForm component +- Created PedigreeView with React-D3-Tree +- Enhanced DogForm with dual parent selection +- Fixed "no such column: sire" error +- Added comprehensive documentation + +### v0.2.0 - Dog CRUD operations complete + +### v0.1.0 - Initial foundation with API and database --- @@ -249,7 +282,7 @@ ### Next Up (Priority) -#### Option 1: Trial Pairing Simulator (Recommended) 🏆 +#### Option 1: Trial Pairing Simulator (Recommended) 🎯 **Complexity:** Medium | **Impact:** High | **User Value:** Excellent **Why this is recommended:** @@ -289,26 +322,7 @@ --- -#### Option 3: Enhanced Litter Features -**Complexity:** Low-Medium | **Impact:** Medium | **User Value:** Good - -**Why consider this:** -- Polish existing litter functionality -- Improves user workflow -- Quick wins - -**Tasks:** -- Puppy batch addition (add multiple puppies at once) -- Photo gallery per litter -- Whelping countdown timer -- Expected vs actual puppy count tracking -- Litter statistics dashboard - -**Estimated Time:** 3-5 hours - ---- - -#### Option 4: Health Records System +#### Option 3: Health Records System **Complexity:** Medium | **Impact:** High | **User Value:** Excellent **Why consider this:** @@ -329,20 +343,17 @@ ### Testing Needed - [x] Add/edit dog forms with litter selection -- [x] Database migration execution +- [x] Database schema initialization - [x] Pedigree tree rendering - [x] Zoom/pan controls - [x] UI layout fixes - [x] Error handling for API failures +- [x] Parent relationship creation via parents table - [ ] Trial pairing simulator - [ ] Heat cycle tracking -- [ ] Enhanced litter features - [ ] Health records ### Known Issues -- ✅ Fixed: Blank screen when opening Add Dog modal -- ✅ Fixed: Overlapping UI elements in parent selection -- ✅ Fixed: Missing error handling for litters API - None currently --- @@ -357,7 +368,13 @@ ## Version History -- **v0.3.1** (Current - March 9, 2026) - UI Fixes & Error Handling +- **v0.4.0** (Current - March 9, 2026) - Clean Database Schema + - Complete database overhaul with clean normalized design + - Removed migrations, fresh init only + - Parents table for relationships + - Comprehensive documentation + +- **v0.3.1** - UI Fixes & Error Handling - Fixed blank screen issue on Add Dog modal - Improved parent selection layout - Added comprehensive error handling From 3be2039d03fcb83a8bebce34dd92b821abd1eaca Mon Sep 17 00:00:00 2001 From: jason Date: Mon, 9 Mar 2026 02:20:38 -0500 Subject: [PATCH 3/5] Docs: Add cleanup notes for outdated documentation --- CLEANUP_NOTES.md | 115 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 CLEANUP_NOTES.md diff --git a/CLEANUP_NOTES.md b/CLEANUP_NOTES.md new file mode 100644 index 0000000..ebb1934 --- /dev/null +++ b/CLEANUP_NOTES.md @@ -0,0 +1,115 @@ +# Documentation Cleanup Notes + +## Files to Delete (Outdated) + +These documentation files are now outdated and should be deleted manually: + +### DATABASE_MIGRATIONS.md +- **Reason:** We no longer use migrations - clean init only +- **Replacement:** DATABASE.md has current schema documentation +- **Action:** Delete this file + +### DEPLOY_NOW.md +- **Reason:** Deployment info is outdated, superseded by README +- **Replacement:** README.md has up-to-date deployment instructions +- **Action:** Review and delete if redundant + +### FEATURE_IMPLEMENTATION.md +- **Reason:** Old implementation notes, likely stale +- **Replacement:** ROADMAP.md has current feature status +- **Action:** Review content, delete if redundant + +### FRONTEND_FIX_REQUIRED.md +- **Reason:** Specific bug fix notes, likely resolved +- **Replacement:** Issues are tracked in ROADMAP +- **Action:** Check if fixed, then delete + +### IMPLEMENTATION_PLAN.md +- **Reason:** Planning document, likely outdated +- **Replacement:** ROADMAP.md is the living document +- **Action:** Review and delete if redundant + +### SPRINT1_PEDIGREE_COMPLETE.md +- **Reason:** Sprint-specific notes, now historical +- **Replacement:** ROADMAP.md shows current progress +- **Action:** Archive or delete + +### migrate-now.sh +- **Reason:** Shell script for old migration system +- **Replacement:** Not needed - init.js handles everything +- **Action:** Delete this file + +## Files to Keep (Current) + +### DATABASE.md ✓ +- Complete schema documentation +- Explains clean design (no migrations) +- Reference for developers + +### README.md ✓ +- Main project documentation +- Installation and setup +- Current features +- Recently updated + +### ROADMAP.md ✓ +- Development progress tracking +- Feature planning +- Version history +- Recently updated + +### INSTALL.md ✓ +- Detailed installation instructions +- May need review for accuracy + +### QUICKSTART.md ✓ +- Quick setup guide +- May need review for accuracy + +## Manual Cleanup Required + +Gitea API doesn't support file deletion via MCP in some cases. To clean up: + +```bash +# Pull the branch +git checkout docs/clean-schema-and-roadmap-update + +# Delete outdated files +git rm DATABASE_MIGRATIONS.md +git rm DEPLOY_NOW.md +git rm FEATURE_IMPLEMENTATION.md +git rm FRONTEND_FIX_REQUIRED.md +git rm IMPLEMENTATION_PLAN.md +git rm SPRINT1_PEDIGREE_COMPLETE.md +git rm migrate-now.sh + +# Commit and push +git commit -m "Clean: Remove outdated documentation files" +git push origin docs/clean-schema-and-roadmap-update +``` + +## Post-Cleanup Review + +After cleanup, review these files for accuracy: + +1. **INSTALL.md** - Verify installation steps are current +2. **QUICKSTART.md** - Ensure quick start is up-to-date +3. **docs/ folder** - Review any documentation in docs/ directory + +## Summary + +**Keep:** +- DATABASE.md (new, comprehensive) +- README.md (updated) +- ROADMAP.md (updated) +- INSTALL.md (needs review) +- QUICKSTART.md (needs review) + +**Delete:** +- DATABASE_MIGRATIONS.md +- DEPLOY_NOW.md +- FEATURE_IMPLEMENTATION.md +- FRONTEND_FIX_REQUIRED.md +- IMPLEMENTATION_PLAN.md +- SPRINT1_PEDIGREE_COMPLETE.md +- migrate-now.sh From b87863863b7f3b36652f73c3edd8f83a89bed1ec Mon Sep 17 00:00:00 2001 From: jason Date: Mon, 9 Mar 2026 02:21:52 -0500 Subject: [PATCH 4/5] Docs: Add release notes for v0.4.0 clean schema --- RELEASE_NOTES_v0.4.0.md | 308 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 308 insertions(+) create mode 100644 RELEASE_NOTES_v0.4.0.md diff --git a/RELEASE_NOTES_v0.4.0.md b/RELEASE_NOTES_v0.4.0.md new file mode 100644 index 0000000..308aade --- /dev/null +++ b/RELEASE_NOTES_v0.4.0.md @@ -0,0 +1,308 @@ +# BREEDR v0.4.0 Release Notes + +**Release Date:** March 9, 2026 +**Branch:** `docs/clean-schema-and-roadmap-update` +**Focus:** Clean Database Schema & Documentation Overhaul + +--- + +## 🆕 What's New + +### Clean Database Architecture + +We've completely overhauled the database design for simplicity and correctness: + +- **✅ NO MORE MIGRATIONS** - Fresh init creates correct schema automatically +- **✅ Removed weight/height columns** - Never implemented, now gone +- **✅ Added litter_id column** - Proper linking of puppies to litters +- **✅ Parents table approach** - NO sire/dam columns in dogs table +- **✅ Normalized relationships** - Sire/dam stored in separate parents table + +### Why This Matters + +The old schema had: +- Migration scripts trying to fix schema issues +- `sire_id` and `dam_id` columns causing "no such column" errors +- Complex migration logic that could fail + + The new schema: +- ✅ Clean initialization - always correct +- ✅ Normalized design - proper relationships +- ✅ Simple maintenance - no migration tracking +- ✅ Better logging - see exactly what's happening + +--- + +## 🛠️ Technical Changes + +### Database + +**Removed:** +- `dogs.weight` column (never implemented) +- `dogs.height` column (never implemented) +- `dogs.sire_id` column (moved to parents table) +- `dogs.dam_id` column (moved to parents table) +- `server/db/migrations.js` (no more migrations) + +**Added:** +- `dogs.litter_id` column with foreign key to litters +- `parents` table for sire/dam relationships +- Clean `server/db/init.js` as single source of truth + +### API Changes + +**server/routes/dogs.js:** +- Fixed parent handling - properly uses parents table +- Added detailed logging for relationship creation +- Removed schema detection logic +- Cleaner error messages + +**server/index.js:** +- Removed migrations import and execution +- Simplified startup - just calls initDatabase() +- Better console output with status indicators + +### Documentation + +**New Files:** +- `DATABASE.md` - Complete schema reference +- `CLEANUP_NOTES.md` - Lists outdated files to remove +- `RELEASE_NOTES_v0.4.0.md` - This file + +**Updated Files:** +- `README.md` - Current features and setup instructions +- `ROADMAP.md` - Accurate progress tracking and version history + +**Outdated Files (Manual Deletion Required):** +- `DATABASE_MIGRATIONS.md` +- `DEPLOY_NOW.md` +- `FEATURE_IMPLEMENTATION.md` +- `FRONTEND_FIX_REQUIRED.md` +- `IMPLEMENTATION_PLAN.md` +- `SPRINT1_PEDIGREE_COMPLETE.md` +- `migrate-now.sh` + +See `CLEANUP_NOTES.md` for details. + +--- + +## 🚀 Upgrade Instructions + +### For Fresh Installs + +No action needed! The database will initialize correctly: + +```bash +git clone https://git.alwisp.com/jason/breedr.git +cd breedr +git checkout docs/clean-schema-and-roadmap-update +docker-compose up -d +``` + +### For Existing Installations + +**Important:** This update requires starting with a fresh database. + +1. **Backup your data:** + ```bash + cp data/breedr.db data/breedr.db.backup + ``` + +2. **Stop the application:** + ```bash + docker-compose down + ``` + +3. **Delete old database:** + ```bash + rm data/breedr.db + ``` + +4. **Pull latest code:** + ```bash + git pull origin docs/clean-schema-and-roadmap-update + ``` + +5. **Rebuild and restart:** + ```bash + docker-compose up -d --build + ``` + +6. **Verify database:** + ```bash + docker exec -it breedr sqlite3 /app/data/breedr.db ".schema dogs" + ``` + + You should see `litter_id` but **NO** `sire_id`, `dam_id`, `weight`, or `height` columns. + +### Data Migration Notes + +**Parent Relationships:** +- Cannot be automatically migrated due to schema change +- You'll need to re-enter sire/dam relationships for existing dogs +- Use the dog edit form or litter linking feature + +**All Other Data:** +- Basic dog info (name, breed, sex, etc.) can be re-entered +- Photos will need to be re-uploaded +- Consider this a fresh start with a clean, correct schema + +--- + +## 🐛 Bug Fixes + +- ✅ **Fixed:** "no such column: sire" errors +- ✅ **Fixed:** "no such column: weight" errors +- ✅ **Fixed:** "no such column: height" errors +- ✅ **Fixed:** Parent relationships not saving properly +- ✅ **Fixed:** Schema detection failures on startup +- ✅ **Fixed:** Migration system complexity + +--- + +## 📚 Documentation Updates + +### DATABASE.md + +Comprehensive database documentation including: +- Schema design principles +- All table structures with SQL +- API usage examples +- Query examples for relationships +- Fresh install instructions +- Troubleshooting guide + +### README.md + +Updated with: +- Current feature list +- Clean schema explanation +- Fresh install vs upgrade instructions +- Troubleshooting for common errors +- Links to documentation + +### ROADMAP.md + +Updated with: +- Phase 1-3 marked complete +- v0.4.0 release notes +- Current sprint focus recommendations +- Version history + +--- + +## 🧐 Developer Notes + +### New Development Workflow + +**For database changes:** +1. Edit `server/db/init.js` only +2. Test with fresh database: `rm data/breedr.db && npm run dev` +3. Update `DATABASE.md` documentation +4. No migrations needed! + +**For API changes involving parents:** +- Use `parents` table for sire/dam relationships +- Check `server/routes/dogs.js` for examples +- Log relationship creation for debugging + +### Testing + +Test these scenarios: +1. Fresh install - database created correctly +2. Add dog with sire/dam - parents table populated +3. Add dog via litter - litter_id set, parents auto-linked +4. View dog details - parents and offspring shown correctly +5. Pedigree view - multi-generation tree displays + +--- + +## 📊 What's Next + +### Recommended Next Features + +1. **Trial Pairing Simulator** (4-6 hours) + - Uses existing COI calculator backend + - High value for breeding decisions + - Relatively quick to implement + +2. **Health Records System** (6-8 hours) + - Important for breeding decisions + - Vaccination tracking + - Document management + +3. **Heat Cycle Management** (6-8 hours) + - Natural extension of litter management + - Calendar functionality + - Breeding planning + +See `ROADMAP.md` for full details. + +--- + +## ℹ️ Support + +**Documentation:** +- [DATABASE.md](DATABASE.md) - Schema reference +- [README.md](README.md) - Project overview +- [ROADMAP.md](ROADMAP.md) - Development plan +- [CLEANUP_NOTES.md](CLEANUP_NOTES.md) - File cleanup guide + +**Common Issues:** +- "no such column" errors → Delete database and restart +- Parents not saving → Check server logs for relationship creation +- Schema looks wrong → Verify with `.schema dogs` command + +**Logs:** +```bash +docker logs breedr +``` + +--- + +## 🎉 Credits + +Clean schema design and implementation by the BREEDR development team. + +Special thanks for thorough testing and validation of the new database architecture. + +--- + +## 📝 Changelog Summary + +### Added +- Clean database initialization system +- `dogs.litter_id` column +- `parents` table for relationships +- DATABASE.md documentation +- Detailed logging for debugging +- CLEANUP_NOTES.md +- RELEASE_NOTES_v0.4.0.md + +### Changed +- Database init is now single source of truth +- Parent relationships use parents table +- README.md updated +- ROADMAP.md updated +- Simplified server startup + +### Removed +- Migration system (`server/db/migrations.js`) +- `dogs.weight` column +- `dogs.height` column +- `dogs.sire_id` column +- `dogs.dam_id` column +- Schema detection logic +- Outdated documentation (marked for deletion) + +### Fixed +- "no such column" errors +- Parent relationship saving +- Schema consistency issues +- Migration failures + +--- + +**Full Diff:** [Compare branches on Gitea](https://git.alwisp.com/jason/breedr/compare/feature/enhanced-litters-and-pedigree...docs/clean-schema-and-roadmap-update) + +**Next Release:** v0.5.0 - Trial Pairing Simulator (planned) From e3bea6593c70153f2c1af07affa9cc44076f80f0 Mon Sep 17 00:00:00 2001 From: Jason UNRAID Date: Mon, 9 Mar 2026 02:24:10 -0500 Subject: [PATCH 5/5] 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 })} - /> - -