# LabFusion Agent Instructions

## Project Overview
LabFusion is a unified dashboard and integration hub for homelab services, built with a polyglot microservices architecture using Java Spring Boot, Python FastAPI, Node.js Express, and React.

## Code Style

### Naming Conventions
- **Java**: PascalCase for classes, camelCase for methods, UPPER_SNAKE_CASE for constants
- **Python**: PascalCase for classes, snake_case for functions, UPPER_SNAKE_CASE for constants
- **JavaScript/TypeScript**: PascalCase for classes, camelCase for functions, UPPER_SNAKE_CASE for constants

### Component Design
- Single responsibility per component
- Maximum 50 lines per component file
- Props validation with PropTypes
- Error boundary protection
- Reusable and composable design

## Architecture

### Service Structure
- Follow the repository pattern
- Keep business logic in service layers
- Use dependency injection
- Implement proper error handling
- Clear separation of concerns

### Frontend Structure
- Use functional components in React
- Implement custom hooks for state logic
- Use error boundaries for error handling
- Follow component composition patterns
- Centralize constants and utilities

## Documentation Requirements

### README Files
Every service MUST have a comprehensive README.md that includes:
- Service overview and purpose
- Architecture and key components
- Features and capabilities
- API endpoints with descriptions
- Configuration and environment variables
- Development setup and running instructions
- Dependencies and versions
- Reference to CLEAN_CODE.md

### Clean Code Documentation
Every service MUST have a CLEAN_CODE.md that includes:
- Architecture overview
- Clean code principles applied
- Code quality improvements
- Best practices and guidelines
- Performance optimizations
- Testing strategies
- Code review checklist
- Future improvements

### Project Documentation
- Update docs/structure.txt when adding files
- Update docs/progress.md when completing tasks
- Update service READMEs when modifying functionality
- Update main README.md when adding features

## API Standards

### OpenAPI Documentation
- All endpoints MUST have OpenAPI documentation
- Include request/response schemas
- Provide example requests and responses
- Document error responses
- Include authentication requirements

### Error Handling
- Use consistent error response format
- Implement proper HTTP status codes
- Provide user-friendly error messages
- Log errors for debugging

### Validation
- Validate all inputs
- Use appropriate data types
- Implement rate limiting
- Sanitize user data

## Testing

### 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

## Quality Assurance

### Code Review Checklist
- [ ] Naming conventions followed
- [ ] Error handling implemented
- [ ] Input validation present
- [ ] Documentation updated
- [ ] Tests written and passing
- [ ] Clean code principles followed

### Documentation Review
- [ ] README files comprehensive
- [ ] Clean code documentation complete
- [ ] Project structure updated
- [ ] Progress tracking current
- [ ] Links working and relevant

## Performance

### 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

### API Performance
- Use pagination for large datasets
- Implement response compression
- Use appropriate HTTP methods
- Optimize response sizes

## Security

### Input Validation
- Validate all inputs
- Sanitize user data
- Use appropriate data types
- Implement rate limiting

### Error Handling
- Don't expose sensitive information
- Log errors appropriately
- Use consistent error responses
- Implement proper status codes

### Authentication
- Implement proper authentication
- Use secure token handling
- Implement authorization checks
- Follow security best practices

## When Working on This Project

1. **Always update documentation** when making changes
2. **Follow clean code principles** in all implementations
3. **Write tests** for new functionality
4. **Use consistent naming conventions** across all languages
5. **Implement proper error handling** in all services
6. **Update progress tracking** when completing tasks
7. **Maintain code quality** through regular reviews
8. **Keep documentation current** and comprehensive

Remember: Good documentation is as important as good code. When in doubt, document it!