# 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.