jason/breedr
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

readmes

Browse Source
This commit is contained in:
jason
2026-03-12 07:35:15 -05:00
parent 42bab14ac3
commit 5f68ca0e8b
2 changed files with 137 additions and 808 deletions
Download Patch File Download Diff File Expand all files Collapse all files

394
README.md
View File

@@ -2,365 +2,89 @@
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**
- **✅ Champion Bloodline Tracking** - Mark dogs as titled champions; offspring display a Champion Bloodline badge
- **✅ Kennel Settings** - Configurable kennel name, tagline, address, AKC ID, breed, owner info
- **✅ UI Theme** - CSS custom property theming with `--champion-gold` and dark-mode variables
## 🌟 Recent Highlights (v0.8.0)
- **✅ Reverse Pedigree** — Toggle between ancestors and descendants view for full lineage tracking.
- **✅ External Dog Mapping** — Assign parents to external dogs, allowing for full genealogy of outside lines.
- **✅ Universal Parent Selection** — Select any dog (kennel or external) as a sire/dam from any profile.
### Database Architecture
- **✅ Clean Schema** - No migrations needed; fresh installs create correct structure; existing DBs auto-migrate via safe `ALTER TABLE` guards
- **✅ 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
- **✅ Settings Table** - Single-row kennel configuration with all contact/identity fields
---
### Recently Added (March 10, 2026 — v0.6.1)
- **✅ COI Direct-Relation Fix** — `calculateCOI` now correctly computes inbreeding coefficient for parent×offspring pairings. Previously returned `0.00%` due to blanket exclusion of `sid` from `commonIds`; sire now correctly appears as a common ancestor in the dam's ancestry map when they are parent×offspring
- **✅ pedigree.js Route Fix** — `commonIds` filter changed from `id !== sid && id !== did` → `id !== did` only; preserves parent×offspring COI path while still preventing reflexive dam self-loop
- **Expected COI for parent×offspring pairing:** ~25.00% (Wright's path coefficient method)
### Previously Added (March 9, 2026 — v0.6.0)
- **✅ Champion Flag** — `is_champion INTEGER DEFAULT 0` on `dogs` table; safe `ALTER TABLE` migration guard for existing DBs
- **✅ Champion Toggle in DogForm** — amber-gold highlighted checkbox row with `Award` icon; marks dog as titled champion
- **✅ Champion ⭐ in Parent Dropdowns** — sire/dam selects append `⭐` to champion names for at-a-glance visibility
- **✅ Champion Bloodline Badge** — offspring of champion parents display a badge on dog cards and detail pages
- **✅ Kennel Settings API** — `GET/PUT /api/settings` with single-row column schema and ALLOWED_KEYS whitelist
- **✅ Settings Table Migration** — all kennel fields added with safe `ALTER TABLE` guards on existing DBs; default seed row auto-created
- **✅ SettingsProvider / useSettings** — React context hook renamed `useSettings.jsx` (was `.js`; contained JSX causing Vite build failure)
- **✅ `server/index.js` Fix** — `initDatabase()` called with no args to match updated `db/init.js`; removed duplicate `/api/health` route
- **✅ `settings.js` Route Fix** — rewrote from double-encoded base64 + old key/value schema to correct single-row column schema
### Previously 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 + safe `ALTER TABLE` migration guards
- **Container**: Single Docker image with multi-stage build
- **Styling**: CSS custom properties with dark theme + `--champion-gold` + gradient branding
## Quick Start
## 🚀 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`
### Upgrading an Existing Installation
The database now uses safe `ALTER TABLE` guards — **you do not need to delete your database to upgrade**. Just pull and rebuild:
```bash
docker-compose down
git pull origin master
docker-compose up -d --build
```
Access at: `http://localhost:3000`
New columns (`is_champion`, all `settings` kennel fields) are added automatically on first boot. Your existing dog data is preserved.
### Fresh Install Database Setup
For a **fresh install**, the database will automatically initialize with the correct schema and seed a default settings row.
## 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
4. **Safe migrations** - `ALTER TABLE ... ADD COLUMN` guards allow zero-downtime upgrades
### Core Tables
- **dogs** - Core dog registry; includes `is_champion`, `litter_id`, `photo_urls`
- **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
- **settings** - Single-row kennel configuration (kennel_name, tagline, address, phone, email, website, akc_id, breed, owner_name)
**Full schema documentation:** [DATABASE.md](DATABASE.md)
## Environment Variables
- `NODE_ENV` - production/development (default: production)
- `PORT` - Server port (default: 3000)
- `DATA_DIR` - Data directory for SQLite file (default: /app/data)
- `UPLOAD_PATH` - Upload directory (default: /app/uploads)
- `STATIC_PATH` - Static assets directory (default: /app/static)
## Development
### Local Development Setup
### Local Development
```bash
# Install dependencies
npm install
# Run development server (frontend + backend, nodemon auto-reload)
npm run dev
# Build for production
npm run build
```
> **Note:** `npm run dev` uses nodemon for auto-reload on the server. `npm start` (production) does **not** watch for changes — restart is required after pulling updates.
---
### Project Structure
## ✅ Core Features
### 🐕 Dog & Litter Management
- **Registry**: Complete CRUD operations for your kennel.
- **Photo Management**: Multiple high-quality photos per dog.
- **Litter Tracking**: Link puppies to breeding records automatically.
- **Champion Tracking**: Badge titled dogs; titles pass "Champion Bloodline" status to offspring.
### 🧬 Breeding & Genetics
- **Interactive Pedigree**: Multi-generational trees with zoom/pan and reverse (descendant) toggles.
- **Trial Pairing**: Simulator with **COI calculation**, common ancestor identification, and risk badges.
- **Heat Cycles**: Full calendar with phase tracking, breeding windows, and **projected whelping alerts**.
### ⚙️ Kennel Configuration
- **Settings System**: Centralized management for kennel name, branding, and contact info.
- **Branding**: Custom logo support and professional dark-themed UI with glassmorphism.
---
## 🛠️ Technology Stack
- **Frontend**: React 18, Vite, Lucide Icons
- **Visualization**: React-D3-Tree
- **Backend**: Node.js, Express.js
- **Database**: SQLite (Zero-config, safe `ALTER TABLE` migrations)
- **Deployment**: Multi-stage Docker
---
## 📂 Project Structure
```
breedr/
├── client/ # React frontend
│ ├── src/
│ │ ├── pages/
│ │ │ ├── BreedingCalendar.jsx # Heat cycle calendar + whelping identifiers
│ │ │ ├── PairingSimulator.jsx # Trial pairing + COI
│ │ │ ├── SettingsPage.jsx # Kennel settings form
│ │ │ ├── Dashboard.jsx
│ │ │ ├── DogList.jsx
│ │ │ ├── DogDetail.jsx
│ │ │ ├── PedigreeView.jsx
│ │ │ └── LitterList.jsx
│ │ ├── components/
│ │ │ └── DogForm.jsx # Champion toggle + parent selects
│ │ ├── hooks/
│ │ │ └── useSettings.jsx # SettingsProvider + useSettings context
│ │ └── App.jsx
│ └── package.json
├── server/ # Node.js backend
│ ├── routes/
│ │ ├── dogs.js # is_champion in all queries
│ │ ├── settings.js # GET/PUT kennel settings (single-row schema)
│ │ ├── breeding.js # Heat cycles, whelping, suggestions
│ │ ├── pedigree.js # COI, trial pairing (v0.6.1 direct-relation fix)
│ │ ├── litters.js
│ │ └── health.js
│ ├── db/
│ │ └── init.js # Schema + ALTER TABLE migration guards
│ └── index.js
├── static/ # Branding assets (br-logo.png, etc.)
├── docs/ # Documentation
├── ROADMAP.md
├── DATABASE.md
├── Dockerfile
├── docker-compose.yml
└── README.md
├── client/ # React frontend (Pages: Pedigree, Pairing, Calendar, Settings)
├── server/ # Node.js backend (Routes: Dogs, Pedigree, Breeding, Settings)
├── static/ # Branded assets (logos, etc.)
├── data/ # SQLite database storage (mapped in Docker)
├── uploads/ # Dog photo storage (mapped in Docker)
└── ROADMAP.md # Detailed development history & planned features
```
## API Endpoints
---
### Dogs
- `GET/POST /api/dogs` - Dog CRUD operations
- `GET /api/dogs/:id` - Get dog with parents (incl. is_champion), offspring, and health summary
- `PUT /api/dogs/:id` - Update dog (incl. is_champion)
- `POST /api/dogs/:id/photos` - Upload photos
## 🕒 Release Summary
### Settings
- `GET /api/settings` - Get kennel settings
- `PUT /api/settings` - Update kennel settings (partial update supported)
- **v0.8.0** (Mar 2026): Reverse Pedigree & External dog parentage.
- **v0.7.0** (In Progress): Health & Genetics (OFA clearances, DNA panels).
- **v0.6.1**: COI calculation fix for direct parent×offspring relations.
- **v0.6.0**: Champion status tracking & Kennel settings API.
- **v0.5.1**: Projected whelping windows and calendar identifiers.
- **v0.5.0**: Breeding tools, pairing simulator, and heat cycle calendar.
### Pedigree & Genetics
- `GET /api/pedigree/:id` - Generate pedigree tree
- `POST /api/pedigree/trial-pairing` - COI + common ancestors + risk recommendation
- `GET /api/pedigree/relations/:sireId/:damId` - Direct relation detection (parent/grandparent check)
---
### 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
## ❓ Troubleshooting
- **COI shows 0.00%?**: Ensure you are on v0.6.1+ to fix direct-relation pathing.
- **Missing Columns?**: Restart the server; safe migration guards add columns automatically.
- **Logo not appearing?**: Place `br-logo.png` in the `static/` directory.
### Litters
- `GET/POST /api/litters` - Litter management
### Assets
- `GET /static/*` - Branding and static assets
- `GET /uploads/*` - Dog photos
## Troubleshooting
### COI shows 0.00% for parent×offspring pairings
Ensure you are on v0.6.1+ (merge PR #47). The fix removes a blanket `id !== sid` exclusion in `calculateCOI` that was silently zeroing the inbreeding coefficient when the sire is a direct ancestor of the dam. After merging, restart the server.
### Server crashes with `SyntaxError: Unexpected end of input` on `settings.js`
The settings route file may have been corrupted (double-encoded base64). Pull the latest code and rebuild.
### "no such column: kennel_name" or "no such column: is_champion"
Your database predates the `ALTER TABLE` migration guards. Pull the latest code and restart — columns are added automatically. No data loss.
### "no such column: weight" or "no such column: sire_id"
Your database has a very old schema. Delete and recreate:
```bash
cp data/breedr.db data/breedr.db.backup
rm data/breedr.db
docker-compose restart
```
### 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.
## Roadmap
### ✅ Completed
- [x] Docker containerization
- [x] SQLite database with clean schema + ALTER TABLE migration guards
- [x] Dog management (CRUD) with champion flag
- [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)
- [x] **Champion Bloodline Tracking** (is_champion flag, DogForm toggle, offspring badge)
- [x] **Kennel Settings** (GET/PUT /api/settings, SettingsProvider, kennel name in navbar)
- [x] **COI Direct-Relation Fix** (parent×offspring now correctly yields ~25% COI — v0.6.1)
### 🔜 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 10, 2026 - COI Direct-Relation Bug Fix (v0.6.1)
- **Fixed:** `calculateCOI` in `server/routes/pedigree.js` — removed `id !== sid` from `commonIds` filter
- **Root cause:** `getAncestorMap` includes each dog at `gen 0`; the sire (`sid`) correctly appears in the dam's ancestor map at `gen 1` for parent×offspring pairings, but `id !== sid` was filtering it out and returning `0.00%`
- **Result:** Parent×offspring pairings now correctly return ~25.00% COI; all other pairings unaffected
- **PR:** [#47](https://git.alwisp.com/jason/breedr/pulls/47)
### March 9, 2026 - Champion Bloodline, Settings, Build Fixes (v0.6.0)
- **Added:** `is_champion` column to `dogs` table with safe `ALTER TABLE` migration guard
- **Added:** Champion toggle checkbox in DogForm with amber-gold highlight and `Award` icon
- **Added:** `⭐` suffix on champion sire/dam in parent dropdowns
- **Added:** Champion Bloodline badge on offspring cards/detail pages
- **Added:** `GET/PUT /api/settings` route — single-row column schema with `ALLOWED_KEYS` whitelist
- **Added:** Full kennel settings columns in `settings` table with migration guards
- **Added:** `SettingsProvider` / `useSettings` React context for kennel name in navbar
- **Fixed:** `useSettings.js` → `useSettings.jsx` (Vite build failure — JSX in `.js` file)
- **Fixed:** `server/index.js` — `initDatabase()` called with no args; removed duplicate `/api/health` route
- **Fixed:** `server/routes/settings.js` — rewrote from double-encoded base64 + old key/value schema
- **Fixed:** `DB_PATH` arg removed from `initDatabase()` call; `DATA_DIR` env var now controls directory
### 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
## 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
---
**Full Documentation & Roadmap**: [ROADMAP.md](ROADMAP.md) | [DATABASE.md](DATABASE.md)

545
ROADMAP.md
View File

@@ -1,402 +1,9 @@
# BREEDR Development Roadmap
## ✅ Phase 1: Foundation (COMPLETE)
### Infrastructure
- [x] Docker multi-stage build configuration
- [x] SQLite database with automatic initialization
- [x] Express.js API server
- [x] React 18 frontend with Vite
- [x] Git repository structure
### Database Schema
- [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
- [x] **Safe ALTER TABLE migration guards** - new columns added automatically on upgrade
### API Endpoints
- [x] `/api/dogs` - Full CRUD operations (incl. `is_champion`)
- [x] `/api/pedigree` - Tree generation and COI calculator
- [x] `/api/litters` - Breeding records
- [x] `/api/health` - Health tracking
- [x] `/api/breeding` - Heat cycles and whelping calculator
- [x] `/api/settings` - Kennel configuration (GET/PUT)
- [x] Photo upload with Multer
- [x] **Parent relationship handling** via parents table
- [x] `/static/*` - Branding and static asset serving
---
## ✅ Phase 2: Core Functionality (COMPLETE)
### Dog Management
- [x] Add new dogs with full form
- [x] Edit existing dogs
- [x] View dog details
- [x] List all dogs with search/filter
- [x] Upload multiple photos per dog
- [x] Delete photos
- [x] Parent selection (sire/dam) via parents table
- [x] **Proper error handling** for API failures
### User Interface
- [x] Dashboard with statistics
- [x] Dog list with grid view
- [x] Dog detail pages
- [x] Modal forms for add/edit
- [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
- [x] **Custom brand logo** (br-logo.png) in navbar
- [x] **Gold-to-rusty-red gradient** on BREEDR brand title
- [x] **Static asset serving** via Express `/static` route
- [x] **Vite dev proxy** for `/static` routes
- [x] **Route fix** - static/uploads don't fall through to React router
- [x] **Logo aspect ratio** fixed to 1:1 square
### Features Implemented
- [x] Photo upload and storage
- [x] Parent-child relationships (via parents table)
- [x] Basic information tracking
- [x] Registration numbers
- [x] Microchip tracking (optional)
- [x] **Litter linking** with litter_id
- [x] **Clean database schema** with no migrations
---
## ✅ Phase 3: Breeding Tools (COMPLETE)
### Pedigree & Genetics
- [x] **Interactive pedigree tree visualization**
- [x] Integrate React-D3-Tree
- [x] Show 3-5 generations
- [x] Click to navigate
- [x] Zoom and pan controls
- [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
- [x] **Trial Pairing Simulator** ✅ *(March 9, 2026)*
- [x] Sire and dam selection dropdowns
- [x] COI calculation display with color coding
- [x] Common ancestors table (sire-gen / dam-gen columns)
- [x] Risk badge: Low (<5%) / Moderate (5-10%) / High (>10%)
- [x] `/pairing` route + navbar link
- [x] `POST /api/pedigree/trial-pairing` backend
- [x] **Heat Cycle Calendar** ✅ *(March 9, 2026)*
- [x] Full month grid calendar (Sun–Sat) with prev/next navigation
- [x] Color-coded day cells by cycle phase
- [x] Start Heat Cycle modal (female dropdown + date picker)
- [x] Cycle Detail modal with phase breakdown
- [x] Breeding date logging inline
- [x] Whelping estimate (earliest/expected/latest)
- [x] Active cycles list with phase badge + day counter
- [x] `GET /api/breeding/heat-cycles` endpoint
- [x] `GET /api/breeding/heat-cycles/:id/suggestions` endpoint
- [x] **Projected Whelping Calendar Identifier** ✅ *(March 9, 2026 − v0.5.1)*
- [x] Gestation constants: earliest=58, expected=63, latest=65 days
- [x] `getWwhelpDates(cycle)` client-side helper (no extra API call)
- [x] Indigo whelp window cells (days 58–63) on calendar grid
- [x] Indigo dot marker on expected whelp day (day 63)
- [x] `Baby` icon + "[Name] due" label inside whelp day cells
- [x] "Whelp est. [date]" row with range on active cycle cards
- [x] Jump-to-whelp-month button on active cycle cards
- [x] Live whelp preview in Cycle Detail modal (client-side, instant)
- [x] Full-width whelping banner when projected whelps exist
- [x] "Projected Whelp" legend entry with Baby icon
- [x] Updated page subtitle to include whelping dates
---
## ✅ Phase 4a: Champion & Settings (COMPLETE − v0.6.0)
### Champion Bloodline Tracking
- [x] `is_champion INTEGER DEFAULT 0` column on `dogs` table
- [x] Safe `ALTER TABLE dogs ADD COLUMN is_champion` migration guard
- [x] `is_champion` included in all `GET /api/dogs` + `GET /api/dogs/:id` responses
- [x] `is_champion` persisted in `POST` and `PUT /api/dogs`
- [x] `is_champion` included on sire/dam JOIN queries and offspring query
- [x] Champion toggle checkbox in `DogForm` with amber-gold highlight + `Award` icon
- [x] `✪` suffix on champion names in sire/dam parent dropdowns
- [x] Champion Bloodline badge on offspring cards and dog detail pages
### Kennel Settings
- [x] `settings` table: `kennel_name`, `kennel_tagline`, `kennel_address`, `kennel_phone`, `kennel_email`, `kennel_website`, `kennel_akc_id`, `kennel_breed`, `owner_name`
- [x] Safe `ALTER TABLE settings ADD COLUMN` migration loop for all kennel fields
- [x] Auto-seed default row (`kennel_name = 'BREEDR'`) if table is empty
- [x] `GET /api/settings` − returns single-row as flat JSON object
- [x] `PUT /api/settings` − partial update via `ALLOWED_KEYS` whitelist
- [x] `SettingsProvider` / `useSettings` React context hook
- [x] Kennel name displayed in navbar from settings
- [x] `SettingsPage` component for editing kennel info
### Build & Runtime Fixes (v0.6.0)
- [x] `useSettings.js` → `useSettings.jsx` − Vite build failed because JSX in `.js` file
- [x] `server/index.js` − `initDatabase()` called with no args (was passing `DB_PATH`, now path is internal)
- [x] `server/index.js` − removed duplicate `app.get('/api/health')` inline route
- [x] `server/index.js` − `DATA_DIR` env var replaces `path.dirname(DB_PATH)` for directory creation
- [x] `server/routes/settings.js` − rewrote from double-encoded base64 + old key/value schema to correct single-row column schema
---
## 📋 Phase 4b: Health & Genetics (NEXT UP − v0.7.0)
## 🚀 Current Status: v0.8.0 (Active Development)
### 🔜 Next Up — Phase 4b: Health & Genetics Build Order
> **Context:** Golden Retriever health clearances follow GRCA Code of Ethics and OFA/CHIC standards.
> This phase builds a structured, breed-aware health tracking system aligned with those requirements.
### Tier 1 — OFA Health Clearances *(Priority 1)* 🩺
The four GRCA-required clearances that must be on record in the public OFA database before breeding.
**Database (schema additions to `health_records` table):**
- [ ] Add `test_type` ENUM-style field: `hip_ofa`, `hip_pennhip`, `elbow_ofa`, `heart_ofa`, `heart_echo`, `eye_caer`, `thyroid_ofa`, `dna_panel`
- [ ] Add `result` field: `pass`, `fail`, `carrier`, `clear`, `excellent`, `good`, `fair`, `borderline`
- [ ] Add `ofa_number` VARCHAR — official OFA certification number
- [ ] Add `chic_number` VARCHAR — CHIC certification number (dog-level field on `dogs` table)
- [ ] Add `performed_by` VARCHAR — vet or specialist name
- [ ] Add `expires_at` DATE — for annually-renewed tests (eyes, heart)
- [ ] Add `document_url` VARCHAR — path to uploaded PDF/image
- [ ] Safe ALTER TABLE migration guards for all new columns
**API:**
- [ ] `GET /api/health/:dogId` — list all health records for a dog
- [ ] `POST /api/health` — create health record
- [ ] `PUT /api/health/:id` — update health record
- [ ] `DELETE /api/health/:id` — delete health record
- [ ] `GET /api/health/:dogId/clearance-summary` — returns pass/fail/missing for all 4 OFA tiers
- [ ] `GET /api/health/:dogId/chic-eligible` — returns boolean + missing tests
**UI Components:**
- [ ] `HealthRecordForm` modal — test type dropdown, result, OFA#, date, performed-by, expiry, document upload
- [ ] `HealthTimeline` component — chronological list of all health events per dog on DogDetail page
- [ ] `ClearanceSummaryCard` — shows OFA Hip / Elbow / Heart / Eyes status in a 2x2 grid with color badges (green=pass, yellow=expiring, red=missing/fail)
- [ ] `ChicStatusBadge` — amber badge on dog cards and DogDetail if CHIC number is on file
- [ ] Expiry alert: yellow badge on dog card if any annual test expires within 90 days; red if expired
- [ ] Document upload support (PDF/image) tied to individual health records
**Clearance Tiers Tracked:**
| Test | OFA Minimum Age | Renewal | Notes |
|---|---|---|---|
| Hip Dysplasia | 24 months | Once (final) | OFA eval or PennHIP |
| Elbow Dysplasia | 24 months | Once (final) | OFA eval |
| Cardiac (Heart) | 12 months | Annual recommended | Echo preferred over auscultation |
| Eyes (CAER) | 12 months | **Annual** | Board-certified ACVO ophthalmologist |
| Thyroid (OFA) | 12 months | Annual recommended | Bonus/Tier 2 |
**Complexity:** Medium | **Impact:** High | **User Value:** Excellent
**Estimated Time:** 8–10 hours
---
### Tier 2 — DNA Genetic Panel *(Priority 2)* 🧬
Embark or equivalent panel results per dog. Allows carrier × clear pairing without producing affected offspring.
**Database:**
- [ ] `genetic_tests` table: `id`, `dog_id`, `test_provider` (embark/optigen/etc), `test_name`, `result` (clear/carrier/affected), `test_date`, `document_url`, `created_at`
- [ ] Safe `CREATE TABLE IF NOT EXISTS` guard
**Golden Retriever Panel — Key Markers:**
- [ ] PRA1 (Progressive Retinal Atrophy type 1)
- [ ] PRA2 (Progressive Retinal Atrophy type 2)
- [ ] prcd-PRA (Progressive Rod-Cone Degeneration)
- [ ] ICH1 / ICH2 (Ichthyosis — very common in Goldens)
- [ ] NCL (Neuronal Ceroid Lipofuscinosis — fatal neurological)
- [ ] DM (Degenerative Myelopathy)
- [ ] MD (Muscular Dystrophy)
- [ ] GR-PRA1, GR-PRA2 (Golden-specific PRA variants)
**API:**
- [ ] `GET /api/genetics/:dogId` — list all genetic test results
- [ ] `POST /api/genetics` — add genetic result
- [ ] `PUT /api/genetics/:id` — update
- [ ] `DELETE /api/genetics/:id` — delete
- [ ] `GET /api/genetics/pairing-risk?sireId=&damId=` — returns at-risk combinations for a trial pairing
**UI Components:**
- [ ] `GeneticTestForm` modal — provider, marker, result (clear/carrier/affected), date, upload
- [ ] `GeneticPanelCard` on DogDetail — color-coded grid of all markers (green=clear, yellow=carrier, red=affected, gray=not tested)
- [ ] Pairing risk overlay on Trial Pairing Simulator — flag if sire+dam are both carriers for same marker
- [ ] "Not Tested" indicator on dog cards when no DNA panel on file
**Complexity:** Medium | **Impact:** High | **User Value:** Excellent
**Estimated Time:** 6–8 hours
---
### Tier 3 — Cancer Lineage & Longevity Tracking *(Priority 3)* 📊
Golden Retrievers have ~60% cancer mortality rate. Lineage-based cancer history is a major differentiator for responsible breeders.
**Database:**
- [ ] `cancer_history` table: `id`, `dog_id`, `cancer_type`, `age_at_diagnosis`, `age_at_death`, `cause_of_death`, `notes`, `created_at`
- [ ] Add `age_at_death` and `cause_of_death` optional fields to `dogs` table
**API:**
- [ ] `GET /api/health/:dogId/cancer-history`
- [ ] `POST /api/health/cancer-history`
- [ ] `GET /api/pedigree/:dogId/cancer-lineage` — walks ancestors and returns cancer incidence summary
**UI:**
- [ ] Longevity section on DogDetail — age at death, cause of death
- [ ] Cancer lineage indicator on Trial Pairing Simulator — "X of 8 ancestors had cancer history"
- [ ] Optional cancer history entry on DogForm
**Complexity:** Low-Medium | **Impact:** Medium | **User Value:** High (differentiator)
**Estimated Time:** 4–5 hours
---
### Tier 4 — Breeding Eligibility Checker *(Priority 4)* ✅
Automatic litter eligibility gate based on health clearance status of sire and dam.
**Logic:**
- [ ] Dog is "GRCA eligible" if: Hip OFA ✅ + Elbow OFA ✅ + Heart ✅ + Eyes (non-expired) ✅ + age ≥ 24 months
- [ ] Dog is "CHIC eligible" if all four tests are in OFA public database (CHIC number on file)
- [ ] Warning flags in Trial Pairing Simulator if sire or dam is missing required clearances
- [ ] Block litter creation (with override) if either parent fails eligibility check
**UI:**
- [ ] Eligibility badge on dog cards: `GRCA Eligible` (green) / `Incomplete` (yellow) / `Not Eligible` (red)
- [ ] Eligibility breakdown tooltip on hover — shows which tests are missing
- [ ] Pre-litter warning modal when creating a litter with non-eligible parents
- [ ] CHIC number field + verification note on DogDetail
**Complexity:** Low | **Impact:** High | **User Value:** Excellent
**Estimated Time:** 3–4 hours
---
## 📋 Phase 5: Advanced Features (PLANNED)
### Pedigree Tools
- [ ] Reverse pedigree (descendants view)
- [ ] PDF pedigree generation
- [ ] Export to standard formats
- [ ] Print-friendly layouts
- [ ] Multi-generation COI analysis
### Breeding Planning
- [ ] Heat cycle predictions (based on cycle history)
- [ ] Expected whelping alerts / push notifications
- [ ] Breeding history reports
- [ ] iCal export for cycle events
### Search & Analytics
- [ ] Advanced search filters
- [ ] By breed, color, age
- [ ] By health clearances
- [ ] By registration status
- [ ] Statistics dashboard
- [ ] Breeding success rates
- [ ] Average litter sizes
- [ ] Popular pairings
---
## 📋 Phase 6: Polish & Optimization (PLANNED)
### User Experience
- [ ] Loading states for all operations
- [ ] Better error messages
- [ ] Confirmation dialogs
- [ ] Undo functionality
- [ ] Keyboard shortcuts
### Performance
- [ ] Image optimization
- [ ] Lazy loading
- [ ] API caching
- [ ] Database query optimization
### Mobile
- [ ] Touch-friendly interface
- [ ] Mobile photo capture
- [ ] Responsive tables
- [ ] Offline mode
### Documentation
- [x] DATABASE.md - Complete schema documentation
- [x] User-facing documentation
- [ ] API documentation
- [ ] Video tutorials
- [ ] FAQ section
---
## Future / Extended Features (BACKLOG)
### Progesterone Tracking *(Moved from Phase 3)*
- [ ] Log progesterone level readings per heat cycle
- [ ] Chart progesterone curve over cycle days
- [ ] LH surge detection
- [ ] Optimal breeding day prediction from levels
### Multi-User Support
- [ ] User authentication
- [ ] Role-based permissions
- [ ] Activity logs
- [ ] Shared access
### Integration
- [ ] Import from other systems
- [ ] Export to Excel/CSV
- [ ] Integration with kennel clubs
- [ ] Backup to cloud storage
- [ ] OFA database lookup by registration number
### Advanced Genetics
- [ ] DNA test result tracking (full Embark import)
- [ ] Genetic diversity analysis
- [ ] Breed-specific calculators
- [ ] Health risk predictions
### Kennel Management
- [ ] Breeding contracts
- [ ] Buyer tracking
- [ ] Financial records
- [ ] Stud service management
---
## 🏃 Current Sprint: v0.7.0 (Phase 4b)
### ✅ Completed This Sprint (v0.6.0)
- [x] `is_champion` flag − DB column, API, DogForm toggle, offspring badge, parent dropdown `✪`
- [x] Kennel Settings − `settings` table with all kennel fields, `GET/PUT /api/settings`, `SettingsProvider`, navbar kennel name
- [x] `useSettings.jsx` rename (Vite build fix)
- [x] `server/index.js` fix − `initDatabase()` no-arg, duplicate health route removed
- [x] `server/routes/settings.js` rewrite: double-encoded base64 + wrong schema fixed
### ✅ Previously Completed (v0.5.1)
- [x] Projected Whelping Calendar Identifier − indigo whelp window cells, due label, active card range, jump-to-month button
- [x] Live whelp preview in Cycle Detail modal (client-side, no save required)
- [x] Full-width whelping banner for months with projected whelps
- [x] "Projected Whelp" legend entry + updated page subtitle
### 🔜 Next Up — Phase 4b Build Order
#### Step 1: DB Schema Extensions
- [ ] Extend `health_records` table with OFA-specific columns (test_type, result, ofa_number, chic_number, expires_at, document_url)
@@ -430,45 +37,15 @@ Automatic litter eligibility gate based on health clearance status of sire and d
- [ ] Eligibility badge on dog cards
- [ ] Pre-litter eligibility warning modal
#### Step 6: Cancer / Longevity (Stretch)
- [ ] Cancer history form + lineage summary on Trial Pairing page
- [ ] Age at death / cause of death on DogDetail
### Testing Needed
- [x] Add/edit dog forms with litter selection
- [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
- [x] Brand logo display and sizing
- [x] Gradient title rendering
- [x] Static asset serving in prod and dev
- [ ] Champion toggle − DogForm save/load round-trip
- [ ] Champion badge − offspring card display
- [ ] Kennel settings − save + navbar name update
- [ ] Trial pairing simulator (end-to-end)
- [ ] Heat cycle calendar (start cycle, detail modal, whelping)
- [ ] Projected whelping calendar identifier (whelp cells, due label, banner)
- [ ] Health records — OFA clearance CRUD
- [ ] Genetic panel — DNA marker entry and display
- [ ] Eligibility checker — badge and litter gate
### Known Issues
- None currently
---
## How to Contribute
## 🕒 Version History & Recent Progress
1. Pick a feature from "Next Up" above
2. Create a feature branch off `master`: `feat/feature-name`
3. Implement with tests
4. Update this roadmap and README.md
5. Submit PR for review
## Version History
- **v0.8.0** (March 12, 2026) - Reverse Pedigree & External Parentage (LATEST)
- [x] **Reverse Pedigree** (descendants view) toggle on Pedigree page
- [x] **External dog parentage** improvements (allowed assigning sire/dam to external dogs)
- [x] **Universal parent selection** (sire/dam dropdowns now include all dogs)
- [x] Updated documentation and roadmap
- **v0.7.0** (In Progress) - Phase 4b: Health & Genetics
- OFA clearance tracking (Hip, Elbow, Heart, Eyes + CHIC number)
@@ -476,58 +53,86 @@ Automatic litter eligibility gate based on health clearance status of sire and d
- Cancer lineage & longevity tracking
- Breeding eligibility checker (GRCA + CHIC gates)
- **v0.6.1** (March 10, 2026) - COI Direct-Relation Fix
- Fixed `calculateCOI` to correctly compute coefficient for parent×offspring pairings (~25%)
- Removed blanket sire exclusion in ancestor mapping logic
- **v0.6.0** (March 9, 2026) - Champion Bloodline, Settings, Build Fixes
- `is_champion` flag on dogs table with ALTER TABLE migration guard
- Champion toggle in DogForm; `✪` suffix in parent dropdowns; offspring badge
- Kennel settings table + `GET/PUT /api/settings` + `SettingsProvider`
- `useSettings.jsx` rename (Vite build fix)
- `server/index.js` fix: `initDatabase()` no-arg, duplicate health route removed
- `server/routes/settings.js` rewrite: double-encoded base64 + wrong schema fixed
- `server/routes/settings.js` rewrite: double-encoded base64 fixed
- **v0.5.1** (March 9, 2026) - Projected Whelping Calendar Identifier
- **v0.5.1** (March 9, 2026) - Projected Whelping Calendar
- Indigo whelp window cells (days 58–65) on month grid
- Indigo dot marker on exact expected whelp day (day 63)
- `Baby` icon + "[Name] due" label in whelp day cells
- "Whelp est." range row on active cycle cards
- Jump-to-whelp-month button on cycle cards
- Live whelp preview in Cycle Detail modal (client-side, instant)
- Full-width whelping banner when projected whelps exist
- "Projected Whelp" legend entry + updated page subtitle
- Live whelp preview in Cycle Detail modal
- **v0.5.0** (March 9, 2026) - Breeding Tools Complete
- **v0.5.0** (March 9, 2026) - Breeding Tools
- Trial Pairing Simulator: COI calculator, risk badge, common ancestors
- Heat Cycle Calendar: month grid, phase color coding, start-cycle modal
- Cycle Detail: breeding windows, inline breeding date, whelping estimate
- New API: `GET /heat-cycles`, `GET /heat-cycles/:id/suggestions`
- Progesterone tracking moved to extended backlog
- Heat Cycle Calendar: month grid, phase color coding, suggestions
- **v0.4.1** (March 9, 2026) - Branding & Header Improvements
- Custom br-logo.png in navbar
- Gold-to-rusty-red gradient title
- Static asset serving via Express
- Vite dev proxy for /static
- Route fix for static/uploads paths
- Logo 1:1 aspect ratio fix
---
- **v0.4.0** (March 9, 2026) - Clean Database Schema
- Complete database overhaul with clean normalized design
- Removed migrations, fresh init only
- Parents table for relationships
- Comprehensive documentation
## 📋 Future Roadmap
- **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
### ✅ Phase 5: Advanced Features (IN PROGRESS)
- [x] Reverse pedigree (descendants view)
- [ ] PDF pedigree generation
- [ ] Export to standard formats (CSV, JSON)
- [ ] Print-friendly layouts
- [ ] Multi-generation COI analysis
- **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
### 📅 Phase 6: Polish & Optimization
- [ ] **User Experience**: Loading states, better error messages, undo functionality
- [ ] **Performance**: Image optimization, lazy loading, API caching
- [ ] **Mobile**: Touch-friendly interface, mobile photo capture
- [ ] **Documentation**: API technical docs, video tutorials
- **v0.2.0** - Dog CRUD operations complete
- **v0.1.0** - Initial foundation with API and database
---
## ✅ Completed Milestones
### Phase 1: Foundation
- [x] Docker multi-stage build & SQLite database
- [x] Express.js API server & React 18 frontend
- [x] Parents relationship table for sire/dam tracking
### Phase 2: Core Functionality
- [x] Dog Management (Full CRUD, photo uploads)
- [x] Modern dark theme with glass morphism
- [x] Branded navigation with custom logo
### Phase 3: Breeding Tools
- [x] Interactive pedigree tree visualization (React-D3-Tree)
- [x] Litter Management & linking puppies
- [x] Trial Pairing Simulator & Heat Cycle Calendar
- [x] Projected Whelping identifiers
### Phase 4a: Champion & Settings
- [x] Champion bloodline tracking and badges
- [x] Universal Kennel Settings system
---
## 🏃 Testing & Quality Assurance
- [x] Database schema initialization guards
- [x] Pedigree tree rendering & zoom/pan
- [x] Parent relationship creation logic
- [x] Static asset serving (prod/dev)
- [ ] Champion toggle load/save trip
- [ ] Heat cycle calendar whelping logic
- [ ] Health records OFA clearance CRUD (Upcoming)
---
## How to Contribute
1. Pick a feature from "Next Up" above
2. Create a feature branch off `master`: `feat/feature-name`
3. Implement with tests and update this roadmap
4. Submit PR for review
---
*Last Updated: March 12, 2026*