labFusion/AGENTS.md

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!