Update README and documentation; refactor frontend components for improved structure and resilience
This commit is contained in:
glenn schrooyen
228
frontend/README.md
Normal file
228
frontend/README.md
Normal file
@@ -0,0 +1,228 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user