106 lines
3.7 KiB
Markdown
106 lines
3.7 KiB
Markdown
|
# Frontend Guide
|
||
|
|
|
||
|
|
This document provides an overview of the frontend architecture, technologies, and patterns used in the BREEDR application.
|
||
|
|
|
||
|
|
## Tech Stack
|
||
|
|
|
||
|
|
- **Framework**: [React](https://reactjs.org/) (bootstrapped with [Vite](https://vitejs.dev/))
|
||
|
|
- **Routing**: [react-router-dom](https://reactrouter.com/)
|
||
|
|
- **Icons**: [lucide-react](https://lucide.dev/)
|
||
|
|
- **Data Fetching**: [axios](https://axios-http.com/)
|
||
|
|
- **Visualizations**: [react-d3-tree](https://github.com/bkrem/react-d3-tree) (for pedigree rendering)
|
||
|
|
- **Styling**: Standard CSS with CSS Variables (Custom properties)
|
||
|
|
|
||
|
|
## Project Structure
|
||
|
|
|
||
|
|
```text
|
||
|
|
client/src/
|
||
|
|
├── components/ # Reusable UI components
|
||
|
|
├── hooks/ # Custom hooks and context providers
|
||
|
|
├── pages/ # Page-level components (routes)
|
||
|
|
├── utils/ # Helper functions and utilities
|
||
|
|
├── App.jsx # Root component with routing
|
||
|
|
├── App.css # Layout-specific styles
|
||
|
|
├── index.css # Global styles and CSS variables
|
||
|
|
└── main.jsx # Application entry point
|
||
|
|
```
|
||
|
|
|
||
|
|
## Routing and Layout
|
||
|
|
|
||
|
|
The application uses `react-router-dom` for navigation. The primary layout and routes are defined in `client/src/App.jsx`.
|
||
|
|
|
||
|
|
- **Navbar**: Contains links to Dashboard, Dogs, Litters, Breeding, Pairing, and Settings.
|
||
|
|
- **Main Content**: Renders the matched route element within a `.main-content` container.
|
||
|
|
|
||
|
|
### Key Routes
|
||
|
|
- `/`: Dashboard
|
||
|
|
- `/dogs`: Dog List
|
||
|
|
- `/dogs/:id`: Dog Detail
|
||
|
|
- `/pedigree/:id`: Pedigree View
|
||
|
|
- `/litters`: Litter List
|
||
|
|
- `/breeding`: Breeding Calendar
|
||
|
|
- `/pairing`: Pairing Simulator
|
||
|
|
- `/settings`: Settings Page
|
||
|
|
|
||
|
|
## State Management
|
||
|
|
|
||
|
|
### Settings Context (`useSettings`)
|
||
|
|
Global application settings (like kennel name) are managed via a React Context.
|
||
|
|
|
||
|
|
- **Provider**: `SettingsProvider` in `client/src/hooks/useSettings.jsx`.
|
||
|
|
- **Usage**:
|
||
|
|
```javascript
|
||
|
|
import { useSettings } from '../hooks/useSettings';
|
||
|
|
const { settings, saveSettings, loading } = useSettings();
|
||
|
|
```
|
||
|
|
|
||
|
|
### Local State
|
||
|
|
Most page-specific data is managed using standard `useState` and `useEffect` hooks, fetching data via `axios`.
|
||
|
|
|
||
|
|
## Styling Conventions
|
||
|
|
|
||
|
|
The application follows a dark-theme aesthetic using CSS variables for consistency.
|
||
|
|
|
||
|
|
### CSS Variables (`client/src/index.css`)
|
||
|
|
Key variables include:
|
||
|
|
- `--primary`: Main brand color (warm amber/copper).
|
||
|
|
- `--bg-primary`: Primary background.
|
||
|
|
- `--text-primary`: Primary text color.
|
||
|
|
- `--border`: Standard border color.
|
||
|
|
- `--radius`: Default border radius.
|
||
|
|
|
||
|
|
### Reusable UI Classes
|
||
|
|
- `.btn`, `.btn-primary`, `.btn-secondary`: Standard button styles.
|
||
|
|
- `.card`: Container for grouped content.
|
||
|
|
- `.grid`, `.grid-2`, `.grid-3`: Responsive grid layouts.
|
||
|
|
- `.modal-overlay`, `.modal-content`: Standard modal structure.
|
||
|
|
|
||
|
|
## Key Components
|
||
|
|
|
||
|
|
### PedigreeTree (`client/src/components/PedigreeTree.jsx`)
|
||
|
|
Uses `react-d3-tree` to render a horizontal, step-based pedigree.
|
||
|
|
- **Props**: `dogId`, `pedigreeData`, `coi`.
|
||
|
|
- **Features**: Custom node rendering (differentiating by sex and champion status), zoom/pan controls, and COI display.
|
||
|
|
|
||
|
|
### DogForm (`client/src/components/DogForm.jsx`)
|
||
|
|
Handles both creation and editing of dog records.
|
||
|
|
- **Logic**: Manages internal/external dog states, parent selection (manual or linked to litter), and champion status.
|
||
|
|
- **Validation**: Basic required field validation; errors are displayed at the top of the form.
|
||
|
|
|
||
|
|
## Data Fetching Patterns
|
||
|
|
|
||
|
|
Standard `axios` requests are used:
|
||
|
|
```javascript
|
||
|
|
const fetchData = async () => {
|
||
|
|
try {
|
||
|
|
const res = await axios.get('/api/endpoint');
|
||
|
|
setData(res.data);
|
||
|
|
} catch (err) {
|
||
|
|
setError(err.response?.data?.error || 'Error message');
|
||
|
|
}
|
||
|
|
};
|
||
|
|
```
|
||
|
|
|
||
|
|
## Icons
|
||
|
|
Use `lucide-react` for all icons to ensure consistency across the UI.
|