Pac-cogs/cline_docs/systemPatterns.md

# System Patterns

## Import Patterns

### Standard Import Structure

Every non-init Python file should follow this pattern:

```python
try:
    # Try relative imports first
    from ..module.submodule import Component
    from .local_module import LocalComponent
except ImportError:
    # Fall back to absolute imports if relative imports fail
    from videoarchiver.module.submodule import Component
    from videoarchiver.current_module.local_module import LocalComponent
```

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

### Package-Level Imports

For package-level imports, use:

```python
try:
    from .. import utils
except ImportError:
    from videoarchiver import utils
```

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

## Module Organization

### Core Module

- Base components and interfaces
- Core functionality implementation
- Command handling
- Event processing
- Error handling
- Lifecycle management

### Database Module

- Database connections
- Query management
- Schema definitions
- Data models
- Migration handling

### FFmpeg Module

- Process management
- Binary handling
- Encoding parameters
- GPU detection
- Video analysis

### Queue Module

- Queue management
- State tracking
- Health monitoring
- Recovery mechanisms
- Cleanup operations

### Utils Module

- Common utilities
- File operations
- Progress tracking
- Permission management
- Message handling

## Development Patterns

### Code Organization

- Keep modules focused and cohesive
- Follow single responsibility principle
- Use clear and consistent naming
- 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