docs

2026-03-12 11:26:48 -05:00
parent c3696ba015
commit fa7a336588
8 changed files with 93 additions and 739 deletions
--- 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*