breedr/DEVELOPMENT.md

DEVELOPMENT.md

This document provides technical details and guidelines for developing and maintaining the BREEDR Genealogy Management System.

Tech Stack Overview

Backend

• Node.js & Express: Core API server. Node 18+ required (better-sqlite3 v11 prebuilds cover Node 18–24; Docker runs node:18).
• better-sqlite3: High-performance SQLite driver. Multi-step writes use db.transaction().
• Multer: Multi-part form data handling for photo and document uploads (type + size limits enforced).
• Authentication: Deliberately not implemented — BREEDR is a self-hosted LAN app. Revisit as its own feature if exposure changes (decision: July 2026).

Frontend

• React 18 & Vite: Modern reactive UI with fast HMR.
• React Router 6: Client-side navigation.
• Lucide React: Consistent iconography.
• React-D3-Tree & D3.js: Dynamic pedigree visualization.
• Axios: Promised-based HTTP client for API communication.

---

Database Architecture

SQLite Implementation

The database is a single file at data/breedr.db by default; both the migration runner and the app honor DB_PATH, and the containing directory is created automatically on startup.

"Parents Table" Approach

Parent relationships are managed in a dedicated parents table rather than columns in the dogs table.

• ** dog_id**: The child dog.
• ** parent_id**: The parent dog.
• ** parent_type**: 'sire' or 'dam'.

Benefits: Supports recursive lookups, avoids ALTER TABLE complexity for lineage changes, and allows historical mapping of ancestors without full profiles.

Safe Migrations

BREEDR uses a two-layer synchronization approach, both run at startup (server/index.js):

1. server/db/migrations.js — a versioned migration runner for structural rewrites (e.g. moving sire/dam into the parents table). Migrations no-op on a fresh/empty database.
2. server/db/init.js — defines the latest table structures (CREATE TABLE IF NOT EXISTS) and injects missing columns with safe ALTER TABLE guards.

⚠️ Keep init.js in sync with the routes. The schema drifted once (routes wrote columns init.js never defined) and only worked because the live Docker volume carried an older ad-hoc schema — fresh installs were broken. When adding a column a route writes, add it to the CREATE TABLE and the ALTER-if-missing list. Verify by booting against a deleted/renamed dev DB.

Key Tables

• dogs: Registry for kennel and external dogs.
• parents: Ancestry relationships.
• litters: Produced breeding groups.
• heat_cycles: Female heat cycle tracking (calendar + whelping projections).
• health_records: OFA clearances, vet records, and puppy weight logs.
• genetic_tests: DNA panel results.
• cancer_history: Cancer/longevity lineage records.
• settings: Kennel-wide configuration (single row).

---

Frontend Documentation

Project Structure

client/src/
├── components/     # Reusable UI (PedigreeTree, DogForm, Cards)
├── hooks/          # Custom hooks (useSettings)
├── pages/          # Route-level components
├── App.jsx         # Routing & Layout
└── index.css       # Global styles & Design System

Design System & Styling

The UI follows a modern dark-theme aesthetic using CSS Variables defined in index.css:

• --primary: Brand color (Warm Amber/Blue).
• --bg-primary: Deep Slate background.
• Glassmorphism effects via backdrop-filter.
• Responsive grid layouts (.grid-2, .grid-3).

Key Components

• PedigreeTree: horizontal, D3-powered tree with zoom/pan.
• DogForm: Dual-mode (Kennel/External) dog entry with parent selection.
• Toast (components/Toast.jsx): ToastProvider + useToast() — success/error toasts. Never use alert(); call toast.error(err.response?.data?.error || 'fallback').
• ConfirmDialog (components/ConfirmDialog.jsx): ConfirmProvider + useConfirm() — promise-based destructive-action confirmation. Never use window.confirm(); call if (!(await confirm({ title, message }))) return.
• Both providers wrap the app in App.jsx. Page loaders should use Promise.allSettled + an error banner with Retry rather than silently swallowing fetch failures (see Dashboard.jsx, BreedingCalendar.jsx).

---

API & Backend Development

Route Modules (server/routes/)

• /api/dogs: Dog registry and photo uploads (paginated list, parent validation, transactional writes).
• /api/litters: Litter management, puppy linking, and puppy weight/health logs.
• /api/health: OFA clearances, vet records, clearance summaries, document upload.
• /api/genetics: DNA panel results and pairing-risk checks.
• /api/pedigree: Recursive ancestry/descendant tree generation and COI.
• /api/breeding: Heat cycle tracking and whelping projections.
• /api/settings: Kennel-wide configuration.

Environment Variables

Variable	Description	Default
PORT	Server port	3000
DB_PATH	Path to .db file (honored by both migrations and the app)	data/breedr.db
DATA_DIR	Data directory (created on boot)	data/
UPLOAD_PATH	Path to photo/document storage	uploads/
STATIC_PATH	Path to branded static assets	static/

---

Technical History & Design Logs

For deeper technical dives into specific features, refer to the docs/ directory:

• UI Redesign & Color System
• Compact Card Layout Design
• Microchip Field Unique Constraint Fix

---

Last Updated: July 6, 2026