2026-03-09 20:41:40 -05:00
2 changed files with 148 additions and 106 deletions
--- a/README.md
+++ b/README.md
@@ -13,6 +13,8 @@ A reactive, interactive dog breeding genealogy mapping system for professional k
 - **✅ 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 and breeding date suggestions

 ### Database Architecture
 - **✅ Clean Schema** - No migrations, fresh installs create correct structure
@@ -23,6 +25,15 @@ A reactive, interactive dog breeding genealogy mapping system for professional k
 - **✅ Genetic Traits** - Inherited trait mapping

 ### Recently Added (March 9, 2026)
+- **✅ 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)
 - **✅ 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
@@ -30,13 +41,6 @@ A reactive, interactive dog breeding genealogy mapping system for professional k
 - **✅ 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

-### Previously Fixed
- **✅ Database Schema** - Removed weight/height columns, added litter_id
- **✅ Parent Handling** - Proper sire/dam via parents table
- **✅ Microchip Field** - Optional, allows multiple dogs without microchips
- **✅ Error Handling** - Graceful fallbacks for API failures
- **✅ UI Layout** - Fixed overlapping elements in dog forms
-
 ## Technology Stack

 - **Frontend**: React 18 with modern component design
@@ -136,10 +140,22 @@ npm run build
 breedr/
 ├── client/             # React frontend
 │   ├── src/
+│   │   ├── pages/
+│   │   │   ├── BreedingCalendar.jsx  # Heat cycle calendar (month grid)
+│   │   │   ├── 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
@@ -154,14 +170,31 @@ breedr/

 ## 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
- `GET/POST /api/litters` - Litter management
+
+### Pedigree & Genetics
 - `GET /api/pedigree/:id` - Generate pedigree tree
- `GET /api/health` - Health records
- `GET/POST /api/breeding` - Heat cycles and breeding
+- `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

@@ -200,9 +233,9 @@ docker-compose restart

 Check server logs for:
 ```
-✓ Dog inserted with ID: 123
+✔ Dog inserted with ID: 123
  Adding sire relationship: dog 123 -> sire 5
-  ✓ Sire relationship added
+  ✔ Sire relationship added
 ```

 If you don't see these logs, ensure `sire_id` and `dam_id` are being sent in the API request.
@@ -211,6 +244,10 @@ If you don't see these logs, ensure `sire_id` and `dam_id` are being sent in the

 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.
+
 ## Roadmap

 ### ✅ Completed
@@ -225,23 +262,32 @@ Ensure `br-logo.png` is placed in the `static/` directory at the project root. T
 - [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)

-### 🚧 In Progress
- [ ] Trial pairing simulator
- [ ] Inbreeding coefficient calculator
- [ ] Heat cycle tracking UI
+### 🔧 In Progress / Up Next
+- [ ] Health Records System
+- [ ] Genetic trait tracking

 ### 📋 Planned
- [ ] Health records management
- [ ] Genetic trait tracking
 - [ ] PDF pedigree generation
 - [ ] Advanced search and filters
 - [ ] Export capabilities
+- [ ] Progesterone tracking (extended feature)

 **Full roadmap:** [ROADMAP.md](ROADMAP.md)

 ## Recent Updates

+### 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
@@ -257,7 +303,6 @@ Ensure `br-logo.png` is placed in the `static/` directory at the project root. T
 - **Added:** litter_id column for linking puppies to litters
 - **Added:** Comprehensive DATABASE.md documentation
 - **Improved:** Server startup with clean initialization
- **Improved:** Logging for parent relationship creation

 ### March 8, 2026 - UI Redesign & Bug Fixes
 - **Fixed:** Microchip field UNIQUE constraint (now properly optional)
@@ -265,7 +310,6 @@ Ensure `br-logo.png` is placed in the `static/` directory at the project root. T
 - **Redesigned:** Compact horizontal info cards (80x80 avatars)
 - **Improved:** Dashboard with gradient stats cards
 - **Improved:** Navigation bar with glass morphism
- **Enhanced:** Age calculation and display
 - **Added:** Sex-colored icons (blue ♂, pink ♀)
 - **Added:** Registration number badges

--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -74,7 +74,7 @@

 ## ✅ Phase 3: Breeding Tools (COMPLETE)

-### Priority Features
+### Pedigree & Genetics
 - [x] **Interactive pedigree tree visualization**
  - [x] Integrate React-D3-Tree
  - [x] Show 3-5 generations
@@ -93,30 +93,38 @@
  - [x] Dual parent selection mode (litter/manual)
  - [x] UI fix for proper layout and error handling

- [ ] Trial Pairing Simulator
-  - [ ] Select sire and dam
-  - [ ] Display COI calculation
-  - [ ] Show common ancestors
-  - [ ] Risk assessment display
+- [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

- [ ] Heat Cycle Management
-  - [ ] Add/edit heat cycles
-  - [ ] Track progesterone levels
-  - [ ] Calendar view
-  - [ ] Breeding date suggestions
+- [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

 ---

-## 📋 Phase 4: Health & Genetics (PLANNED)
+## 📋 Phase 4: Health & Genetics (NEXT UP)

-### Health Records
- [ ] Add health test results
- [ ] Vaccination tracking
- [ ] Medical history timeline
+### Health Records *(Priority 1)*
+- [ ] Health records list view per dog
+- [ ] Add/edit health test results
+- [ ] Vaccination tracking with expiry alerts
+- [ ] Medical history timeline view
 - [ ] Document uploads (PDFs, images)
- [ ] Alert for expiring vaccinations
+- [ ] Health clearance status badges on dog cards

-### Genetic Tracking
+### Genetic Tracking *(Priority 2)*
 - [ ] Track inherited traits
 - [ ] Color genetics calculator
 - [ ] Health clearance status
@@ -134,10 +142,10 @@
 - [ ] Multi-generation COI analysis

 ### Breeding Planning
- [ ] Breeding calendar
- [ ] Heat cycle predictions
- [ ] Expected whelping alerts
+- [ ] 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
@@ -181,7 +189,13 @@

 ---

-## Future Enhancements (BACKLOG)
+## 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
@@ -209,77 +223,54 @@

 ---

-## 🌕 Current Sprint: v0.5.0
+## 🌕 Current Sprint: v0.6.0

-### ✅ Completed This Sprint
- [x] Custom `br-logo.png` brand logo in navbar
- [x] Gold-to-rusty-red gradient on BREEDR title
- [x] `/static` directory served by Express
- [x] Vite dev proxy for `/static`
- [x] Fixed route fall-through for `/static` and `/uploads`
- [x] Brand logo fixed to 1:1 aspect ratio
+### ✅ Completed This Sprint (v0.5.0)
+- [x] Trial Pairing Simulator — `/pairing` route, COI%, risk badge, common ancestors
+- [x] Heat Cycle Calendar — month grid, phase color coding, start-cycle modal
+- [x] Cycle Detail modal — breeding windows, inline breeding date, whelping estimate
+- [x] New backend endpoints: `GET /heat-cycles`, `GET /heat-cycles/:id/suggestions`
+- [x] Removed `progesterone_peak_date` from POST/PUT (moved to extended backlog)

-### 🚧 Next Up (Priority Order)
+### 🔧 Next Up (Priority Order)

-#### Option 1: Trial Pairing Simulator (Recommended) 👍
+#### Option 1: Health Records System (Recommended) 👆
 **Complexity:** Medium | **Impact:** High | **User Value:** Excellent

 **Why this is recommended:**
- Leverages existing COI calculator backend
- Provides immediate breeding decision support
- High value feature for breeders
- Relatively quick to implement
-
-**Tasks:**
- Create `PairingSimulator` component
- Add sire/dam selection dropdowns
- Display COI calculation results
- Show common ancestors table
- Add genetic risk assessment
- Color-coded recommendations (green/yellow/red)
-
-**Estimated Time:** 4-6 hours
-
---
-
-#### Option 2: Heat Cycle Management
-**Complexity:** Medium-High | **Impact:** Medium | **User Value:** Good
-
-**Why consider this:**
- Natural extension of litter management
- Helps with breeding planning
- Provides calendar functionality
-
-**Tasks:**
- Create `HeatCycleForm` component
- Add calendar view with heat cycle tracking
- Track progesterone levels
- Implement breeding date suggestions
- Whelping date calculator
-
-**Estimated Time:** 6-8 hours
-
---
-
-#### Option 3: Health Records System
-**Complexity:** Medium | **Impact:** High | **User Value:** Excellent
-
-**Why consider this:**
- Important for breeding decisions
- Vaccination tracking is valuable
- Document management adds utility
+- Natural complement to existing dog profiles
+- Vaccination expiry alerts are high day-to-day utility
+- Clearance badges on dog cards improve trust at a glance
+- Builds toward breeding decision support

 **Tasks:**
 - Create `HealthRecordForm` component
- Add vaccination tracking with expiry alerts
- Medical history timeline view
- PDF/image document uploads
- Health clearance status badges
+- Health records list/timeline per dog on DogDetail page
+- Vaccination tracking with expiry date + alert badge
+- Health clearance status badges (OFA, CERF, etc.)
+- Optional document/PDF upload

 **Estimated Time:** 6-8 hours

 ---

+#### Option 2: Genetic Trait Tracking
+**Complexity:** Medium | **Impact:** Medium | **User Value:** Good
+
+**Why consider this:**
+- Visual color/coat genetics are important for breeders
+- Links naturally to pedigree view
+- Useful for marketing/listing dogs
+
+**Tasks:**
+- Trait entry form (coat color, pattern, carried traits)
+- Display traits on dog detail page
+- Predicted trait calculator for trial pairings
+
+**Estimated Time:** 5-7 hours
+
+---
+
 ### Testing Needed
 - [x] Add/edit dog forms with litter selection
 - [x] Database schema initialization
@@ -291,8 +282,8 @@
 - [x] Brand logo display and sizing
 - [x] Gradient title rendering
 - [x] Static asset serving in prod and dev
- [ ] Trial pairing simulator
- [ ] Heat cycle tracking
+- [ ] Trial pairing simulator (end-to-end)
+- [ ] Heat cycle calendar (start cycle, detail modal, whelping)
 - [ ] Health records

 ### Known Issues
@@ -302,14 +293,21 @@

 ## How to Contribute

-1. Pick a feature from "Priority Features"
-2. Create a feature branch: `feature/feature-name`
+1. Pick a feature from "Next Up" above
+2. Create a feature branch: `feat/feature-name`
 3. Implement with tests
-4. Update this roadmap
-5. Submit for review
+4. Update this roadmap and README.md
+5. Submit PR for review

 ## Version History

+- **v0.5.0** (March 9, 2026) - Breeding Tools Complete
+  - Trial Pairing Simulator: COI calculator, risk badge, common ancestors
+  - Heat Cycle Calendar: month grid, phase windows, 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
+
 - **v0.4.1** (March 9, 2026) - Branding & Header Improvements
  - Custom br-logo.png in navbar
  - Gold-to-rusty-red gradient title