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.
- **better-sqlite3**: High-performance SQLite driver.
- **Multer**: Multi-part form data handling for photo uploads.
- **Bcrypt & JWT**: (Planned) Authentication and security.

### 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 located at `data/breedr.db`. This directory is automatically created 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 use a migration-free synchronization approach:
1. `server/db/init.js` defines the latest table structures.
2. Safe `ALTER TABLE` guards inject missing columns on startup.
3. This ensures data persistence across updates without manual migration scripts.

### Key Tables
- `dogs`: Registry for kennel and external dogs.
- `parents`: Ancestry relationships.
- `litters`: Produced breeding groups.
- `health_records`: OFA clearances and vet records.
- `genetic_tests`: DNA panel results.
- `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.

---

## API & Backend Development

### Route Modules (`server/routes/`)
- `/api/dogs`: Dog registry and photo uploads.
- `/api/litters`: Litter management and puppy linking.
- `/api/pedigree`: Recursive ancestry/descendant tree generation.
- `/api/breeding`: Heat cycle tracking and whelping projections.

### Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `PORT` | Server port | `3000` |
| `DB_PATH` | Path to .db file | `../data/breedr.db` |
| `UPLOAD_PATH`| Path to photo storage| `../uploads` |

---

## 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: March 12, 2026*