docs: update system patterns with standardized import patterns

cline_docs/systemPatterns.md

@@ -2,59 +2,121 @@
 
 ## Import Patterns
 
-### Relative Imports
+### Standard Import Structure
-
+Every non-init Python file should follow this pattern:
-- Use relative imports by default to maintain package structure
-- Single dot (.) for imports from same directory
-- Double dots (..) for imports from parent directory
-- Example: `from .base import VideoArchiver`
-
-### Fallback Import Pattern
-
-When loading in different environments (development vs Red-DiscordBot):
-
 ```python
 try:
     # Try relative imports first
-    from ..utils.exceptions import ComponentError
+    from ..module.submodule import Component
+    from .local_module import LocalComponent
 except ImportError:
     # Fall back to absolute imports if relative imports fail
-    from videoarchiver.utils.exceptions import ComponentError
+    from videoarchiver.module.submodule import Component
+    from videoarchiver.current_module.local_module import LocalComponent
 ```
 
-### Package Structure
+### TYPE_CHECKING Imports
+For type checking imports, use:
+```python
+if TYPE_CHECKING:
+    try:
+        from ..module.component import Component
+    except ImportError:
+        from videoarchiver.module.component import Component
+```
 
-- Each module has __init__.py to mark it as a package
+### Package-Level Imports
-- Core package imports are kept simple and direct
+For package-level imports, use:
-- Avoid circular imports by using proper hierarchy
+```python
+try:
+    from .. import utils
+except ImportError:
+    from videoarchiver import utils
+```
 
-## Component Management
+### Import Rules
+1. Always try relative imports first
+2. Provide absolute import fallbacks
+3. Group imports logically:
+   - Standard library imports first
+   - Third-party imports second
+   - Local/relative imports third
+4. Use explicit imports over wildcard imports
+5. Handle TYPE_CHECKING imports separately
+6. Keep __init__.py files simple with direct imports
+7. Test imports in both development and production environments
 
-- Components are loaded in dependency order
+## Module Organization
-- Each component is registered and tracked
-- State changes and errors are logged
-- Health checks ensure system stability
 
-## Error Handling
+### Core Module
+- Base components and interfaces
+- Core functionality implementation
+- Command handling
+- Event processing
+- Error handling
+- Lifecycle management
 
-- Detailed error contexts are maintained
+### Database Module
-- Component errors include severity levels
+- Database connections
-- Graceful degradation when possible
+- Query management
-- Clear error messages for debugging
+- Schema definitions
+- Data models
+- Migration handling
 
-## Initialization Flow
+### FFmpeg Module
+- Process management
+- Binary handling
+- Encoding parameters
+- GPU detection
+- Video analysis
 
-1. Package imports are resolved
+### Queue Module
-2. Core components are initialized
+- Queue management
-3. Dependencies are checked and ordered
+- State tracking
-4. Components are initialized in dependency order
+- Health monitoring
-5. Health checks are established
+- Recovery mechanisms
-6. System enters ready state
+- Cleanup operations
+
+### Utils Module
+- Common utilities
+- File operations
+- Progress tracking
+- Permission management
+- Message handling
 
 ## Development Patterns
 
-- Always maintain relative imports where possible
+### Code Organization
-- Use fallback patterns for environment compatibility
+- Keep modules focused and cohesive
-- Keep package structure clean and hierarchical
+- Follow single responsibility principle
-- Document import patterns and their rationale
+- Use clear and consistent naming
-- Test in both development and production environments
+- Maintain proper documentation
+- Implement proper error handling
+
+### Testing Strategy
+- Test in development environment
+- Verify in production environment
+- Check import resolution
+- Validate component interactions
+- Monitor error handling
+
+### Error Handling
+- Use specific exception types
+- Provide detailed error contexts
+- Implement graceful degradation
+- Log errors appropriately
+- Track error patterns
+
+### Component Management
+- Register components explicitly
+- Track component states
+- Monitor health metrics
+- Handle cleanup properly
+- Manage dependencies carefully
+
+### Documentation
+- Maintain clear docstrings
+- Update context files
+- Document patterns and decisions
+- Track changes systematically
+- Keep examples current