Jason Stedwell
a06ddf0435
Build and Push Docker Image / build (push) Successful in 16s
- README: v0.8.1 highlights, Node 18+ requirement + client install step for manual dev setup, health/genetics features listed, release summary updated - API.md: paginated response shapes for dogs/litters, validation + status-code behavior (400/404), full breeding heat-cycle CRUD, genetics PUT/DELETE, pedigree COI/relations/cancer-lineage endpoints, corrected Litter object - DEVELOPMENT.md: two-layer migration approach documented with schema-drift warning, heat_cycles/cancer_history tables, Toast/ConfirmDialog UI patterns (no alert/window.confirm), full env-var table, auth-deferred decision noted - INSTALL.md: fixed API smoke-test (old /api/health root path doesn't exist), master -> main - ROADMAP: v0.8.1 entry; Phase 4b checkboxes reconciled with what's actually built; Phase 6 progress; pre-deploy prod-DB check added to QA list Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
113 lines
5.5 KiB
Markdown
113 lines
5.5 KiB
Markdown
# DEVELOPMENT.md
|
||
|
||
This document provides technical details and guidelines for developing and maintaining the BREEDR Genealogy Management System.
|
||
|
||
## Tech Stack Overview
|
||
|
||
### Backend
|
||
- **Node.js & Express**: Core API server. Node 18+ required (better-sqlite3 v11 prebuilds cover Node 18–24; Docker runs node:18).
|
||
- **better-sqlite3**: High-performance SQLite driver. Multi-step writes use `db.transaction()`.
|
||
- **Multer**: Multi-part form data handling for photo and document uploads (type + size limits enforced).
|
||
- **Authentication**: Deliberately not implemented — BREEDR is a self-hosted LAN app. Revisit as its own feature if exposure changes (decision: July 2026).
|
||
|
||
### 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.
|
||
|
||
---
|
||
|
||
## Database Architecture
|
||
|
||
### SQLite Implementation
|
||
The database is a single file at `data/breedr.db` by default; both the migration runner and the app honor `DB_PATH`, and the containing directory is created automatically on startup.
|
||
|
||
### "Parents Table" Approach
|
||
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'.
|
||
|
||
**Benefits**: Supports recursive lookups, avoids `ALTER TABLE` complexity for lineage changes, and allows historical mapping of ancestors without full profiles.
|
||
|
||
### Safe Migrations
|
||
BREEDR uses a two-layer synchronization approach, both run at startup (`server/index.js`):
|
||
1. `server/db/migrations.js` — a versioned migration runner for structural rewrites (e.g. moving sire/dam into the `parents` table). Migrations no-op on a fresh/empty database.
|
||
2. `server/db/init.js` — defines the latest table structures (`CREATE TABLE IF NOT EXISTS`) and injects missing columns with safe `ALTER TABLE` guards.
|
||
|
||
> ⚠️ **Keep init.js in sync with the routes.** The schema drifted once (routes wrote columns init.js never defined) and only worked because the live Docker volume carried an older ad-hoc schema — fresh installs were broken. When adding a column a route writes, add it to the `CREATE TABLE` *and* the ALTER-if-missing list. Verify by booting against a deleted/renamed dev DB.
|
||
|
||
### Key Tables
|
||
- `dogs`: Registry for kennel and external dogs.
|
||
- `parents`: Ancestry relationships.
|
||
- `litters`: Produced breeding groups.
|
||
- `heat_cycles`: Female heat cycle tracking (calendar + whelping projections).
|
||
- `health_records`: OFA clearances, vet records, and puppy weight logs.
|
||
- `genetic_tests`: DNA panel results.
|
||
- `cancer_history`: Cancer/longevity lineage records.
|
||
- `settings`: Kennel-wide configuration (single row).
|
||
|
||
---
|
||
|
||
## Frontend Documentation
|
||
|
||
### 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
|
||
```
|
||
|
||
### 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`).
|
||
|
||
### Key Components
|
||
- **PedigreeTree**: horizontal, D3-powered tree with zoom/pan.
|
||
- **DogForm**: Dual-mode (Kennel/External) dog entry with parent selection.
|
||
- **Toast** (`components/Toast.jsx`): `ToastProvider` + `useToast()` — success/error toasts. **Never use `alert()`**; call `toast.error(err.response?.data?.error || 'fallback')`.
|
||
- **ConfirmDialog** (`components/ConfirmDialog.jsx`): `ConfirmProvider` + `useConfirm()` — promise-based destructive-action confirmation. **Never use `window.confirm()`**; call `if (!(await confirm({ title, message }))) return`.
|
||
- Both providers wrap the app in `App.jsx`. Page loaders should use `Promise.allSettled` + an error banner with Retry rather than silently swallowing fetch failures (see `Dashboard.jsx`, `BreedingCalendar.jsx`).
|
||
|
||
---
|
||
|
||
## API & Backend Development
|
||
|
||
### Route Modules (`server/routes/`)
|
||
- `/api/dogs`: Dog registry and photo uploads (paginated list, parent validation, transactional writes).
|
||
- `/api/litters`: Litter management, puppy linking, and puppy weight/health logs.
|
||
- `/api/health`: OFA clearances, vet records, clearance summaries, document upload.
|
||
- `/api/genetics`: DNA panel results and pairing-risk checks.
|
||
- `/api/pedigree`: Recursive ancestry/descendant tree generation and COI.
|
||
- `/api/breeding`: Heat cycle tracking and whelping projections.
|
||
- `/api/settings`: Kennel-wide configuration.
|
||
|
||
### Environment Variables
|
||
| Variable | Description | Default |
|
||
|----------|-------------|---------|
|
||
| `PORT` | Server port | `3000` |
|
||
| `DB_PATH` | Path to .db file (honored by both migrations and the app) | `data/breedr.db` |
|
||
| `DATA_DIR` | Data directory (created on boot) | `data/` |
|
||
| `UPLOAD_PATH`| Path to photo/document storage | `uploads/` |
|
||
| `STATIC_PATH`| Path to branded static assets | `static/` |
|
||
|
||
---
|
||
|
||
## 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: July 6, 2026*
|