Update README and documentation; refactor frontend components for improved structure and resilience

2025-09-11 23:46:29 +02:00
parent 63b4bb487d
commit b9206de1a0
49 changed files with 27058 additions and 581 deletions
--- a/.cursor/rules/api-standards.mdc
+++ b/.cursor/rules/api-standards.mdc
@@ -0,0 +1,96 @@
+---
+description: API validation and service standards
+globs: ["services/**/*.java", "services/**/*.py", "services/**/*.js"]
+alwaysApply: false
+---
+
+# API Standards
+
+## API Documentation
+
+### OpenAPI Requirements
+- All endpoints MUST have OpenAPI documentation
+- Include request/response schemas
+- Provide example requests and responses
+- Document error responses
+- Include authentication requirements
+
+### Documentation Tags
+- Use consistent tags for endpoint grouping
+- Provide clear descriptions
+- Include parameter documentation
+- Document response codes
+
+## Error Handling
+
+### Consistent Error Responses
+```javascript
+// Standard error response format
+{
+  "error": "Error type",
+  "message": "User-friendly message",
+  "timestamp": "2024-01-01T00:00:00Z",
+  "details": "Additional error details"
+}
+```
+
+### HTTP Status Codes
+- 200: Success
+- 201: Created
+- 400: Bad Request
+- 401: Unauthorized
+- 403: Forbidden
+- 404: Not Found
+- 500: Internal Server Error
+- 503: Service Unavailable
+
+## Service-Specific Standards
+
+### Java Spring Boot
+- Use constructor injection
+- Implement proper validation
+- Use appropriate annotations
+- Follow REST conventions
+- Implement global exception handling
+
+### Python FastAPI
+- Use Pydantic models
+- Implement async/await
+- Use dependency injection
+- Follow OpenAPI standards
+- Implement proper error handling
+
+### Node.js Express
+- Use middleware appropriately
+- Implement proper error handling
+- Use async/await patterns
+- Follow REST conventions
+- Implement health checks
+
+## Validation
+
+### Input Validation
+- Validate all inputs
+- Sanitize user data
+- Use appropriate data types
+- Implement rate limiting
+
+### Response Validation
+- Validate response schemas
+- Use consistent data formats
+- Implement proper error handling
+- Document response structures
+
+## Performance
+
+### API Performance
+- Use pagination for large datasets
+- Implement response compression
+- Use appropriate HTTP methods
+- Optimize response sizes
+
+### Caching
+- Implement appropriate caching
+- Use Redis for distributed caching
+- Cache frequently accessed data
+- Implement cache invalidation
--- a/.cursor/rules/code-quality.mdc
+++ b/.cursor/rules/code-quality.mdc
@@ -0,0 +1,124 @@
+---
+description: Code quality standards and clean code principles
+globs: ["**/*.java", "**/*.py", "**/*.js", "**/*.jsx", "**/*.ts", "**/*.tsx"]
+alwaysApply: true
+---
+
+# Code Quality Standards
+
+## Clean Code Principles
+
+### Single Responsibility Principle (SRP)
+- Each class/component has one clear purpose
+- Each function/method does one thing
+- Clear separation of concerns
+- Minimal coupling between components
+
+### Open/Closed Principle (OCP)
+- Open for extension, closed for modification
+- Use interfaces and abstractions
+- Plugin architecture where appropriate
+- Configuration-driven behavior
+
+### Dependency Inversion Principle (DIP)
+- Depend on abstractions, not concretions
+- Use dependency injection
+- Interface-based design
+- Inversion of control
+
+### Interface Segregation Principle (ISP)
+- Small, focused interfaces
+- Clients should not depend on unused methods
+- Specific-purpose modules
+- Clear API boundaries
+
+## Naming Conventions
+
+### Java (Spring Boot)
+- Classes: PascalCase (e.g., `DashboardController`)
+- Methods: camelCase (e.g., `getAllDashboards`)
+- Variables: camelCase (e.g., `dashboardRepository`)
+- Constants: UPPER_SNAKE_CASE (e.g., `API_VERSION`)
+
+### Python (FastAPI)
+- Classes: PascalCase (e.g., `ServiceStatus`)
+- Functions: snake_case (e.g., `get_home_assistant_entities`)
+- Variables: snake_case (e.g., `service_config`)
+- Constants: UPPER_SNAKE_CASE (e.g., `SERVICES`)
+
+### JavaScript/TypeScript (Node.js, React)
+- Classes: PascalCase (e.g., `DashboardComponent`)
+- Functions: camelCase (e.g., `fetchServiceSpec`)
+- Variables: camelCase (e.g., `serviceStatus`)
+- Constants: UPPER_SNAKE_CASE (e.g., `API_CONFIG`)
+
+## Function Design
+
+### Small, Focused Functions
+- Maximum 20-30 lines per function
+- Single level of abstraction
+- Clear, descriptive names
+- Single responsibility
+
+### Error Handling
+- Consistent error responses
+- Proper exception handling
+- User-friendly error messages
+- Logging for debugging
+
+## Code Review Checklist
+
+### Before Merging
+- [ ] All new code follows naming conventions
+- [ ] Error handling is implemented
+- [ ] Input validation is present
+- [ ] Documentation is updated
+- [ ] Tests are written and passing
+- [ ] Clean code principles are followed
+
+### Documentation Review
+- [ ] README files are comprehensive
+- [ ] Clean code documentation is complete
+- [ ] Project structure is updated
+- [ ] Progress tracking is current
+- [ ] Links are working and relevant
+
+## Testing Requirements
+
+### Unit Tests
+- Test business logic
+- Test error conditions
+- Test edge cases
+- Maintain high coverage
+
+### Integration Tests
+- Test API endpoints
+- Test service interactions
+- Test error scenarios
+- Test configuration
+
+### End-to-End Tests
+- Test critical user flows
+- Test service integration
+- Test error recovery
+- Test performance
+
+## Performance Guidelines
+
+### Database Optimization
+- Use appropriate indexes
+- Implement connection pooling
+- Use lazy loading where appropriate
+- Optimize queries
+
+### Caching
+- Implement appropriate caching
+- Use Redis for distributed caching
+- Cache frequently accessed data
+- Implement cache invalidation
+
+### Resource Management
+- Proper cleanup of resources
+- Memory leak prevention
+- Connection pooling
+- Efficient algorithms
--- a/.cursor/rules/documentation-standards.mdc
+++ b/.cursor/rules/documentation-standards.mdc
@@ -0,0 +1,81 @@
+---
+description: Documentation standards for LabFusion project
+globs: ["**/*.md", "**/README.md", "**/CLEAN_CODE.md", "**/RESILIENCE.md"]
+alwaysApply: true
+---
+
+# Documentation Standards
+
+## README Requirements
+Every service and major component MUST have a comprehensive README.md file that includes:
+
+### Service README Requirements
+- **Service Overview**: Purpose, port, and main functionality
+- **Architecture**: Key components and their responsibilities
+- **Features**: Core capabilities and integrations
+- **API Endpoints**: Available endpoints with descriptions
+- **Configuration**: Environment variables and settings
+- **Development**: Setup, running, and testing instructions
+- **Dependencies**: Required packages and versions
+- **Clean Code**: Reference to CLEAN_CODE.md file
+
+### Frontend README Requirements
+- **Component Structure**: Directory organization and component hierarchy
+- **Development Setup**: Installation and running instructions
+- **Architecture**: Clean code principles and patterns
+- **API Integration**: Service communication and error handling
+- **Offline Mode**: Resilience features and fallback behavior
+- **Testing**: Unit and integration testing guidelines
+
+## Documentation Folder Structure
+The `docs/` folder MUST contain:
+
+### Required Files
+- **specs.md**: Project specifications and requirements
+- **structure.txt**: Complete project directory structure
+- **progress.md**: Development progress and completed tasks
+- **FRONTEND_REFACTORING.md**: Frontend clean code refactoring summary
+
+### Documentation Updates
+- Update `structure.txt` when adding new files or directories
+- Update `progress.md` when completing tasks or milestones
+- Update service-specific READMEs when modifying functionality
+- Update main README.md when adding new features or services
+
+## Clean Code Documentation
+Every service MUST have a CLEAN_CODE.md file that includes:
+
+### Required Sections
+- **Architecture Overview**: Service structure and organization
+- **Clean Code Principles**: SRP, OCP, DIP, ISP applications
+- **Code Quality Improvements**: Before/after examples
+- **Best Practices**: Technology-specific guidelines
+- **Performance Optimizations**: Caching, async operations, etc.
+- **Testing Strategy**: Unit, integration, and E2E testing
+- **Code Review Checklist**: Quality assurance guidelines
+- **Future Improvements**: Enhancement roadmap
+
+## Documentation Quality Checklist
+
+### README Quality
+- [ ] Clear service overview and purpose
+- [ ] Complete setup and running instructions
+- [ ] API endpoint documentation
+- [ ] Configuration examples
+- [ ] Development guidelines
+- [ ] Links to related documentation
+
+### Clean Code Documentation
+- [ ] Architecture overview included
+- [ ] Clean code principles explained
+- [ ] Code examples provided
+- [ ] Best practices documented
+- [ ] Testing strategies outlined
+- [ ] Future improvements listed
+
+### Project Documentation
+- [ ] Structure.txt is up to date
+- [ ] Progress.md reflects current status
+- [ ] All services have README files
+- [ ] All services have CLEAN_CODE.md files
+- [ ] Main README.md is comprehensive
--- a/.cursor/rules/frontend-standards.mdc
+++ b/.cursor/rules/frontend-standards.mdc
@@ -0,0 +1,104 @@
+---
+description: Frontend component standards and React best practices
+globs: ["frontend/**/*.js", "frontend/**/*.jsx", "frontend/**/*.ts", "frontend/**/*.tsx"]
+alwaysApply: false
+---
+
+# Frontend Standards
+
+## Component Design
+
+### React Components
+- Single responsibility per component
+- Props validation with PropTypes
+- Error boundary protection
+- Reusable and composable design
+- Maximum 50 lines per component file
+
+### Component Structure
+```
+src/
+├── components/
+│   ├── common/           # Reusable UI components
+│   ├── dashboard/        # Dashboard-specific components
+│   └── [main components] # Main application components
+├── hooks/               # Custom React hooks
+├── services/            # API and external services
+├── utils/               # Utility functions
+└── constants/           # Configuration constants
+```
+
+## Naming Conventions
+
+### JavaScript/TypeScript
+- Classes: PascalCase (e.g., `DashboardComponent`)
+- Functions: camelCase (e.g., `fetchServiceSpec`)
+- Variables: camelCase (e.g., `serviceStatus`)
+- Constants: UPPER_SNAKE_CASE (e.g., `API_CONFIG`)
+
+### File Organization
+- Component files: PascalCase (e.g., `Dashboard.js`)
+- Hook files: camelCase with 'use' prefix (e.g., `useServiceStatus.js`)
+- Utility files: camelCase (e.g., `errorHandling.js`)
+- Constant files: camelCase (e.g., `index.js`)
+
+## Clean Code Principles
+
+### 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
+
+### 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`
+
+### Component Composition
+- Large components broken into smaller, focused components
+- Clear prop interfaces with PropTypes validation
+- Easy to test and maintain
+
+## Error Handling
+
+### Error Boundaries
+- `ErrorBoundary` component for graceful error recovery
+- Development-friendly error details
+- User-friendly error messages
+
+### Offline Mode
+- Service status monitoring
+- Fallback data when services unavailable
+- Automatic retry mechanisms
+- Clear status indicators
+
+## Performance
+
+### Component Optimization
+- Smaller components = 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
+  });
+});
+```
--- a/.cursor/rules/project-structure.mdc
+++ b/.cursor/rules/project-structure.mdc
@@ -0,0 +1,110 @@
+---
+description: Project structure and file organization standards
+globs: ["**/*"]
+alwaysApply: true
+---
+
+# Project Structure Standards
+
+## Directory Organization
+
+### Service Structure
+```
+services/[service-name]/
+├── src/                    # Source code
+├── tests/                  # Test files
+├── docs/                   # Service-specific documentation
+├── README.md              # Service documentation
+├── CLEAN_CODE.md          # Clean code implementation
+├── package.json/pom.xml   # Dependencies
+└── Dockerfile             # Container configuration
+```
+
+### Frontend Structure
+```
+frontend/
+├── src/
+│   ├── components/        # React components
+│   │   ├── common/        # Reusable components
+│   │   └── dashboard/     # Dashboard-specific components
+│   ├── hooks/            # Custom hooks
+│   ├── services/         # API services
+│   ├── utils/            # Utility functions
+│   ├── constants/        # Configuration constants
+│   └── [app files]       # Main application files
+├── public/               # Static assets
+├── README.md            # Frontend documentation
+├── CLEAN_CODE.md        # Clean code implementation
+├── RESILIENCE.md        # Offline mode features
+└── package.json         # Dependencies
+```
+
+## File Naming
+
+### Service Files
+- Source files: Follow language conventions
+- Documentation: README.md, CLEAN_CODE.md
+- Configuration: package.json, pom.xml, requirements.txt
+- Docker: Dockerfile, Dockerfile.dev
+
+### Frontend Files
+- Components: PascalCase (e.g., `Dashboard.js`)
+- Hooks: camelCase with 'use' prefix (e.g., `useServiceStatus.js`)
+- Utilities: camelCase (e.g., `errorHandling.js`)
+- Constants: camelCase (e.g., `index.js`)
+
+## Documentation Structure
+
+### Required Documentation
+- **README.md**: Service overview and setup
+- **CLEAN_CODE.md**: Clean code implementation
+- **Progress tracking**: In docs/progress.md
+- **Structure updates**: In docs/structure.txt
+
+### Documentation Updates
+- Update when adding new files or directories
+- Update when completing tasks or milestones
+- Update when modifying functionality
+- Update when adding new features or services
+
+## Configuration Files
+
+### Environment Configuration
+- Use .env files for environment variables
+- Provide .env.example templates
+- Document all required variables
+- Use consistent naming conventions
+
+### Docker Configuration
+- Multi-stage builds for production
+- Development-specific Dockerfiles
+- Health checks in containers
+- Proper base image selection
+
+## Git Structure
+
+### Branching Strategy
+- main: Production-ready code
+- develop: Integration branch
+- feature/*: Feature development
+- hotfix/*: Critical fixes
+
+### Commit Messages
+- Use conventional commit format
+- Include scope when relevant
+- Provide clear descriptions
+- Reference issues when applicable
+
+## Quality Gates
+
+### Pre-commit Checks
+- Code formatting
+- Linting
+- Type checking
+- Test execution
+
+### Pre-merge Checks
+- Code review approval
+- Test coverage requirements
+- Documentation updates
+- Security scans