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

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.