breedr/DATABASE.md

# BREEDR Database Schema

## Overview

This document describes the clean database schema for BREEDR. **NO migrations** - fresh installs create the correct schema automatically.

## Schema Design

### Core Principle: Parents Table Approach

The `dogs` table **does NOT have sire/dam columns**. Parent relationships are stored in the separate `parents` table. This design:
- Keeps the schema clean and normalized
- Allows flexible parent relationships
- Supports future extensions (multiple sires, surrogates, etc.)

## Tables

### dogs

Core registry for all dogs.

```sql
CREATE TABLE dogs (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  name TEXT NOT NULL,
  registration_number TEXT UNIQUE,
  breed TEXT NOT NULL,
  sex TEXT NOT NULL CHECK(sex IN ('male', 'female')),
  birth_date DATE,
  color TEXT,
  microchip TEXT,
  photo_urls TEXT,  -- JSON array
  notes TEXT,
  litter_id INTEGER,  -- Links to litters table
  is_active INTEGER DEFAULT 1,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (litter_id) REFERENCES litters(id) ON DELETE SET NULL
);
```

**Important:** NO `sire_id` or `dam_id` columns!

### parents

Stores sire/dam relationships.

```sql
CREATE TABLE parents (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  dog_id INTEGER NOT NULL,  -- The puppy
  parent_id INTEGER NOT NULL,  -- The parent
  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)  -- One sire, one dam per dog
);
```

### litters

Breeding records and litter tracking.

```sql
CREATE TABLE litters (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  sire_id INTEGER NOT NULL,
  dam_id INTEGER NOT NULL,
  breeding_date DATE NOT NULL,
  whelping_date DATE,
  puppy_count INTEGER DEFAULT 0,
  notes TEXT,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (sire_id) REFERENCES dogs(id) ON DELETE CASCADE,
  FOREIGN KEY (dam_id) REFERENCES dogs(id) ON DELETE CASCADE
);
```

### health_records

Health tests, vaccinations, exams, treatments.

```sql
CREATE TABLE health_records (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  dog_id INTEGER NOT NULL,
  record_type TEXT NOT NULL CHECK(record_type IN ('test', 'vaccination', 'exam', 'treatment', 'certification')),
  test_name TEXT,
  test_date DATE NOT NULL,
  result TEXT,
  document_url TEXT,
  notes TEXT,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (dog_id) REFERENCES dogs(id) ON DELETE CASCADE
);
```

### heat_cycles

Female heat cycle tracking for breeding timing.

```sql
CREATE TABLE heat_cycles (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  dog_id INTEGER NOT NULL,
  start_date DATE NOT NULL,
  end_date DATE,
  progesterone_peak_date DATE,
  breeding_date DATE,
  breeding_successful INTEGER DEFAULT 0,
  notes TEXT,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (dog_id) REFERENCES dogs(id) ON DELETE CASCADE
);
```

### traits

Genetic trait tracking and inheritance.

```sql
CREATE TABLE traits (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  dog_id INTEGER NOT NULL,
  trait_category TEXT NOT NULL,
  trait_name TEXT NOT NULL,
  trait_value TEXT NOT NULL,
  inherited_from INTEGER,  -- Parent dog ID
  notes TEXT,
  FOREIGN KEY (dog_id) REFERENCES dogs(id) ON DELETE CASCADE,
  FOREIGN KEY (inherited_from) REFERENCES dogs(id) ON DELETE SET NULL
);
```

## API Usage

### Creating a Dog with Parents

```javascript
POST /api/dogs
{
  "name": "Puppy Name",
  "breed": "Breed Name",
  "sex": "male",
  "sire_id": 5,  // Parent male dog ID
  "dam_id": 8,   // Parent female dog ID
  "litter_id": 2  // Optional: link to litter
}
```

The API route automatically:
1. Inserts the dog into `dogs` table (without sire/dam columns)
2. Creates entries in `parents` table linking to sire and dam

### Querying Parents

```sql
-- Get a dog's parents
SELECT p.parent_type, d.* 
FROM parents p 
JOIN dogs d ON p.parent_id = d.id 
WHERE p.dog_id = ?;

-- Get a dog's offspring
SELECT d.* 
FROM dogs d
JOIN parents p ON d.id = p.dog_id
WHERE p.parent_id = ?;
```

## Fresh Install

For a fresh install:

1. **Delete the old database** (if upgrading):
   ```bash
   rm data/breedr.db
   ```

2. **Start the server** - it will create the correct schema automatically:
   ```bash
   npm run dev
   ```

3. **Verify the schema**:
   ```bash
   sqlite3 data/breedr.db ".schema dogs"
   ```
   
   You should see `litter_id` but **NO** `sire_id` or `dam_id` columns.

## Troubleshooting

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

**Solution:** Your database has an old schema. Delete it and let the app recreate it:

```bash
rm data/breedr.db
npm run dev
```

### Parent relationships not saving

Check server logs. You should see:
```
✓ Dog inserted with ID: 123
  Adding sire relationship: dog 123 -> sire 5
  ✓ Sire relationship added
  Adding dam relationship: dog 123 -> dam 8
  ✓ Dam relationship added
```

If relationships aren't being created, check that `sire_id` and `dam_id` are being sent in the API request.

## Database Files

- `server/db/init.js` - Creates clean schema, no migrations
- `server/routes/dogs.js` - Handles parent relationships via `parents` table
- `server/index.js` - Initializes database on startup

**NO MIGRATIONS!** The init file is the source of truth.