2daccf7d8c
Scan the code, build the .md files you need to make it easier for the agent to preform modifications and fix bugs
119 lines
4.2 KiB
Markdown
119 lines
4.2 KiB
Markdown
# 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:
|
|
```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.
|
|
|
|
### "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:
|
|
|
|
```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)
|
|
);
|
|
```
|
|
|
|
**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` |
|