breedr/.zenflow/tasks/init-9c68/spec.md

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.