diff --git a/API.md b/API.md index beb5c97..f84f3ae 100644 --- a/API.md +++ b/API.md @@ -1,4 +1,4 @@ -# BREEDR API Documentation (v0.6.1) +# BREEDR API Documentation (v0.8.0) Base URL: `/api` diff --git a/DATABASE.md b/DATABASE.md deleted file mode 100644 index 3f54987..0000000 --- a/DATABASE.md +++ /dev/null @@ -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* diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 7388f19..4ed05f2 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -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* diff --git a/FRONTEND_GUIDE.md b/FRONTEND_GUIDE.md deleted file mode 100644 index 4012ec9..0000000 --- a/FRONTEND_GUIDE.md +++ /dev/null @@ -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. diff --git a/QUICKSTART.md b/QUICKSTART.md deleted file mode 100644 index 75e1801..0000000 --- a/QUICKSTART.md +++ /dev/null @@ -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! 🐶** diff --git a/README.md b/README.md index dd51e0d..5ad538b 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/ROADMAP.md b/ROADMAP.md index 8988faf..9727eda 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,4 +1,4 @@ -# BREEDR Development Roadmap +# BREEDR Development Roadmap (v0.8.0) ## 🚀 Current Status: v0.8.0 (Active Development) diff --git a/docs/VERIFICATION_CHECKLIST.md b/docs/VERIFICATION_CHECKLIST.md deleted file mode 100644 index b8fbd49..0000000 --- a/docs/VERIFICATION_CHECKLIST.md +++ /dev/null @@ -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) \ No newline at end of file