jason/breedr
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

readmes

Browse Source
This commit is contained in:
jason
2026-03-12 07:35:15 -05:00
parent 42bab14ac3
commit 5f68ca0e8b
2 changed files with 137 additions and 808 deletions
Download Patch File Download Diff File Expand all files Collapse all files

394
README.md
View File

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