2daccf7d8c
Scan the code, build the .md files you need to make it easier for the agent to preform modifications and fix bugs
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.
|