breedr/README.md

BREEDR - Dog Breeding Genealogy Management System

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

Database Architecture

• ✅ Clean Schema - No migrations, fresh installs create correct structure
• ✅ 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

Recently 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
• ✅ 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

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
• Visualization: React-D3-Tree for pedigree charts
• Backend: Node.js/Express API
• Database: SQLite (embedded, zero-config) with clean normalized schema
• Container: Single Docker image with multi-stage build
• Styling: CSS custom properties with dark theme + gradient branding

Quick Start

Docker Deployment (Recommended)

# 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

Fresh Install Database Setup

For a fresh install, the database will automatically initialize with the correct schema.

For an existing installation upgrade:

# Stop the application
docker-compose down

# Backup your data
cp data/breedr.db data/breedr.db.backup

# Delete old database (it will be recreated)
rm data/breedr.db

# Pull latest code
git pull origin master

# Rebuild and restart
docker-compose up -d --build

The app will create a fresh database with the clean schema automatically.

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

Core Tables

• dogs - Core dog registry (NO sire_id/dam_id columns)
• 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

Full schema documentation: DATABASE.md

Environment Variables

• NODE_ENV - production/development (default: production)
• PORT - Server port (default: 3000)
• DB_PATH - SQLite database path (default: /app/data/breedr.db)
• UPLOAD_PATH - Upload directory (default: /app/uploads)

Development

Local Development Setup

# Install dependencies
npm install

# Run development server (frontend + backend)
npm run dev

# Build for production
npm run build

Project Structure

breedr/
├── client/             # React frontend
│   ├── src/
│   ├── public/
│   └── package.json
├── server/             # Node.js backend
│   ├── routes/
│   ├── db/
│   │   └── init.js  # Clean schema (NO migrations)
│   └── index.js
├── static/             # Branding assets (br-logo.png, etc.)
├── docs/               # Documentation
├── DATABASE.md         # Schema documentation
├── ROADMAP.md          # Development roadmap
├── Dockerfile          # Multi-stage Docker build
├── docker-compose.yml
└── README.md

API Endpoints

• 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
• GET /api/pedigree/:id - Generate pedigree tree
• GET /api/health - Health records
• GET/POST /api/breeding - Heat cycles and breeding
• GET /static/* - Branding and static assets

Upgrading

From Earlier Versions

If you have an old database with sire/dam columns or missing litter_id:

# Backup your data
cp data/breedr.db data/breedr.db.backup

# Delete old database
rm data/breedr.db

# Pull latest code
git pull

# Restart (will create clean schema)
docker-compose restart

Important: The new schema uses a parents table instead of sire/dam columns. Parent data cannot be automatically migrated - you'll need to re-enter parent relationships.

Troubleshooting

"no such column: weight" or "no such column: sire_id"

Your database has an old schema. Delete and recreate:

rm data/breedr.db
docker-compose restart

Parent relationships not saving

Check server logs for:

✓ Dog inserted with ID: 123
  Adding sire relationship: dog 123 -> sire 5
  ✓ Sire relationship added

If you don't see these logs, ensure sire_id and dam_id are being sent in the API request.

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.

Roadmap

✅ Completed

• Docker containerization
• SQLite database with clean schema
• Dog management (CRUD)
• Photo management
• Interactive pedigree visualization
• Litter management
• Parent-child relationships via parents table
• Modern UI redesign
• Search and filtering
• Custom brand logo + gradient title
• Static asset serving

🚧 In Progress

• Trial pairing simulator
• Inbreeding coefficient calculator
• Heat cycle tracking UI

📋 Planned

• Health records management
• Genetic trait tracking
• PDF pedigree generation
• Advanced search and filters
• Export capabilities

Full roadmap: ROADMAP.md

Recent Updates

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

March 9, 2026 - Clean Database Schema (v0.4.0)

• Fixed: Database schema cleaned up - no migrations
• Fixed: Removed weight/height columns (never implemented)
• Fixed: Proper parent handling via parents table
• 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)
• Redesigned: Modern dark theme with sleek aesthetics
• 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

Documentation

• DATABASE.md - Complete schema documentation
• ROADMAP.md - Development roadmap and features
• INSTALL.md - Detailed installation instructions
• 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