Docs: Update README with clean schema and current features

2026-03-09 02:18:48 -05:00
parent 417dc96b49
commit c9297cba2d
1 changed files with 159 additions and 111 deletions
--- 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`
+- Review DATABASE.md for schema questions
+- Check container logs: `docker logs breedr`
 - Contact the system administrator