90 lines
4.1 KiB
Markdown
90 lines
4.1 KiB
Markdown
|
# 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.
|