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:

   npm install
   

3. Install client dependencies:

   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:

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