diff --git a/README.md b/README.md index 0cc68a4..dd51e0d 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/ROADMAP.md b/ROADMAP.md index d6c240c..8988faf 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -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 - -- **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 +## 📋 Future Roadmap + +### ✅ 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 + +### 📅 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 + +--- + +## ✅ 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*