# Cursor AI Rules for PunimTag

## Project Context
This is a Python desktop application for photo management with facial recognition.

## Code Style
- Follow PEP 8 strictly
- Use type hints for all function signatures
- Maximum line length: 100 characters
- Use 4 spaces for indentation (never tabs)
- Add docstrings to all public classes and methods

## Import Organization
```python
# Standard library imports
import os
import sys

# Third-party imports
import numpy as np
from PIL import Image

# Local imports
from src.core.database import DatabaseManager
from src.utils.path_utils import normalize_path
```

## Naming Conventions
- Classes: PascalCase (e.g., `FaceProcessor`)
- Functions/methods: snake_case (e.g., `process_faces`)
- Constants: UPPER_SNAKE_CASE (e.g., `DEFAULT_TOLERANCE`)
- Private members: prefix with underscore (e.g., `_internal_method`)

## Project Structure
- `src/core/`: Business logic and data processing
- `src/gui/`: GUI components and panels
- `src/utils/`: Utility functions
- `tests/`: Test files
- `docs/`: Documentation
- `.notes/`: Project planning and notes

## Key Technologies
- Python 3.12+
- Tkinter for GUI
- SQLite for database
- face_recognition (current, migrating to DeepFace)
- NumPy for numerical operations
- Pillow for image processing

## Import Paths
Always use absolute imports from src:
```python
from src.core.database import DatabaseManager
from src.gui.gui_core import GUICore
```

## Database
- All database operations go through DatabaseManager
- Use context managers for database connections
- Always use prepared statements (never string interpolation)

## Error Handling
- Use specific exception types
- Log errors appropriately
- Provide user-friendly error messages in GUI
- Never silently catch exceptions

## Testing
- Write tests for all new features
- Use pytest framework
- Place tests in `tests/` directory
- Aim for >80% code coverage

## Documentation
- Update docstrings when changing code
- Keep README.md current
- Update ARCHITECTURE.md for architectural changes
- Document complex algorithms inline

## Git Commit Messages
Format: `<type>: <subject>`

Types:
- feat: New feature
- fix: Bug fix
- docs: Documentation
- style: Formatting
- refactor: Code restructuring
- test: Tests
- chore: Maintenance

## Current Focus
- Migrating from face_recognition to DeepFace
- Improving test coverage
- Optimizing performance
- Enhancing documentation

## Avoid
- Circular imports
- Global state (except configuration)
- Hard-coded file paths
- SQL injection vulnerabilities
- Mixing business logic with GUI code

## Prefer
- Type hints
- List/dict comprehensions over loops
- Context managers for resources
- f-strings for formatting
- Pathlib over os.path

## When Adding Features
1. Design: Plan the feature
2. Database: Update schema if needed
3. Core: Implement business logic
4. GUI: Add UI components
5. Tests: Write test cases
6. Docs: Update documentation

## Performance Considerations
- Cache face encodings
- Use database indices
- Batch database operations
- Lazy load large datasets
- Profile before optimizing

## Security
- Validate all user inputs
- Sanitize file paths
- Use prepared SQL statements
- Don't store sensitive data in plain text
- Validate image files before processing