breedr/ROADMAP.md

# 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)

### 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)
- [ ] Health clearance status badges on dog cards

**Complexity:** Medium | **Impact:** High | **User Value:** Excellent

**Why this is recommended:**
- 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

**Estimated Time:** 6-8 hours

### Genetic Trait Tracking *(Priority 2)*
- [ ] Track inherited traits
- [ ] Color genetics calculator
- [ ] Health clearance status
- [ ] Link traits to ancestors

**Estimated Time:** 5-7 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

### Advanced Genetics
- [ ] DNA test result tracking
- [ ] 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

### ✅ 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 call, duplicate health route removed
- [x] `server/routes/settings.js` rewrite — fixed double-encoded base64 + wrong key/value schema

### ✅ 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 (Priority Order)

#### Option 1: Health Records System (Recommended) 🚨
**Complexity:** Medium | **Impact:** High | **User Value:** Excellent

**Tasks:**
- Create `HealthRecordForm` component
- 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

**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
- [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

### Known Issues
- None currently

---

## 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
4. Update this roadmap and README.md
5. Submit PR for review

## Version History

- **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

- **v0.5.1** (March 9, 2026) - Projected Whelping Calendar Identifier
  - 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

- **v0.5.0** (March 9, 2026) - Breeding Tools Complete
  - 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

- **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