breedr/ROADMAP.md

BREEDR Development Roadmap

✅ Phase 1: Foundation (COMPLETE)

Infrastructure

• Docker multi-stage build configuration
• SQLite database with automatic initialization
• Express.js API server
• React 18 frontend with Vite
• Git repository structure

Database Schema

• Dogs table with core fields (NO sire/dam columns)
• Parents relationship table for sire/dam tracking
• Litters breeding records
• Health records tracking
• Heat cycles management
• Traits genetic mapping
• Indexes and triggers
• litter_id column for linking puppies to litters
• Clean schema design - NO migrations, fresh init only
• Safe ALTER TABLE migration guards - new columns added automatically on upgrade

API Endpoints

• /api/dogs - Full CRUD operations (incl. is_champion)
• /api/pedigree - Tree generation and COI calculator
• /api/litters - Breeding records
• /api/health - Health tracking
• /api/breeding - Heat cycles and whelping calculator
• /api/settings - Kennel configuration (GET/PUT)
• Photo upload with Multer
• Parent relationship handling via parents table
• /static/* - Branding and static asset serving

---

✅ Phase 2: Core Functionality (COMPLETE)

Dog Management

• Add new dogs with full form
• Edit existing dogs
• View dog details
• List all dogs with search/filter
• Upload multiple photos per dog
• Delete photos
• Parent selection (sire/dam) via parents table
• Proper error handling for API failures

User Interface

• Dashboard with statistics
• Dog list with grid view
• Dog detail pages
• Modal forms for add/edit
• Photo management UI
• Search and sex filtering
• Responsive navigation
• Compact info cards (80x80 avatars)
• Modern dark theme with glass morphism
• Custom brand logo (br-logo.png) in navbar
• Gold-to-rusty-red gradient on BREEDR brand title
• Static asset serving via Express /static route
• Vite dev proxy for /static routes
• Route fix - static/uploads don't fall through to React router
• Logo aspect ratio fixed to 1:1 square

Features Implemented

• Photo upload and storage
• Parent-child relationships (via parents table)
• Basic information tracking
• Registration numbers
• Microchip tracking (optional)
• Litter linking with litter_id
• Clean database schema with no migrations

---

✅ Phase 3: Breeding Tools (COMPLETE)

Pedigree & Genetics

• Interactive pedigree tree visualization

  • Integrate React-D3-Tree
  • Show 3-5 generations
  • Click to navigate
  • Zoom and pan controls
  • Beautiful color-coded nodes
  • Male/Female distinction

• Litter Management ✅

  • Create litter records
  • Link puppies to litter
  • Track whelping details
  • Auto-link parent relationships
  • Database migration for litter_id
  • Enhanced API endpoints
  • Dual parent selection mode (litter/manual)
  • UI fix for proper layout and error handling

• Trial Pairing Simulator ✅ (March 9, 2026)

  • Sire and dam selection dropdowns
  • COI calculation display with color coding
  • Common ancestors table (sire-gen / dam-gen columns)
  • Risk badge: Low (<5%) / Moderate (5-10%) / High (>10%)
  • /pairing route + navbar link
  • POST /api/pedigree/trial-pairing backend

• Heat Cycle Calendar ✅ (March 9, 2026)

  • Full month grid calendar (Sun–Sat) with prev/next navigation
  • Color-coded day cells by cycle phase
  • Start Heat Cycle modal (female dropdown + date picker)
  • Cycle Detail modal with phase breakdown
  • Breeding date logging inline
  • Whelping estimate (earliest/expected/latest)
  • Active cycles list with phase badge + day counter
  • GET /api/breeding/heat-cycles endpoint
  • GET /api/breeding/heat-cycles/:id/suggestions endpoint

• Projected Whelping Calendar Identifier ✅ (March 9, 2026 − v0.5.1)

  • Gestation constants: earliest=58, expected=63, latest=65 days
  • getWwhelpDates(cycle) client-side helper (no extra API call)
  • Indigo whelp window cells (days 58–63) on calendar grid
  • Indigo dot marker on expected whelp day (day 63)
  • Baby icon + "[Name] due" label inside whelp day cells
  • "Whelp est. [date]" row with range on active cycle cards
  • Jump-to-whelp-month button on active cycle cards
  • Live whelp preview in Cycle Detail modal (client-side, instant)
  • Full-width whelping banner when projected whelps exist
  • "Projected Whelp" legend entry with Baby icon
  • Updated page subtitle to include whelping dates

---

✅ Phase 4a: Champion & Settings (COMPLETE − v0.6.0)

Champion Bloodline Tracking

• is_champion INTEGER DEFAULT 0 column on dogs table
• Safe ALTER TABLE dogs ADD COLUMN is_champion migration guard
• is_champion included in all GET /api/dogs + GET /api/dogs/:id responses
• is_champion persisted in POST and PUT /api/dogs
• is_champion included on sire/dam JOIN queries and offspring query
• Champion toggle checkbox in DogForm with amber-gold highlight + Award icon
• ✪ suffix on champion names in sire/dam parent dropdowns
• Champion Bloodline badge on offspring cards and dog detail pages

Kennel Settings

• settings table: kennel_name, kennel_tagline, kennel_address, kennel_phone, kennel_email, kennel_website, kennel_akc_id, kennel_breed, owner_name
• Safe ALTER TABLE settings ADD COLUMN migration loop for all kennel fields
• Auto-seed default row (kennel_name = 'BREEDR') if table is empty
• GET /api/settings − returns single-row as flat JSON object
• PUT /api/settings − partial update via ALLOWED_KEYS whitelist
• SettingsProvider / useSettings React context hook
• Kennel name displayed in navbar from settings
• SettingsPage component for editing kennel info

Build & Runtime Fixes (v0.6.0)

• useSettings.js → useSettings.jsx − Vite build failed because JSX in .js file
• server/index.js − initDatabase() called with no args (was passing DB_PATH, now path is internal)
• server/index.js − removed duplicate app.get('/api/health') inline route
• server/index.js − DATA_DIR env var replaces path.dirname(DB_PATH) for directory creation
• 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)

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

• DATABASE.md - Complete schema documentation
• 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)

• is_champion flag − DB column, API, DogForm toggle, offspring badge, parent dropdown ✪
• Kennel Settings − settings table with all kennel fields, GET/PUT /api/settings, SettingsProvider, navbar kennel name
• 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

✅ Previously Completed (v0.5.1)

• Projected Whelping Calendar Identifier − indigo whelp window cells, due label, active card range, jump-to-month button
• Live whelp preview in Cycle Detail modal (client-side, no save required)
• Full-width whelping banner for months with projected whelps
• "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)
• Create genetic_tests table (PRA, ICH, NCL, DM, MD, GR-PRA variants)
• Create cancer_history table
• Add chic_number, age_at_death, cause_of_death to dogs table
• All changes via safe ALTER TABLE / CREATE TABLE IF NOT EXISTS guards

Step 2: API Layer

• GET|POST|PUT|DELETE /api/health/:dogId (OFA records)
• GET /api/health/:dogId/clearance-summary
• GET /api/health/:dogId/chic-eligible
• GET|POST|PUT|DELETE /api/genetics/:dogId
• GET /api/genetics/pairing-risk (sire + dam carrier check)
• Cancer history endpoints

Step 3: Core UI — Health Records

• HealthRecordForm modal (test type, result, OFA#, expiry, doc upload)
• HealthTimeline on DogDetail page
• ClearanceSummaryCard 2×2 grid (Hip / Elbow / Heart / Eyes)
• ChicStatusBadge on dog cards
• Expiry alert badges (90-day warning, expired)

Step 4: Core UI — Genetics Panel

• GeneticTestForm modal
• GeneticPanelCard on DogDetail (color-coded markers)
• Pairing risk overlay on Trial Pairing Simulator

Step 5: Eligibility Checker

• Eligibility logic (grca_eligible, chic_eligible computed fields)
• 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

• Add/edit dog forms with litter selection
• Database schema initialization
• Pedigree tree rendering
• Zoom/pan controls
• UI layout fixes
• Error handling for API failures
• Parent relationship creation via parents table
• Brand logo display and sizing
• Gradient title rendering
• 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

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.7.0 (In Progress) - Phase 4b: Health & Genetics

  • OFA clearance tracking (Hip, Elbow, Heart, Eyes + CHIC number)
  • DNA genetic panel (PRA, ICH, NCL, DM, MD variants)
  • Cancer lineage & longevity tracking
  • Breeding eligibility checker (GRCA + CHIC gates)

• 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