breedr/DEVELOPMENT.md

# DEVELOPMENT.md

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

## Tech Stack Overview

- **Monorepo Structure**:
  - `server/`: Express.js backend.
  - `client/`: React/Vite frontend.
  - `data/`: SQLite database storage.
  - `uploads/`: Uploaded images and documents.
  - `static/`: Static assets for the application.

- **Backend**: Node.js, Express, better-sqlite3, multer, bcrypt, jsonwebtoken.
- **Frontend**: React 18, Vite, React Router 6, Axios, Lucide React, D3 (for pedigree trees).
- **Database**: SQLite (managed with better-sqlite3).

## Getting Started

### Prerequisites
- Node.js (v18+ recommended)
- npm

### Installation
1. Clone the repository.
2. Install root dependencies:
   ```bash
   npm install
   ```
3. Install client dependencies:
   ```bash
   cd client && npm install
   ```

### Development Commands
Run the following from the project root:
- **Run both client and server**: `npm run dev`
- **Run server only**: `npm run server`
- **Run client only**: `npm run client`
- **Initialize Database**: `npm run db:init`
- **Build for production**: `npm run build`

## Database Architecture

### Data Storage
The database is a single SQLite file located at `data/breedr.db`. This directory is automatically created on startup if it doesn't exist.

### Initialization & Schema
- **Initialization**: `server/db/init.js` defines the initial schema and creates tables if they don't exist.
- **Migrations**: `server/db/migrations.js` handles schema updates. Migrations run automatically on server startup.

### "Parents Table" Approach
Instead of storing parent IDs directly in the `dogs` table (which was the old approach), relationships are managed in a dedicated `parents` table:

```sql
CREATE TABLE parents (
  id          INTEGER PRIMARY KEY AUTOINCREMENT,
  dog_id      INTEGER NOT NULL,
  parent_id   INTEGER NOT NULL,
  parent_type TEXT NOT NULL CHECK(parent_type IN ('sire', 'dam')),
  FOREIGN KEY (dog_id)    REFERENCES dogs(id) ON DELETE CASCADE,
  FOREIGN KEY (parent_id) REFERENCES dogs(id) ON DELETE CASCADE,
  UNIQUE(dog_id, parent_type)
);
```

**Key Benefits**:
- Avoids complex `ALTER TABLE` operations when changing pedigree logic.
- Cleanly separates dog attributes from lineage relationships.
- Supports indexing for fast recursive pedigree lookups.

### Key Tables
- **`dogs`**: Core dog data (name, breed, sex, microchip, etc.).
- **`parents`**: Lineage relationships (Sire/Dam).
- **`litters`**: Groups of dogs from a single breeding.
- **`breeding_records`**: Planned or completed breeding events.
- **`health_records`**: OFA results, vaccinations, and other health tests.
- **`genetic_tests`**: DNA panel results.
- **`settings`**: Kennel-wide configurations.

## Backend Development

### API Routes
Routes are modularized in `server/routes/`:
- `/api/dogs`: Dog management.
- `/api/litters`: Litter management.
- `/api/health`: Health record management.
- `/api/genetics`: Genetic testing management.
- `/api/pedigree`: Pedigree tree generation.
- `/api/breeding`: Breeding records.
- `/api/settings`: Application settings.

### File Uploads
Images and documents are stored in `uploads/`. The `multer` middleware handles file processing. File paths are stored in the database as relative URLs (e.g., `/uploads/image.jpg`).

## Frontend Development

### State Management
- **Settings**: Managed globally via `SettingsProvider` in `client/src/hooks/useSettings.jsx`.
- **Component State**: Local `useState` and `useEffect` are preferred for feature-specific data.

### Styling
- CSS Variables are used for theming.
- The UI uses a modern, clean design with Lucide icons.

### Pedigree Trees
The pedigree tree visualization is powered by `react-d3-tree` and D3.js. Logic for building the tree structure is located in `server/routes/pedigree.js` and visualized in the `PedigreeTree` component.

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `PORT` | Server port | `3000` |
| `NODE_ENV` | Environment mode | `development` |
| `DATA_DIR` | Path to DB storage | `../data` |
| `UPLOAD_PATH` | Path to uploads | `../uploads` |
| `STATIC_PATH` | Path to static assets | `../static` |
| `DB_PATH` | Full path to .db file | `../data/breedr.db` |