102 lines
3.4 KiB
Markdown
102 lines
3.4 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.
|
|
- **better-sqlite3**: High-performance SQLite driver.
|
|
- **Multer**: Multi-part form data handling for photo uploads.
|
|
- **Bcrypt & JWT**: (Planned) Authentication and security.
|
|
|
|
### 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 located at `data/breedr.db`. This directory is automatically created 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 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`: 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).
|
|
|
|
---
|
|
|
|
## 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.
|
|
|
|
---
|
|
|
|
## API & Backend Development
|
|
|
|
### 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` |
|
|
| `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*
|