Docs: bring all documentation current with v0.8.1
Build and Push Docker Image / build (push) Successful in 16s
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>
This commit is contained in:
Jason Stedwell
+27
-16
@@ -5,10 +5,10 @@ This document provides technical details and guidelines for developing and maint
|
||||
## 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.
|
||||
- **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.
|
||||
@@ -22,7 +22,7 @@ This document provides technical details and guidelines for developing and maint
|
||||
## Database Architecture
|
||||
|
||||
### SQLite Implementation
|
||||
The database is a single file located at `data/breedr.db`. This directory is automatically created on startup.
|
||||
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.
|
||||
@@ -33,17 +33,20 @@ Parent relationships are managed in a dedicated `parents` table rather than colu
|
||||
**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.
|
||||
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.
|
||||
- `health_records`: OFA clearances and vet records.
|
||||
- `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).
|
||||
|
||||
---
|
||||
@@ -70,23 +73,31 @@ The UI follows a modern dark-theme aesthetic using **CSS Variables** defined in
|
||||
### 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.
|
||||
- `/api/litters`: Litter management and puppy linking.
|
||||
- `/api/pedigree`: Recursive ancestry/descendant tree generation.
|
||||
- `/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 | `../data/breedr.db` |
|
||||
| `UPLOAD_PATH`| Path to photo storage| `../uploads` |
|
||||
| `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/` |
|
||||
|
||||
---
|
||||
|
||||
@@ -98,4 +109,4 @@ For deeper technical dives into specific features, refer to the `docs/` director
|
||||
- [Microchip Field Unique Constraint Fix](docs/MICROCHIP_FIX.md)
|
||||
|
||||
---
|
||||
*Last Updated: March 12, 2026*
|
||||
*Last Updated: July 6, 2026*
|
||||
|
||||
Reference in New Issue
Block a user