Merge pull request 'docs: Update README & ROADMAP for v0.5.0 — Pairing Simulator + Heat Cycle Calendar' (#24) from docs/update-readme-roadmap-v0.5.1 into master

Reviewed-on: #24

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
+- `POST /api/pedigree/trial-pairing` - COI + common ancestors + risk recommendation
-- `GET/POST /api/breeding` - Heat cycles and breeding
+
+### 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
+### 🔧 In Progress / Up Next
-- [ ] Trial pairing simulator
+- [ ] Health Records System
-- [ ] Inbreeding coefficient calculator
+- [ ] Genetic trait tracking
-- [ ] Heat cycle tracking UI
 
 ### 📋 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
 

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
+- [x] **Trial Pairing Simulator** ✅ *(March 9, 2026)*
-  - [ ] Select sire and dam
+  - [x] Sire and dam selection dropdowns
-  - [ ] Display COI calculation
+  - [x] COI calculation display with color coding
-  - [ ] Show common ancestors
+  - [x] Common ancestors table (sire-gen / dam-gen columns)
-  - [ ] Risk assessment display
+  - [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
+- [x] **Heat Cycle Calendar** ✅ *(March 9, 2026)*
-  - [ ] Add/edit heat cycles
+  - [x] Full month grid calendar (Sun–Sat) with prev/next navigation
-  - [ ] Track progesterone levels
+  - [x] Color-coded day cells by cycle phase
-  - [ ] Calendar view
+  - [x] Start Heat Cycle modal (female dropdown + date picker)
-  - [ ] Breeding date suggestions
+  - [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
+### Health Records *(Priority 1)*
-- [ ] Add health test results
+- [ ] Health records list view per dog
-- [ ] Vaccination tracking
+- [ ] Add/edit health test results
-- [ ] Medical history timeline
+- [ ] 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 (based on cycle history)
-- [ ] Heat cycle predictions
+- [ ] Expected whelping alerts / push notifications
-- [ ] Expected whelping alerts
 - [ ] 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
+### ✅ Completed This Sprint (v0.5.0)
-- [x] Custom `br-logo.png` brand logo in navbar
+- [x] Trial Pairing Simulator — `/pairing` route, COI%, risk badge, common ancestors
-- [x] Gold-to-rusty-red gradient on BREEDR title
+- [x] Heat Cycle Calendar — month grid, phase color coding, start-cycle modal
-- [x] `/static` directory served by Express
+- [x] Cycle Detail modal — breeding windows, inline breeding date, whelping estimate
-- [x] Vite dev proxy for `/static`
+- [x] New backend endpoints: `GET /heat-cycles`, `GET /heat-cycles/:id/suggestions`
-- [x] Fixed route fall-through for `/static` and `/uploads`
+- [x] Removed `progesterone_peak_date` from POST/PUT (moved to extended backlog)
-- [x] Brand logo fixed to 1:1 aspect ratio
 
-### 🚧 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
+- Natural complement to existing dog profiles
-- Provides immediate breeding decision support
+- Vaccination expiry alerts are high day-to-day utility
-- High value feature for breeders
+- Clearance badges on dog cards improve trust at a glance
-- Relatively quick to implement
+- Builds toward breeding decision support
-
-**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
 
 **Tasks:**
 - Create `HealthRecordForm` component
-- Add vaccination tracking with expiry alerts
+- Health records list/timeline per dog on DogDetail page
-- Medical history timeline view
+- Vaccination tracking with expiry date + alert badge
-- PDF/image document uploads
+- Health clearance status badges (OFA, CERF, etc.)
-- Health clearance status badges
+- 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
+- [ ] Trial pairing simulator (end-to-end)
-- [ ] Heat cycle tracking
+- [ ] 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"
+1. Pick a feature from "Next Up" above
-2. Create a feature branch: `feature/feature-name`
+2. Create a feature branch: `feat/feature-name`
 3. Implement with tests
-4. Update this roadmap
+4. Update this roadmap and README.md
-5. Submit for review
+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