jason/breedr
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

INIT (zenflow 9c6862b8)

Browse Source 
Scan the code, build the .md files you need to make it easier for the agent to preform modifications and fix bugs
This commit is contained in:
Zenflow
2026-03-11 09:51:35 -05:00
parent 5c6068364b
commit 2daccf7d8c
6 changed files with 644 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

87
.zenflow/tasks/init-9c68/plan.md Normal file
View File

@@ -0,0 +1,87 @@
# Full SDD workflow
## Configuration
- **Artifacts Path**: {@artifacts_path} → `.zenflow/tasks/{task_id}`
---
## Agent Instructions
If you are blocked and need user clarification, mark the current step with `[!]` in plan.md before stopping.
---
## Workflow Steps
### [x] Step: Requirements
<!-- chat-id: c41b4352-a09d-4280-9aa2-cf29378edb68 -->
Create a Product Requirements Document (PRD) based on the feature description.
1. Review existing codebase to understand current architecture and patterns
2. Analyze the feature definition and identify unclear aspects
3. Ask the user for clarifications on aspects that significantly impact scope or user experience
4. Make reasonable decisions for minor details based on context and conventions
5. If user can't clarify, make a decision, state the assumption, and continue
Save the PRD to `{@artifacts_path}/requirements.md`.
### [x] Step: Technical Specification
<!-- chat-id: c8a2d821-c232-4b10-a4b9-471df9e53543 -->
Create a technical specification based on the PRD in `{@artifacts_path}/requirements.md`.
1. Review existing codebase architecture and identify reusable components
2. Define the implementation approach
Save to `{@artifacts_path}/spec.md` with:
- Technical context (language, dependencies)
- Implementation approach referencing existing code patterns
- Source code structure changes
- Data model / API / interface changes
- Delivery phases (incremental, testable milestones)
- Verification approach using project lint/test commands
### [x] Step: Planning
<!-- chat-id: 5128cbb3-0529-47f2-a7ac-9a978ea72267 -->
Create a detailed implementation plan based on `{@artifacts_path}/spec.md`.
1. Break down the work into concrete tasks
2. Each task should reference relevant contracts and include verification steps
3. Replace the Implementation step below with the planned tasks
Rule of thumb for step size: each step should represent a coherent unit of work (e.g., implement a component, add an API endpoint). Avoid steps that are too granular (single function) or too broad (entire feature).
Important: unit tests must be part of each implementation task, not separate tasks. Each task should implement the code and its tests together, if relevant.
If the feature is trivial and doesn't warrant full specification, update this workflow to remove unnecessary steps and explain the reasoning to the user.
Save to `{@artifacts_path}/plan.md`.
### [x] Phase 1: Create DEVELOPMENT.md
<!-- chat-id: 0da2c64e-4b20-423d-9049-46fc0467eaec -->
1. Research tech stack, monorepo structure, and database schemas in `server/db/`.
2. Document the "Parents Table" approach and database initialization/migration.
3. Add setup and development commands.
4. Verify correctness against `server/db/init.js` and `package.json`.
### [x] Phase 2: Create API.md
<!-- chat-id: bde368a7-164c-419e-b4b9-582e6ced4a45 -->
1. Research all routes in `server/routes/` for endpoints, methods, parameters, and responses.
2. Document endpoint groups: Dogs, Litters, Health, Genetics, Breeding, and Settings.
3. Provide JSON schema examples for key data models (Dog, Litter, etc.).
4. Verify endpoints against route handlers in `server/routes/`.
### [x] Phase 3: Create FRONTEND_GUIDE.md
<!-- chat-id: f0c53f46-3014-4030-9433-3df4d730fde7 -->
1. Research React patterns, hooks (`useSettings`), and `PedigreeTree` logic.
2. Document routing, state management, and key reusable components (`DogForm`, `PedigreeTree`, etc.).
3. Explain styling conventions and theme implementation using CSS variables.
4. Verify patterns against `client/src/App.jsx`, `client/src/hooks/`, and `client/src/components/`.
### [x] Phase 4: Final Review and Verification
<!-- chat-id: b87b4e6a-5d6a-4ad2-91dc-70916b830845 -->
1. Cross-reference all new documentation files with the current codebase (v0.6.1).
2. Ensure consistent formatting and clarity across all three files.
3. Verify that an agent can understand how to implement a new feature using only these documents.

44
.zenflow/tasks/init-9c68/requirements.md Normal file
View File

@@ -0,0 +1,44 @@
# Product Requirements Document (PRD) - INIT (Codebase Documentation)
## 1. Goal
The primary goal of this task is to perform a comprehensive scan of the Breedr codebase and create essential developer-focused documentation (`.md` files). This documentation will streamline the onboarding of new agents or developers and simplify the process of implementing new features and fixing bugs.
## 2. Target Audience
- AI Agents performing code modifications.
- Human developers contributing to the project.
## 3. Scope of Documentation
### 3.1 DEVELOPMENT.md (Architecture & General Guide)
This document will serve as the entry point for understanding the Breedr system.
- **Tech Stack Overview**: React, Express, SQLite (better-sqlite3).
- **Architecture**: Monorepo structure (`client/`, `server/`), data flow, and core principles.
- **Database System**: Detailed explanation of the "Parents Table" approach vs. traditional `sire_id`/`dam_id` columns, migration strategies, and schema initialization.
- **Project Structure**: High-level explanation of key directories and files.
- **Development Workflow**: How to run the app locally, common commands, and testing procedures (if any).
- **Coding Standards**: Patterns for backend routes and frontend components.
### 3.2 API.md (REST API Documentation)
A comprehensive list of all backend API endpoints.
- **Endpoint Definitions**: URL, method, and purpose.
- **Request Parameters**: Headers, query params, and body schemas.
- **Response Format**: Expected JSON structure and status codes.
- **Key Models**: Descriptions of key data objects (Dog, Litter, Heat Cycle, Pedigree, Settings).
### 3.3 FRONTEND_GUIDE.md (UI/UX & React Patterns)
A guide focusing on the client-side implementation.
- **Context & Hooks**: Documentation of `useSettings`, `SettingsProvider`, and any other shared state mechanisms.
- **Component Patterns**: Key reusable components (`DogForm`, `PedigreeTree`, etc.).
- **Styling**: Use of CSS custom properties (theming) and global styles.
- **Pedigree Visualization**: How `react-d3-tree` is integrated and used for genealogy mapping.
- **Routing**: Client-side navigation structure using `react-router-dom`.
## 4. Non-Functional Requirements
- **Consistency**: Documentation must match the current state (v0.6.1) of the codebase.
- **Clarity**: Use clear, concise language and code examples where appropriate.
- **Maintainability**: Organize documents so they are easy to update when new features are added.
## 5. Success Criteria
- The three proposed documentation files (`DEVELOPMENT.md`, `API.md`, `FRONTEND_GUIDE.md`) are created in the project root.
- The documentation accurately reflects the current codebase architecture, API, and frontend patterns.
- An agent can use these documents to understand how to implement a new feature (e.g., adding a new field to the Dog model) without scanning the entire codebase.

89
.zenflow/tasks/init-9c68/spec.md Normal file
View File

@@ -0,0 +1,89 @@
# Technical Specification - Codebase Documentation (INIT)
This specification outlines the plan for creating comprehensive developer documentation for the Breedr codebase.
## Technical Context
- **Backend**: Node.js, Express, `better-sqlite3`.
- **Frontend**: React (Vite), `react-router-dom`, `axios`, `react-d3-tree`.
- **Database**: SQLite (managed via `server/db/init.js` and `server/db/migrations.js`).
- **Structure**: Monorepo-style with `client/` and `server/` directories.
## Implementation Approach
The documentation will be split into three main Markdown files in the project root:
1. **DEVELOPMENT.md**: Focuses on architecture, database design, and workflow.
2. **API.md**: Detailed documentation of all REST API endpoints.
3. **FRONTEND_GUIDE.md**: Focuses on React patterns, components, and styling.
### Research Methodology
- **Database**: Analyze `server/db/init.js` for table schemas and `parents` table logic.
- **API**: Scan `server/routes/*.js` for endpoints, middleware, and request/response structures.
- **Frontend**: Analyze `client/src/App.jsx` for routing, `client/src/hooks/` for state management, and `client/src/components/` for reusable patterns.
## Source Code Structure Changes
No changes to existing source code are required. Three new files will be created in the root directory:
- `/DEVELOPMENT.md`
- `/API.md`
- `/FRONTEND_GUIDE.md`
## Documentation Structure
### 1. DEVELOPMENT.md
- **Overview**: System purpose and high-level architecture.
- **Project Layout**: Description of key directories (`client`, `server`, `data`, `static`, `uploads`).
- **Database Design**:
- Explain the "Parents Table" approach (decoupling genealogy from the `dogs` table).
- Schema overview (Dogs, Litters, Health, Genetics, Settings).
- Initialization and migration process.
- **Getting Started**:
- `npm install` (root and client).
- `npm run dev` (concurrent execution).
- Database initialization (`npm run db:init`).
- **Coding Standards**: Backend route structure, async/await usage, error handling.
### 2. API.md
- **Base URL**: `/api`
- **Authentication**: (Note if any exists, currently seems open).
- **Endpoint Groups**:
- `Dogs`: CRUD operations, photo management, parent/offspring retrieval.
- `Litters`: Management of whelping records.
- `Health`: OFA records and test results.
- `Genetics`: DNA panel markers and results.
- `Breeding`: Breeding records and pairing simulations.
- `Settings`: Kennel profile management.
- **Data Models**: JSON schema examples for Dog, Litter, HealthRecord, etc.
### 3. FRONTEND_GUIDE.md
- **Tech Stack**: Vite, React, CSS Modules/Global CSS.
- **Routing**: `react-router-dom` configuration in `App.jsx`.
- **State Management**: `SettingsProvider` and `useSettings` hook.
- **Pedigree Engine**: Implementation of `react-d3-tree` and `pedigreeHelpers.js`.
- **Key Components**:
- `DogForm`: Complex form with parent selection.
- `PedigreeTree`: SVG-based genealogy visualization.
- `ClearanceSummaryCard`: Health status overview.
- **Styling**: Theming with CSS variables (found in `index.css` and `App.css`).
## Delivery Phases
### Phase 1: Core Architecture & Database (DEVELOPMENT.md)
- Document the tech stack and monorepo structure.
- Detail the SQLite schema and genealogy logic.
- Add setup and development commands.
### Phase 2: API Documentation (API.md)
- Document all routes in `server/routes/`.
- Provide request/response examples.
- Document the `parents` table integration in API responses.
### Phase 3: Frontend Guide (FRONTEND_GUIDE.md)
- Document React component patterns and hooks.
- Explain the pedigree visualization logic.
- Document routing and styling conventions.
## Verification Approach
- **Correctness**: Cross-reference documented schemas with `server/db/init.js`.
- **Accuracy**: Test documented API endpoints against the running server if possible, or verify via route handlers.
- **Completeness**: Ensure all components in `client/src/components` and routes in `server/routes` are mentioned or categorized.
- **Formatting**: Use `markdownlint` (if available) or manual review to ensure readability.

201
API.md Normal file
View File

@@ -0,0 +1,201 @@
# BREEDR API Documentation (v0.6.1)
Base URL: `/api`
All endpoints return JSON responses. Errors follow the format `{ "error": "message" }`.
---
## 1. Dogs (`/api/dogs`)
Manage individual dogs in the kennel.
### `GET /`
Get active kennel dogs.
- **Query Params**:
- `include_external=1`: Include external dogs (studs/others)
- `external_only=1`: Only show external dogs
- **Response**: Array of [Dog](#dog-object) objects with `sire` and `dam` attached.
### `GET /:id`
Get single dog details.
- **Response**: [Dog](#dog-object) object including `sire`, `dam`, and `offspring` array.
### `POST /`
Create a new dog.
- **Body**: See [Dog](#dog-object) fields. `name`, `breed`, `sex` are required.
- **Response**: The created Dog object.
### `PUT /:id`
Update an existing dog.
- **Body**: Dog fields to update.
- **Response**: The updated Dog object.
### `DELETE /:id`
Permanently delete a dog and its related records (health, heat, parents).
- **Response**: `{ "success": true, "message": "..." }`
### `POST /:id/photos`
Upload a photo for a dog.
- **Form-Data**: `photo` (file)
- **Response**: `{ "url": "...", "photos": [...] }`
### `DELETE /:id/photos/:photoIndex`
Delete a specific photo from a dog's photo array.
- **Response**: `{ "photos": [...] }`
---
## 2. Litters (`/api/litters`)
Manage breeding litters and puppy logs.
### `GET /`
Get all litters.
- **Response**: Array of [Litter](#litter-object) objects with sire/dam names and puppies.
### `GET /:id`
Get single litter details.
- **Response**: [Litter](#litter-object) object.
### `POST /`
Create a new litter.
- **Body**: `sire_id`, `dam_id`, `breeding_date` (required), `whelping_date`, `puppy_count`, `notes`.
- **Response**: The created Litter object.
### `PUT /:id`
Update litter details.
### `POST /:id/puppies/:puppyId`
Link a dog to a litter as a puppy.
- **Side Effect**: Automatically sets the litter's sire and dam as the puppy's parents.
### `DELETE /:id/puppies/:puppyId`
Remove a puppy from a litter (sets `litter_id` to NULL).
### `GET /:litterId/puppies/:puppyId/logs`
Get weight and health logs for a puppy.
### `POST /:litterId/puppies/:puppyId/logs`
Add a weight/health log entry.
- **Body**: `record_date` (required), `weight_oz`, `weight_lbs`, `notes`, `record_type`.
---
## 3. Health (`/api/health`)
Manage OFA clearances and veterinary records.
### `GET /dog/:dogId`
Get all health records for a dog.
### `GET /dog/:dogId/clearance-summary`
Get GRCA core clearance status (Hip, Elbow, Heart, Eyes).
- **Response**: `{ summary, grca_eligible, age_eligible, chic_number }`
### `GET /dog/:dogId/chic-eligible`
Check if a dog has all required CHIC tests.
### `POST /`
Create health record.
- **Body**: `dog_id`, `record_type`, `test_date` (required), `test_type`, `test_name`, `ofa_result`, `ofa_number`, etc.
---
## 4. Genetics (`/api/genetics`)
Manage DNA panel results and breeding risks.
### `GET /dog/:dogId`
Get the full genetic panel for a dog. Returns `tests` (actual records) and `panel` (full list including `not_tested` placeholders).
### `GET /pairing-risk?sireId=X&damId=Y`
Check genetic compatibility between two dogs.
- **Response**: `{ risks: [...], safe_to_pair: boolean }`
### `POST /`
Add a genetic test result.
- **Body**: `dog_id`, `marker`, `result` (clear|carrier|affected|not_tested).
---
## 5. Breeding (`/api/breeding`)
Track heat cycles and whelping projections.
### `GET /heat-cycles/active`
Get currently active heat cycles.
### `GET /heat-cycles/:id/suggestions`
Get optimal breeding window (days 9-15) and whelping projections.
### `POST /heat-cycles`
Log a new heat cycle. Dog must be female.
### `GET /whelping-calculator?breeding_date=YYYY-MM-DD`
Standalone tool to calculate expected whelping window.
---
## 6. Pedigree (`/api/pedigree`)
Advanced ancestry and COI calculations.
### `GET /:id?generations=N`
Get an interactive pedigree tree (ancestors). Default 5 generations.
### `GET /:id/descendants?generations=N`
Get a descendant tree. Default 3 generations.
### `POST /trial-pairing`
Calculate Coefficient of Inbreeding (COI) for a hypothetical mating.
- **Body**: `sire_id`, `dam_id`.
- **Response**: `{ coi, commonAncestors, directRelation, recommendation }`
---
## 7. Settings (`/api/settings`)
### `GET /`
Get kennel metadata (name, address, etc.).
### `PUT /`
Update kennel settings.
---
## Data Objects
### Dog Object
```json
{
"id": 1,
"name": "BREEDR Champion",
"registration_number": "AKC123456",
"breed": "Golden Retriever",
"sex": "male",
"birth_date": "2020-01-01",
"color": "Golden",
"microchip": "900123456789",
"is_active": 1,
"is_champion": 1,
"is_external": 0,
"photo_urls": ["/uploads/img.jpg"],
"notes": "Excellent temperament",
"sire": { "id": 10, "name": "Sire Name" },
"dam": { "id": 11, "name": "Dam Name" }
}
```
### Litter Object
```json
{
"id": 5,
"sire_id": 1,
"dam_id": 2,
"breeding_date": "2023-01-01",
"whelp_date": "2023-03-05",
"total_count": 8,
"puppies": [ ... ]
}
```

118
DEVELOPMENT.md Normal file
View File

@@ -0,0 +1,118 @@
# 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` |

105
FRONTEND_GUIDE.md Normal file
View File

@@ -0,0 +1,105 @@
# Frontend Guide
This document provides an overview of the frontend architecture, technologies, and patterns used in the BREEDR application.
## Tech Stack
- **Framework**: [React](https://reactjs.org/) (bootstrapped with [Vite](https://vitejs.dev/))
- **Routing**: [react-router-dom](https://reactrouter.com/)
- **Icons**: [lucide-react](https://lucide.dev/)
- **Data Fetching**: [axios](https://axios-http.com/)
- **Visualizations**: [react-d3-tree](https://github.com/bkrem/react-d3-tree) (for pedigree rendering)
- **Styling**: Standard CSS with CSS Variables (Custom properties)
## Project Structure
```text
client/src/
├── components/ # Reusable UI components
├── hooks/ # Custom hooks and context providers
├── pages/ # Page-level components (routes)
├── utils/ # Helper functions and utilities
├── App.jsx # Root component with routing
├── App.css # Layout-specific styles
├── index.css # Global styles and CSS variables
└── main.jsx # Application entry point
```
## Routing and Layout
The application uses `react-router-dom` for navigation. The primary layout and routes are defined in `client/src/App.jsx`.
- **Navbar**: Contains links to Dashboard, Dogs, Litters, Breeding, Pairing, and Settings.
- **Main Content**: Renders the matched route element within a `.main-content` container.
### Key Routes
- `/`: Dashboard
- `/dogs`: Dog List
- `/dogs/:id`: Dog Detail
- `/pedigree/:id`: Pedigree View
- `/litters`: Litter List
- `/breeding`: Breeding Calendar
- `/pairing`: Pairing Simulator
- `/settings`: Settings Page
## State Management
### Settings Context (`useSettings`)
Global application settings (like kennel name) are managed via a React Context.
- **Provider**: `SettingsProvider` in `client/src/hooks/useSettings.jsx`.
- **Usage**:
```javascript
import { useSettings } from '../hooks/useSettings';
const { settings, saveSettings, loading } = useSettings();
```
### Local State
Most page-specific data is managed using standard `useState` and `useEffect` hooks, fetching data via `axios`.
## Styling Conventions
The application follows a dark-theme aesthetic using CSS variables for consistency.
### CSS Variables (`client/src/index.css`)
Key variables include:
- `--primary`: Main brand color (warm amber/copper).
- `--bg-primary`: Primary background.
- `--text-primary`: Primary text color.
- `--border`: Standard border color.
- `--radius`: Default border radius.
### Reusable UI Classes
- `.btn`, `.btn-primary`, `.btn-secondary`: Standard button styles.
- `.card`: Container for grouped content.
- `.grid`, `.grid-2`, `.grid-3`: Responsive grid layouts.
- `.modal-overlay`, `.modal-content`: Standard modal structure.
## Key Components
### PedigreeTree (`client/src/components/PedigreeTree.jsx`)
Uses `react-d3-tree` to render a horizontal, step-based pedigree.
- **Props**: `dogId`, `pedigreeData`, `coi`.
- **Features**: Custom node rendering (differentiating by sex and champion status), zoom/pan controls, and COI display.
### DogForm (`client/src/components/DogForm.jsx`)
Handles both creation and editing of dog records.
- **Logic**: Manages internal/external dog states, parent selection (manual or linked to litter), and champion status.
- **Validation**: Basic required field validation; errors are displayed at the top of the form.
## Data Fetching Patterns
Standard `axios` requests are used:
```javascript
const fetchData = async () => {
try {
const res = await axios.get('/api/endpoint');
setData(res.data);
} catch (err) {
setError(err.response?.data?.error || 'Error message');
}
};
```
## Icons
Use `lucide-react` for all icons to ensure consistency across the UI.