jason/breedr
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs

Browse Source
This commit is contained in:
jason
2026-03-12 11:26:48 -05:00
parent c3696ba015
commit fa7a336588
8 changed files with 93 additions and 739 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
API.md
View File

@@ -1,4 +1,4 @@
# BREEDR API Documentation (v0.6.1)
# BREEDR API Documentation (v0.8.0)
Base URL: `/api`

136
DATABASE.md
View File

@@ -1,136 +0,0 @@
# BREEDR Database Schema
## Overview
This document describes the database schema for BREEDR. The application uses SQLite via `better-sqlite3`.
**Safe Migrations:** The schema is maintained in `server/db/init.js`. On startup, the application automatically ensures all tables exist and all necessary columns are present using safe `ALTER TABLE` guards.
## Schema Design
### Core Principle: Parents Table Approach
The `dogs` table **does NOT have sire/dam columns**. Parent relationships are stored in a separate `parents` table. This design:
- Keeps the core dog data normalized.
- Allows for flexible parent relationships.
- Supports historical mapping where ancestors might not have full profiles initially.
---
## Tables
### dogs
Core registry for all dogs (both in-kennel and external).
| Column | Type | Description |
|---|---|---|
| id | INTEGER | Primary Key |
| name | TEXT | Dog's call name or registered name |
| registration_number | TEXT | Unique registration (AKC, etc.) |
| breed | TEXT | Breed name |
| sex | TEXT | 'male' or 'female' |
| birth_date | TEXT | Date string |
| color | TEXT | Coat color/markings |
| microchip | TEXT | Identification number |
| litter_id | INTEGER | FK to `litters.id` |
| is_active | INTEGER | 1 = Active in kennel, 0 = Retired/Old |
| is_champion | INTEGER | 1 = Titled champion |
| is_external | INTEGER | 1 = External dog (pedigree only), 0 = Kennel dog |
| chic_number | TEXT | CHIC certification number |
| age_at_death | TEXT | Age if deceased |
| cause_of_death | TEXT | Cause if deceased |
| photo_urls | TEXT | JSON array of photo paths |
| notes | TEXT | General observations |
### parents
Stores sire/dam relationships for every dog.
```sql
CREATE TABLE parents (
id INTEGER PRIMARY KEY AUTOINCREMENT,
dog_id INTEGER NOT NULL, -- The puppy/child
parent_id INTEGER NOT NULL, -- The parent dog
parent_type TEXT NOT NULL CHECK(parent_type IN ('sire', 'dam')),
FOREIGN KEY (dog_id) REFERENCES dogs(id),
FOREIGN KEY (parent_id) REFERENCES dogs(id),
UNIQUE(dog_id, parent_type)
);
```
### breeding_records
Tracks mating attempts/plans.
| Column | Type | Description |
|---|---|---|
| sire_id | INTEGER | FK to `dogs.id` |
| dam_id | INTEGER | FK to `dogs.id` |
| breeding_date | TEXT | Date of mating |
| due_date | TEXT | Estimated whelp date |
| conception_method | TEXT | 'natural', 'ai', 'frozen', 'surgical' |
### litters
Tracks successfully produced litters.
```sql
CREATE TABLE litters (
id INTEGER PRIMARY KEY AUTOINCREMENT,
breeding_id INTEGER, -- Optional link to breeding_record
sire_id INTEGER NOT NULL,
dam_id INTEGER NOT NULL,
whelp_date TEXT,
total_count INTEGER DEFAULT 0,
male_count INTEGER DEFAULT 0,
female_count INTEGER DEFAULT 0,
stillborn_count INTEGER DEFAULT 0,
notes TEXT,
FOREIGN KEY (breeding_id) REFERENCES breeding_records(id),
FOREIGN KEY (sire_id) REFERENCES dogs(id),
FOREIGN KEY (dam_id) REFERENCES dogs(id)
);
```
### health_records (OFA & General)
Tracks medical tests and certifications (Hips, Elbows, Heart, Eyes, etc).
| Column | Type | Description |
|---|---|---|
| record_type | TEXT | 'test', 'vaccination', 'exam', 'treatment', 'certification' |
| test_type | TEXT | 'hip_ofa', 'eye_caer', etc. |
| ofa_result | TEXT | Official rating (Excellent, Good, etc.) |
| ofa_number | TEXT | Certification number |
| expires_at | TEXT | Expiry for annual tests |
| document_url | TEXT | Link to PDF or image scan |
### genetic_tests
DNA panel results (Embark, etc).
```sql
CREATE TABLE genetic_tests (
id INTEGER PRIMARY KEY AUTOINCREMENT,
dog_id INTEGER NOT NULL,
test_provider TEXT, -- Embark, PawPrint, etc.
marker TEXT NOT NULL, -- PRA1, ICH1, etc.
result TEXT NOT NULL CHECK(result IN ('clear', 'carrier', 'affected', 'not_tested')),
FOREIGN KEY (dog_id) REFERENCES dogs(id)
);
```
### heat_cycles
Female heat cycle tracking.
### settings
Global kennel configuration (Single-row table).
- `kennel_name`, `kennel_tagline`, `kennel_address`, `owner_name`, etc.
---
## Migration Policy
BREEDR uses a **Migration-Free** sync approach:
1. `init.js` defines the latest `CREATE TABLE` statements.
2. An `ADD COLUMN` loop checks for existing columns.
3. If a column is missing, it is injected via `ALTER TABLE`.
4. This ensures users can pull latest code and restart without losing data.
---
*Last Updated: March 12, 2026*

161
DEVELOPMENT.md
View File

@@ -4,115 +4,98 @@ This document provides technical details and guidelines for developing and maint
## 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**: Core API server.
- **better-sqlite3**: High-performance SQLite driver.
- **Multer**: Multi-part form data handling for photo uploads.
- **Bcrypt & JWT**: (Planned) Authentication and security.
- **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).
### 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.
## 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.
### SQLite Implementation
The database is a single file located at `data/breedr.db`. This directory is automatically created on 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:
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'.
```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)
);
```
**Benefits**: Supports recursive lookups, avoids `ALTER TABLE` complexity for lineage changes, and allows historical mapping of ancestors without full profiles.
**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.
### 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`**: 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.
- `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).
## 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.
## Frontend Documentation
### 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`).
### 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
```
## Frontend Development
### 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`).
### 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.
### Key Components
- **PedigreeTree**: horizontal, D3-powered tree with zoom/pan.
- **DogForm**: Dual-mode (Kennel/External) dog entry with parent selection.
### 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.
## API & Backend Development
## Environment Variables
### 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` |
| `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` |
| `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*

105
FRONTEND_GUIDE.md
View File

@@ -1,105 +0,0 @@
# Frontend Guide
This document provides an overview of the frontend architecture, technologies, and patterns used in the BREEDR application.
## Tech Stack
- **Framework**: [React](https://reactjs.org/) (bootstrapped with [Vite](https://vitejs.dev/))
- **Routing**: [react-router-dom](https://reactrouter.com/)
- **Icons**: [lucide-react](https://lucide.dev/)
- **Data Fetching**: [axios](https://axios-http.com/)
- **Visualizations**: [react-d3-tree](https://github.com/bkrem/react-d3-tree) (for pedigree rendering)
- **Styling**: Standard CSS with CSS Variables (Custom properties)
## Project Structure
```text
client/src/
├── components/ # Reusable UI components
├── hooks/ # Custom hooks and context providers
├── pages/ # Page-level components (routes)
├── utils/ # Helper functions and utilities
├── App.jsx # Root component with routing
├── App.css # Layout-specific styles
├── index.css # Global styles and CSS variables
└── main.jsx # Application entry point
```
## Routing and Layout
The application uses `react-router-dom` for navigation. The primary layout and routes are defined in `client/src/App.jsx`.
- **Navbar**: Contains links to Dashboard, Dogs, Litters, Breeding, Pairing, and Settings.
- **Main Content**: Renders the matched route element within a `.main-content` container.
### Key Routes
- `/`: Dashboard
- `/dogs`: Dog List
- `/dogs/:id`: Dog Detail
- `/pedigree/:id`: Pedigree View
- `/litters`: Litter List
- `/breeding`: Breeding Calendar
- `/pairing`: Pairing Simulator
- `/settings`: Settings Page
## State Management
### Settings Context (`useSettings`)
Global application settings (like kennel name) are managed via a React Context.
- **Provider**: `SettingsProvider` in `client/src/hooks/useSettings.jsx`.
- **Usage**:
```javascript
import { useSettings } from '../hooks/useSettings';
const { settings, saveSettings, loading } = useSettings();
```
### Local State
Most page-specific data is managed using standard `useState` and `useEffect` hooks, fetching data via `axios`.
## Styling Conventions
The application follows a dark-theme aesthetic using CSS variables for consistency.
### CSS Variables (`client/src/index.css`)
Key variables include:
- `--primary`: Main brand color (warm amber/copper).
- `--bg-primary`: Primary background.
- `--text-primary`: Primary text color.
- `--border`: Standard border color.
- `--radius`: Default border radius.
### Reusable UI Classes
- `.btn`, `.btn-primary`, `.btn-secondary`: Standard button styles.
- `.card`: Container for grouped content.
- `.grid`, `.grid-2`, `.grid-3`: Responsive grid layouts.
- `.modal-overlay`, `.modal-content`: Standard modal structure.
## Key Components
### PedigreeTree (`client/src/components/PedigreeTree.jsx`)
Uses `react-d3-tree` to render a horizontal, step-based pedigree.
- **Props**: `dogId`, `pedigreeData`, `coi`.
- **Features**: Custom node rendering (differentiating by sex and champion status), zoom/pan controls, and COI display.
### DogForm (`client/src/components/DogForm.jsx`)
Handles both creation and editing of dog records.
- **Logic**: Manages internal/external dog states, parent selection (manual or linked to litter), and champion status.
- **Validation**: Basic required field validation; errors are displayed at the top of the form.
## Data Fetching Patterns
Standard `axios` requests are used:
```javascript
const fetchData = async () => {
try {
const res = await axios.get('/api/endpoint');
setData(res.data);
} catch (err) {
setError(err.response?.data?.error || 'Error message');
}
};
```
## Icons
Use `lucide-react` for all icons to ensure consistency across the UI.

81
QUICKSTART.md
View File

@@ -1,81 +0,0 @@
# BREEDR Quick Start Guide (v0.8.0)
Welcome to BREEDR! This guide will help you get up and running with the most powerful kennel management and pedigree mapping features.
---
## 🚀 Installation & Setup
### 1. The Easy Way (Docker)
Ensure you have Docker and Docker-Compose installed.
```bash
git clone https://git.alwisp.com/jason/breedr.git
cd breedr
docker-compose up -d --build
```
Open your browser to `http://localhost:3000`.
### 2. Manual Development Setup
```bash
# 1. Install project dependencies
npm install
# 2. Start the dev environment (Frontend @ 5173, Backend @ 3000)
npm run dev
```
> **Note:** The database initializes automatically on first boot. No manual migrations are required.
---
## 🐕 Managing Your Kennel
### Adding or Importing Dogs
1. Go to the **Dogs** page.
2. Click **Add New Dog**.
3. Fill in the core details (Name, Registration, Breed, Sex).
4. **Pedigree Mapping**: You can select a Sire and Dam from your existing dogs.
5. **External Dogs**: Check "External Dog" if you are adding an ancestor that isn't in your kennel.
### Champion Tracking
- Use the **Champion Toggle** in the Add/Edit form to mark titled dogs.
- They will appear with a `✪` star in dropdowns and display a gold badge on their profile.
- Their offspring will automatically display the "Champion Bloodline" badge.
---
## 🧬 Breeding Tools
### 1. Pedigree Visualization
- Click **Pedigree** on any dog detail page.
- **Ancestors View**: Default interactive 5-generation tree.
- **Descendants View**: Toggle the switch in the header to see the "Reverse Pedigree" (offspring lineage).
- Use the mouse wheel or on-screen buttons to zoom and pan.
### 2. Trial Pairing Simulator
- Go to the **Pairing Simulator** via the flask icon in the navbar.
- Select a potential Sire and Dam.
- **COI Calculation**: Instantly see the Wright's Inbreeding Coefficient.
- **Ancestry Check**: The system flags common ancestors and provides a risk badge (Low < 5%, Moderate 5-10%, High > 10%).
### 3. Heat Cycle Calendar
- Use the **Calendar** to track female heat cycles.
- **Phase Colors**: Automatically segments cycles into Proestrus, Optimal, Late, and Diestrus.
- **Projected Whelping**: Log a breeding date to see a indigo "Whelping Window" and expected due dates directly on the main calendar grid.
---
## ⚙️ Kennel Customization
- Visit the **Settings** page.
- Configure your Kennel Name, Tagline, Address, and Contact info.
- This information updates your site branding and navbar automatically.
---
## ❓ Troubleshooting
- **COI shows 0.00%?**: Ensure you have both parents mapped and that they have shared ancestors.
- **Image not loading?**: Ensure `br-logo.png` is in the `static/` folder for branding.
- **Database "No such column"?**: Simply restart the app; the auto-init logic will fix the schema.
---
**Happy Breeding! 🐶**

41
README.md
View File

@@ -13,7 +13,7 @@ A reactive, interactive dog breeding genealogy mapping system for professional k
## 🚀 Quick Start
### Docker Deployment (Recommended)
### 1. Docker Deployment (Recommended)
```bash
git clone https://git.alwisp.com/jason/breedr.git
cd breedr
@@ -21,36 +21,33 @@ docker-compose up -d --build
```
Access at: `http://localhost:3000`
### Local Development
### 2. Manual Development Setup
```bash
npm install
npm run dev
```
> **Note:** The database initializes automatically on first boot. No manual migrations are required.
---
## ✅ Core Features
## 🐕 Managing Your Kennel
### 🐕 Dog & Litter Management
- **Registry**: Complete CRUD operations for your kennel.
- **Photo Management**: Multiple high-quality photos per dog.
- **Litter Tracking**: Link puppies to breeding records automatically.
- **Champion Tracking**: Badge titled dogs; titles pass "Champion Bloodline" status to offspring.
- **Adding Dogs**: Go to the **Dogs** page, click **Add New Dog**. You can mark dogs as **External** if they aren't in your kennel but are needed for pedigree mapping.
- **Champion Tracking**: Toggle the **Champion** status to title dogs. Offspring will automatically display the "Champion Bloodline" badge.
- **Photo Management**: Multiple high-quality photos per dog with a compact gallery view.
- **Litter Tracking**: Link puppies to breeding records automatically to track weight and health from birth.
### 🧬 Breeding & Genetics
- **Interactive Pedigree**: Multi-generational trees with zoom/pan and reverse (descendant) toggles.
- **Trial Pairing**: Simulator with **COI calculation**, common ancestor identification, and risk badges.
- **Heat Cycles**: Full calendar with phase tracking, breeding windows, and **projected whelping alerts**.
## 🧬 Breeding & Genetics
### ⚙️ Kennel Configuration
- **Settings System**: Centralized management for kennel name, branding, and contact info.
- **Branding**: Custom logo support and professional dark-themed UI with glassmorphism.
- **Interactive Pedigree**: 5-generation trees with zoom/pan. Toggle the **Reverse Pedigree** switch to see descendant lineage.
- **Trial Pairing Simulator**: Calculate Wright's Inbreeding Coefficient (COI) instantly. Identifies common ancestors and providing risk badges (Low/Moderate/High).
- **Heat Cycles**: Track female cycles on the calendar. Includes **projected whelping alerts** (indigo windows) and expected due dates.
---
## 🛠️ Technology Stack
- **Frontend**: React 18, Vite, Lucide Icons
- **Visualization**: React-D3-Tree
- **Visualization**: React-D3-Tree, D3.js
- **Backend**: Node.js, Express.js
- **Database**: SQLite (Zero-config, safe `ALTER TABLE` migrations)
- **Deployment**: Multi-stage Docker
@@ -65,7 +62,7 @@ breedr/
├── static/ # Branded assets (logos, etc.)
├── data/ # SQLite database storage (mapped in Docker)
├── uploads/ # Dog photo storage (mapped in Docker)
└── ROADMAP.md # Detailed development history & planned features
└── docs/ # Technical documentation and design history
```
---
@@ -76,15 +73,15 @@ breedr/
- **v0.7.0** (In Progress): Health & Genetics (OFA clearances, DNA panels).
- **v0.6.1**: COI calculation fix for direct parent×offspring relations.
- **v0.6.0**: Champion status tracking & Kennel settings API.
- **v0.5.1**: Projected whelping windows and calendar identifiers.
- **v0.5.0**: Breeding tools, pairing simulator, and heat cycle calendar.
---
## ❓ Troubleshooting
- **COI shows 0.00%?**: Ensure you are on v0.6.1+ to fix direct-relation pathing.
- **Missing Columns?**: Restart the server; safe migration guards add columns automatically.
- **COI shows 0.00%?**: Ensure both parents are mapped and have shared ancestors.
- **Missing Columns?**: Restart the server; auto-init guards add columns automatically.
- **Logo not appearing?**: Place `br-logo.png` in the `static/` directory.
---
**Full Documentation & Roadmap**: [ROADMAP.md](ROADMAP.md) | [DATABASE.md](DATABASE.md)
**Full Documentation**:
[Installation Guide](INSTALL.md) | [Development & Architecture](DEVELOPMENT.md) | [API Reference](API.md) | [Roadmap](ROADMAP.md)

2
ROADMAP.md
View File

@@ -1,4 +1,4 @@
# BREEDR Development Roadmap
# BREEDR Development Roadmap (v0.8.0)
## 🚀 Current Status: v0.8.0 (Active Development)

304
docs/VERIFICATION_CHECKLIST.md
View File

@@ -1,304 +0,0 @@
# BREEDR Verification Checklist
## Microchip Field Fix Verification
### ✅ Schema Files (All Correct)
#### 1. Database Schema: `server/db/init.js`
- [x] **Line 29:** `microchip TEXT,` (no UNIQUE constraint)
- [x] **Lines 38-43:** Partial unique index created
```sql
CREATE UNIQUE INDEX IF NOT EXISTS idx_dogs_microchip
ON dogs(microchip)
WHERE microchip IS NOT NULL
```
**Status:** ✅ Correct for future installations
---
#### 2. UI Form: `client/src/components/DogForm.jsx`
- [x] **Line 150:** Microchip input has NO `required` attribute
- [x] Label shows "Microchip Number" (no asterisk)
- [x] Field is truly optional in the UI
**Status:** ✅ Correct - users can leave microchip blank
---
#### 3. Migration Script: `server/db/migrate_microchip.js`
- [x] Exists and is executable
- [x] Safely migrates existing databases
- [x] Idempotent (can run multiple times)
- [x] Preserves all data during migration
**Status:** ✅ Available for existing installations
---
#### 4. Migration Helper: `migrate-now.sh`
- [x] Shell script for easy execution
- [x] Checks if container is running
- [x] Runs migration inside container
- [x] Restarts container after migration
**Status:** ✅ User-friendly migration tool
---
#### 5. Documentation: `docs/MICROCHIP_FIX.md`
- [x] Problem explanation
- [x] Solution details
- [x] Migration instructions (3 options)
- [x] Verification tests
- [x] Troubleshooting guide
**Status:** ✅ Complete documentation
---
#### 6. README: `README.md`
- [x] Migration notice at top
- [x] Link to detailed documentation
- [x] Upgrade instructions included
- [x] Recent updates section added
**Status:** ✅ Users will see migration notice
---
## For Future Installations
### Fresh Install (No Migration Needed)
When a user does a **fresh install** (no existing database):
1. Container starts
2. `server/db/init.js` runs automatically
3. Database created with **correct schema**
4. Microchip field is **optional from the start**
5. No migration required ✅
### Existing Installation (Migration Required)
When a user **upgrades** from an old version:
1. Pull latest code
2. Rebuild Docker image
3. Start container
4. **Must run migration:** `docker exec -it breedr node server/db/migrate_microchip.js`
5. Restart container
6. Microchip field now optional ✅
---
## Testing Checklist
### Test 1: Add Dog Without Microchip
```bash
curl -X POST http://localhost:3000/api/dogs \
-H "Content-Type: application/json" \
-d '{"name":"TestDog1","breed":"Lab","sex":"male"}'
```
**Expected:** ✅ Success (201 Created)
### Test 2: Add Multiple Dogs Without Microchips
```bash
curl -X POST http://localhost:3000/api/dogs \
-H "Content-Type: application/json" \
-d '{"name":"TestDog2","breed":"Lab","sex":"female"}'
```
**Expected:** ✅ Success (multiple NULL values allowed)
### Test 3: Add Dog With Microchip
```bash
curl -X POST http://localhost:3000/api/dogs \
-H "Content-Type: application/json" \
-d '{"name":"TestDog3","breed":"Lab","sex":"male","microchip":"123456789"}'
```
**Expected:** ✅ Success
### Test 4: Duplicate Microchip Should Fail
```bash
curl -X POST http://localhost:3000/api/dogs \
-H "Content-Type: application/json" \
-d '{"name":"TestDog4","breed":"Lab","sex":"female","microchip":"123456789"}'
```
**Expected:** ❌ Error (UNIQUE constraint still enforced for non-NULL)
---
## Database Verification
### Check Schema Directly
```bash
# Enter container
docker exec -it breedr sh
# Open SQLite CLI
sqlite3 /app/data/breedr.db
# Check table schema
.schema dogs
# Should show:
# microchip TEXT, (no UNIQUE)
# Check indexes
.indexes dogs
# Should show:
# idx_dogs_microchip (partial index)
# Verify partial index
SELECT sql FROM sqlite_master
WHERE type='index' AND name='idx_dogs_microchip';
# Should show:
# CREATE UNIQUE INDEX idx_dogs_microchip
# ON dogs(microchip) WHERE microchip IS NOT NULL
```
---
## Rollback Plan
If something goes wrong:
### Option A: Restore Backup
```bash
docker stop breedr
cp /mnt/user/appdata/breedr/breedr.db.backup \
/mnt/user/appdata/breedr/breedr.db
docker start breedr
```
### Option B: Re-run Migration
```bash
docker exec -it breedr node server/db/migrate_microchip.js
docker restart breedr
```
### Option C: Fresh Database (Data Loss)
```bash
docker stop breedr
rm /mnt/user/appdata/breedr/breedr.db
docker start breedr
```
---
## Deployment Verification
After deploying to production:
- [ ] Check container logs for schema initialization
- [ ] Verify database schema with SQLite CLI
- [ ] Test adding dog without microchip via UI
- [ ] Test adding dog with microchip via UI
- [ ] Confirm no UNIQUE constraint errors
- [ ] Verify partial index exists
- [ ] Test duplicate microchip still fails
---
## Common Issues
### Issue: Still Getting UNIQUE Constraint Error
**Cause:** Migration not run on existing database
**Solution:**
```bash
docker exec -it breedr node server/db/migrate_microchip.js
docker restart breedr
```
### Issue: Migration Script Not Found
**Cause:** Old code still in container
**Solution:**
```bash
cd /mnt/user/appdata/breedr-build
git pull
docker build -t breedr:latest .
docker stop breedr && docker rm breedr
# Recreate container with new image
```
### Issue: Microchip Required in UI
**Cause:** Browser cached old JavaScript
**Solution:**
- Hard refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)
- Clear browser cache
- Try incognito/private window
---
## File Manifest
### Core Files (Must Be Present)
- ✅ `server/db/init.js` - Database schema (corrected)
- ✅ `server/db/migrate_microchip.js` - Migration script
- ✅ `client/src/components/DogForm.jsx` - UI form (microchip optional)
- ✅ `migrate-now.sh` - Helper script
- ✅ `docs/MICROCHIP_FIX.md` - Detailed documentation
- ✅ `docs/VERIFICATION_CHECKLIST.md` - This file
- ✅ `README.md` - Updated with migration notice
### Validation Commands
```bash
# Check all files exist
ls -la server/db/init.js
ls -la server/db/migrate_microchip.js
ls -la client/src/components/DogForm.jsx
ls -la migrate-now.sh
ls -la docs/MICROCHIP_FIX.md
ls -la docs/VERIFICATION_CHECKLIST.md
# Verify microchip field in init.js
grep -n "microchip TEXT" server/db/init.js
# Should show line 29 with NO UNIQUE
# Verify partial index
grep -A2 "idx_dogs_microchip" server/db/init.js
# Should show WHERE clause
# Verify form has no required
grep -n 'name="microchip"' client/src/components/DogForm.jsx
# Should NOT have required attribute
```
---
## Sign-Off
### Pre-Deployment Checklist
- [x] Schema file correct (no UNIQUE on microchip)
- [x] Partial index created (WHERE IS NOT NULL)
- [x] UI form allows empty microchip
- [x] Migration script tested
- [x] Documentation complete
- [x] README updated
- [x] Tests passing
### Post-Deployment Checklist
- [ ] Container started successfully
- [ ] Schema verified in database
- [ ] UI allows empty microchip
- [ ] Multiple NULL values work
- [ ] Unique constraint still enforced for non-NULL
- [ ] No errors in logs
---
**Last Verified:** March 8, 2026
**Status:** ✅ All files correct for future installations
**Migration Required:** Only for existing databases (one-time)