# 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
```text
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](docs/UI_REDESIGN.md)
- [Compact Card Layout Design](docs/COMPACT_CARDS.md)
- [Microchip Field Unique Constraint Fix](docs/MICROCHIP_FIX.md)

---
*Last Updated: July 6, 2026*