INIT (zenflow 9c6862b8)

Scan the code, build the .md files you need to make it easier for the agent to preform modifications and fix bugs
2026-03-11 09:51:35 -05:00
parent 5c6068364b
commit 2daccf7d8c
6 changed files with 644 additions and 0 deletions
--- a/.zenflow/tasks/init-9c68/plan.md
+++ b/.zenflow/tasks/init-9c68/plan.md
@@ -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.
--- a/.zenflow/tasks/init-9c68/requirements.md
+++ b/.zenflow/tasks/init-9c68/requirements.md
@@ -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.
--- a/.zenflow/tasks/init-9c68/spec.md
+++ b/.zenflow/tasks/init-9c68/spec.md
@@ -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.
--- a/API.md
+++ b/API.md
@@ -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": [ ... ]
+}
+```
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -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` |
--- a/FRONTEND_GUIDE.md
+++ b/FRONTEND_GUIDE.md
@@ -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.