labFusion/frontend

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

cd frontend
npm install

Development Server

npm start

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

Building for Production

npm run build

Testing

npm test

Configuration

Environment Variables

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

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

Documentation

• Clean Code Implementation
• Resilience Features
• Main Project README

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 file for details.