361 lines
14 KiB
Markdown
361 lines
14 KiB
Markdown
# BREEDR - Dog Breeding Genealogy Management System
|
||
|
||
A reactive, interactive dog breeding genealogy mapping system for professional kennel management.
|
||
|
||
## ✅ Current Features
|
||
|
||
### 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
|
||
- **✅ Branded Navigation** - Custom logo (br-logo.png) with gold-to-rusty-red gradient title
|
||
- **✅ Trial Pairing Simulator** - COI calculator with common ancestors table and risk badge
|
||
- **✅ Heat Cycle Calendar** - Month grid calendar with cycle windows, breeding date suggestions, and **projected whelping identifiers**
|
||
|
||
### 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
|
||
|
||
### Recently Added (March 9, 2026 — v0.5.1)
|
||
- **✅ Projected Whelp Window on Calendar** - Indigo/purple day cells (days 58–65 from breeding date) visible directly on the month grid
|
||
- **✅ Expected Whelp Day Marker** - Indigo dot on the exact expected whelp day (day 63) alongside the green breeding dot
|
||
- **✅ "[Name] due" Cell Label** - Baby 🍼 icon + dog name label inside the whelp day cell
|
||
- **✅ Active Cycle Card — Whelp Range** - "Whelp est. [date]" row with earliest–latest range shown on each active cycle card
|
||
- **✅ Jump-to-Whelp-Month Button** - One-click navigation to the whelp month when it differs from current view
|
||
- **✅ Live Whelp Preview in Modal** - Instant client-side earliest/expected/latest preview as soon as a breeding date is entered (no save required)
|
||
- **✅ Whelping Banner** - Full-width indigo banner listing dogs with projected whelps when no active heat cycles are visible
|
||
- **✅ Legend Entry** - "Projected Whelp" added to calendar legend
|
||
- **✅ Updated Page Subtitle** - Now reads: *"Track heat cycles, optimal breeding windows, and projected whelping dates"*
|
||
|
||
### Previously Added (March 9, 2026 — v0.5.0)
|
||
- **✅ Heat Cycle Calendar** - Full month grid with color-coded cycle windows (Proestrus / Optimal / Late Estrus / Diestrus)
|
||
- **✅ Start Cycle Modal** - Click any day or the header button to log a new heat cycle for a female
|
||
- **✅ Breeding Date Suggestions** - Phase windows with date ranges loaded from `GET /api/breeding/heat-cycles/:id/suggestions`
|
||
- **✅ Whelping Estimate** - Auto-calculates earliest/expected/latest whelping once a breeding date is logged
|
||
- **✅ Trial Pairing Simulator** - `/pairing` route with sire/dam dropdowns, COI%, risk badge, and common ancestors table
|
||
- **✅ Pairing Nav Link** - `FlaskConical` icon added to navbar
|
||
- **✅ New API Endpoints** - `GET /api/breeding/heat-cycles`, `GET /api/breeding/heat-cycles/:id/suggestions`
|
||
|
||
### Previously Added (March 9, 2026 — v0.4.x)
|
||
- **✅ Brand Logo** - Custom `br-logo.png` in navbar replacing generic icon
|
||
- **✅ Gradient Title** - Gold-to-rusty-red gradient on "BREEDR" brand text
|
||
- **✅ Static Asset Serving** - `/static` directory served by Express for branding assets
|
||
- **✅ Dev Proxy** - Vite dev server proxies `/static` to Express backend
|
||
- **✅ Route Fix** - `/static` and `/uploads` paths no longer fall through to React catch-all
|
||
- **✅ Logo Sizing** - Fixed brand logo to 1:1 aspect ratio square
|
||
|
||
## 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) with clean normalized schema
|
||
- **Container**: Single Docker image with multi-stage build
|
||
- **Styling**: CSS custom properties with dark theme + gradient branding
|
||
|
||
## Quick Start
|
||
|
||
### Docker Deployment (Recommended)
|
||
|
||
```bash
|
||
# Clone repository
|
||
git clone https://git.alwisp.com/jason/breedr.git
|
||
cd breedr
|
||
|
||
# Build Docker image
|
||
docker build -t breedr:latest .
|
||
|
||
# Run with docker-compose
|
||
docker-compose up -d
|
||
```
|
||
|
||
Access at: `http://localhost:3000`
|
||
|
||
### Fresh Install Database Setup
|
||
|
||
For a **fresh install**, the database will automatically initialize with the correct schema.
|
||
|
||
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 master
|
||
|
||
# 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
|
||
|
||
### Local Development Setup
|
||
|
||
```bash
|
||
# Install dependencies
|
||
npm install
|
||
|
||
# Run development server (frontend + backend)
|
||
npm run dev
|
||
|
||
# Build for production
|
||
npm run build
|
||
```
|
||
|
||
### Project Structure
|
||
|
||
```
|
||
breedr/
|
||
├── client/ # React frontend
|
||
│ ├── src/
|
||
│ │ ├── pages/
|
||
│ │ │ ├── BreedingCalendar.jsx # Heat cycle calendar + whelping identifiers
|
||
│ │ │ ├── PairingSimulator.jsx # Trial pairing + COI
|
||
│ │ │ ├── Dashboard.jsx
|
||
│ │ │ ├── DogList.jsx
|
||
│ │ │ ├── DogDetail.jsx
|
||
│ │ │ ├── PedigreeView.jsx
|
||
│ │ │ └── LitterList.jsx
|
||
│ ├── public/
|
||
│ └── package.json
|
||
├── server/ # Node.js backend
|
||
│ ├── routes/
|
||
│ │ ├── breeding.js # Heat cycles, whelping, suggestions
|
||
│ │ ├── pedigree.js # COI, trial pairing
|
||
│ │ ├── dogs.js
|
||
│ │ └── litters.js
|
||
│ ├── db/
|
||
│ │ └── init.js # Clean schema (NO migrations)
|
||
│ └── index.js
|
||
├── static/ # Branding assets (br-logo.png, etc.)
|
||
├── docs/ # Documentation
|
||
├── DATABASE.md # Schema documentation
|
||
├── ROADMAP.md # Development roadmap
|
||
├── Dockerfile # Multi-stage Docker build
|
||
├── docker-compose.yml
|
||
└── README.md
|
||
```
|
||
|
||
## API Endpoints
|
||
|
||
### Dogs
|
||
- `GET/POST /api/dogs` - Dog CRUD operations
|
||
- `GET /api/dogs/:id` - Get dog with parents and offspring
|
||
- `POST /api/dogs/:id/photos` - Upload photos
|
||
|
||
### Pedigree & Genetics
|
||
- `GET /api/pedigree/:id` - Generate pedigree tree
|
||
- `POST /api/pedigree/trial-pairing` - COI + common ancestors + risk recommendation
|
||
|
||
### Breeding & Heat Cycles
|
||
- `GET /api/breeding/heat-cycles` - All heat cycles
|
||
- `GET /api/breeding/heat-cycles/active` - Active cycles with dog info
|
||
- `GET /api/breeding/heat-cycles/dog/:dogId` - Cycles for a specific dog
|
||
- `GET /api/breeding/heat-cycles/:id/suggestions` - Breeding windows + whelping estimate
|
||
- `POST /api/breeding/heat-cycles` - Create new heat cycle
|
||
- `PUT /api/breeding/heat-cycles/:id` - Update cycle (log breeding date, etc.)
|
||
- `DELETE /api/breeding/heat-cycles/:id` - Delete cycle
|
||
- `GET /api/breeding/whelping-calculator` - Standalone whelping date calculator
|
||
|
||
### Litters
|
||
- `GET/POST /api/litters` - Litter management
|
||
|
||
### Assets
|
||
- `GET /static/*` - Branding and static assets
|
||
- `GET /uploads/*` - Dog photos
|
||
|
||
## Upgrading
|
||
|
||
### From Earlier Versions
|
||
|
||
If you have an **old database with sire/dam columns** or missing litter_id:
|
||
|
||
```bash
|
||
# Backup your data
|
||
cp data/breedr.db data/breedr.db.backup
|
||
|
||
# Delete old database
|
||
rm data/breedr.db
|
||
|
||
# Pull latest code
|
||
git pull
|
||
|
||
# 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.
|
||
|
||
### Logo not appearing in navbar
|
||
|
||
Ensure `br-logo.png` is placed in the `static/` directory at the project root. The file is served at `/static/br-logo.png`.
|
||
|
||
### Heat cycles not showing on calendar
|
||
|
||
Ensure dogs are registered with `sex: 'female'` before creating heat cycles. The API validates this and will return a 400 error for male dogs.
|
||
|
||
### Whelping window not appearing on calendar
|
||
|
||
A breeding date must be logged on the cycle for whelp window cells to appear. Use the Cycle Detail modal → "Log Breeding Date" field. The whelp preview appears client-side instantly; the calendar cells populate after save.
|
||
|
||
## Roadmap
|
||
|
||
### ✅ Completed
|
||
- [x] Docker containerization
|
||
- [x] SQLite database with clean schema
|
||
- [x] Dog management (CRUD)
|
||
- [x] Photo management
|
||
- [x] Interactive pedigree visualization
|
||
- [x] Litter management
|
||
- [x] Parent-child relationships via parents table
|
||
- [x] Modern UI redesign
|
||
- [x] Search and filtering
|
||
- [x] Custom brand logo + gradient title
|
||
- [x] Static asset serving
|
||
- [x] Trial Pairing Simulator (COI + common ancestors + risk badge)
|
||
- [x] Heat Cycle Calendar (month grid + windows + breeding suggestions + whelping estimate)
|
||
- [x] **Projected Whelping Calendar Identifier** (whelp window cells, due label, active card range, live modal preview, whelping banner)
|
||
|
||
### 🔧 In Progress / Up Next
|
||
- [ ] Health Records System
|
||
- [ ] Genetic trait tracking
|
||
|
||
### 📋 Planned
|
||
- [ ] PDF pedigree generation
|
||
- [ ] Advanced search and filters
|
||
- [ ] Export capabilities
|
||
- [ ] Progesterone tracking (extended feature)
|
||
|
||
**Full roadmap:** [ROADMAP.md](ROADMAP.md)
|
||
|
||
## Recent Updates
|
||
|
||
### March 9, 2026 - Projected Whelping Calendar Identifier (v0.5.1)
|
||
- **Added:** Indigo whelp window (days 58–65) on calendar grid cells when a breeding date is logged
|
||
- **Added:** Indigo dot marker on exact expected whelp day (day 63)
|
||
- **Added:** `Baby` icon + "[Name] due" label inside whelp day cells
|
||
- **Added:** "Whelp est. [date]" row with earliest–latest range on active cycle cards
|
||
- **Added:** Jump-to-whelp-month button on active cycle cards
|
||
- **Added:** Live whelp preview in Cycle Detail modal (client-side, instant, no save required)
|
||
- **Added:** Full-width whelping banner when projected whelps exist but no active heat cycles are visible
|
||
- **Added:** "Projected Whelp" legend entry with Baby icon
|
||
- **Updated:** Page subtitle to include projected whelping dates
|
||
|
||
### March 9, 2026 - Heat Cycle Calendar & Trial Pairing Simulator (v0.5.0)
|
||
- **Added:** Full month grid heat cycle calendar with color-coded phase windows
|
||
- **Added:** Start Heat Cycle modal (click any day or header button)
|
||
- **Added:** Cycle Detail modal with breeding window breakdown and inline breeding date logging
|
||
- **Added:** Whelping estimate (earliest/expected/latest) auto-calculated from breeding date
|
||
- **Added:** Trial Pairing Simulator at `/pairing` with COI%, risk badge, common ancestors table
|
||
- **Added:** `GET /api/breeding/heat-cycles` and `GET /api/breeding/heat-cycles/:id/suggestions` endpoints
|
||
- **Moved:** Progesterone tracking to extended roadmap
|
||
|
||
### March 9, 2026 - Branding & Header Improvements (v0.4.1)
|
||
- **Added:** Custom `br-logo.png` brand logo in navbar
|
||
- **Added:** Gold-to-rusty-red gradient on "BREEDR" title text
|
||
- **Added:** `/static` directory for branding assets served by Express
|
||
- **Fixed:** Vite dev proxy for `/static` routes
|
||
- **Fixed:** `/static` and `/uploads` paths no longer fall through to React router
|
||
- **Fixed:** Brand logo sized as fixed 1:1 square for proper aspect ratio
|
||
|
||
### March 9, 2026 - Clean Database Schema (v0.4.0)
|
||
- **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
|
||
|
||
### March 8, 2026 - UI Redesign & Bug Fixes
|
||
- **Fixed:** Microchip field UNIQUE constraint (now properly optional)
|
||
- **Redesigned:** Modern dark theme with sleek aesthetics
|
||
- **Redesigned:** Compact horizontal info cards (80x80 avatars)
|
||
- **Improved:** Dashboard with gradient stats cards
|
||
- **Improved:** Navigation bar with glass morphism
|
||
- **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
|
||
|
||
## Support
|
||
|
||
For issues or questions:
|
||
- Check documentation in `docs/` folder
|
||
- Review DATABASE.md for schema questions
|
||
- Check container logs: `docker logs breedr`
|
||
- Contact the system administrator
|