labFusion/frontend/README.md

# LabFusion Frontend

A modern React frontend for the LabFusion homelab dashboard, built with clean code principles and offline resilience.

## Features

- **Clean Code Architecture**: Modular components following React best practices
- **Offline Mode**: Works gracefully when backend services are unavailable
- **Real-time Monitoring**: Service status and system metrics
- **Error Resilience**: Comprehensive error handling and recovery
- **Responsive Design**: Mobile-friendly interface with Ant Design
- **Type Safety**: PropTypes validation for better development experience

## Architecture

### Component Structure
```
src/
├── components/
│   ├── common/           # Reusable UI components
│   │   ├── ErrorBoundary.js    # Error boundary component
│   │   ├── LoadingSpinner.js   # Loading state component
│   │   └── StatusIcon.js       # Status icon component
│   ├── dashboard/        # Dashboard-specific components
│   │   ├── SystemStatsCards.js # System statistics cards
│   │   ├── ServiceStatusList.js # Service status list
│   │   └── RecentEventsList.js # Recent events list
│   └── [main components] # Main application components
├── hooks/               # Custom React hooks
│   └── useServiceStatus.js # Service status and data hooks
├── services/            # API and external services
│   └── api.js           # Centralized API client
├── utils/               # Utility functions
│   └── errorHandling.js # Error handling utilities
├── constants/           # Configuration constants
│   └── index.js         # UI constants, colors, messages
└── [app files]          # Main application files
```

## Clean Code Principles

### 1. Single Responsibility Principle (SRP)
- Each component has one clear purpose
- `SystemStatsCards` only handles system statistics display
- `ServiceStatusList` only manages service status display
- `StatusIcon` only renders status icons

### 2. Don't Repeat Yourself (DRY)
- Centralized status icon logic in `StatusIcon` component
- Reusable loading component in `LoadingSpinner`
- Centralized error handling in `utils/errorHandling.js`
- All constants extracted to `constants/index.js`

### 3. Component Composition
- Large components broken into smaller, focused components
- Clear prop interfaces with PropTypes validation
- Easy to test and maintain

### 4. Error Handling
- Error boundaries for graceful error recovery
- User-friendly error messages
- Development-friendly error details

## Offline Mode & Resilience

### Service Status Monitoring
- Real-time health checks every 30 seconds
- Automatic retry when services come back online
- Clear status indicators (online, partial, offline)

### Graceful Degradation
- Fallback data when services are unavailable
- Loading states during data fetching
- Clear error messages instead of crashes

### Error Recovery
- 5-second timeout for all API calls
- Connection error detection
- Automatic retry mechanisms

## Development

### Prerequisites
- Node.js 16+
- npm or yarn

### Installation
```bash
cd frontend
npm install
```

### Development Server
```bash
npm start
```

The app will open at http://localhost:3000

### Building for Production
```bash
npm run build
```

### Testing
```bash
npm test
```

## Configuration

### Environment Variables
```bash
REACT_APP_API_URL=http://localhost:8080
REACT_APP_ADAPTERS_URL=http://localhost:8000
REACT_APP_DOCS_URL=http://localhost:8083
```

### Service URLs
- **API Gateway**: http://localhost:8080
- **Service Adapters**: http://localhost:8000
- **API Documentation**: http://localhost:8083

## Component Documentation

### Common Components

#### ErrorBoundary
Catches JavaScript errors anywhere in the component tree and displays a fallback UI.

#### LoadingSpinner
Reusable loading component with customizable message and size.

#### StatusIcon
Consistent status icon rendering with color coding.

### Dashboard Components

#### SystemStatsCards
Displays system metrics (CPU, Memory, Disk, Network) with progress bars.

#### ServiceStatusList
Shows service status with uptime information and status indicators.

#### RecentEventsList
Displays recent events with timestamps and service information.

### Hooks

#### useServiceStatus
Monitors service health and provides status information.

#### useSystemData
Fetches and manages system data with fallback handling.

## API Integration

### Centralized API Client
All API calls are centralized in `services/api.js` with:
- Consistent error handling
- Timeout configuration
- Fallback data support

### Service Endpoints
- **API Gateway**: Health, dashboards, system data
- **Service Adapters**: Home Assistant, Frigate, Immich, events
- **API Docs**: Service health and documentation

## Error Handling

### Error Types
- **Connection Timeout**: Request timeout handling
- **Service Error**: HTTP error responses
- **Service Unavailable**: Network connectivity issues
- **Unknown Error**: Unexpected errors

### Error Recovery
- Automatic retry mechanisms
- Fallback data display
- User-friendly error messages
- Development error details

## Performance

### Optimizations
- Smaller components for better React optimization
- Reduced re-renders through focused components
- Memoization opportunities for pure components

### Code Splitting Ready
- Modular structure supports code splitting
- Easy to lazy load dashboard components
- Clear separation enables tree shaking

## Testing

### Testable Components
- Pure functions in utils
- Isolated component logic
- Clear prop interfaces
- Mockable dependencies

### Test Structure
```javascript
describe('SystemStatsCards', () => {
  it('renders CPU usage correctly', () => {
    // Test focused component
  });
});
```

## Documentation

- [Clean Code Implementation](CLEAN_CODE.md)
- [Resilience Features](RESILIENCE.md)
- [Main Project README](../README.md)

## Contributing

1. Follow clean code principles
2. Add PropTypes to new components
3. Write tests for new functionality
4. Update documentation as needed
5. Follow the established component structure

## License

This project is licensed under the MIT License - see the [LICENSE](../LICENSE) file for details.