# Project Restructure Migration Guide

## Overview
The project has been restructured to follow Python best practices with a clean separation of concerns.

---

## Directory Changes

### Before → After

```
Root Directory Files → Organized Structure
```

| Old Location | New Location | Type |
|-------------|--------------|------|
| `config.py` | `src/core/config.py` | Core |
| `database.py` | `src/core/database.py` | Core |
| `face_processing.py` | `src/core/face_processing.py` | Core |
| `photo_management.py` | `src/core/photo_management.py` | Core |
| `tag_management.py` | `src/core/tag_management.py` | Core |
| `search_stats.py` | `src/core/search_stats.py` | Core |
| `dashboard_gui.py` | `src/gui/dashboard_gui.py` | GUI |
| `gui_core.py` | `src/gui/gui_core.py` | GUI |
| `identify_panel.py` | `src/gui/identify_panel.py` | GUI |
| `auto_match_panel.py` | `src/gui/auto_match_panel.py` | GUI |
| `modify_panel.py` | `src/gui/modify_panel.py` | GUI |
| `tag_manager_panel.py` | `src/gui/tag_manager_panel.py` | GUI |
| `path_utils.py` | `src/utils/path_utils.py` | Utils |
| `photo_tagger.py` | `src/photo_tagger.py` | Entry |
| `test_*.py` | `tests/test_*.py` | Tests |
| `README.md` | `docs/README.md` | Docs |
| `ARCHITECTURE.md` | `docs/ARCHITECTURE.md` | Docs |

---

## Import Path Changes

### Core Modules

**Before:**
```python
from config import DEFAULT_DB_PATH
from database import DatabaseManager
from face_processing import FaceProcessor
from photo_management import PhotoManager
from tag_management import TagManager
from search_stats import SearchStats
```

**After:**
```python
from src.core.config import DEFAULT_DB_PATH
from src.core.database import DatabaseManager
from src.core.face_processing import FaceProcessor
from src.core.photo_management import PhotoManager
from src.core.tag_management import TagManager
from src.core.search_stats import SearchStats
```

### GUI Modules

**Before:**
```python
from gui_core import GUICore
from identify_panel import IdentifyPanel
from auto_match_panel import AutoMatchPanel
from modify_panel import ModifyPanel
from tag_manager_panel import TagManagerPanel
```

**After:**
```python
from src.gui.gui_core import GUICore
from src.gui.identify_panel import IdentifyPanel
from src.gui.auto_match_panel import AutoMatchPanel
from src.gui.modify_panel import ModifyPanel
from src.gui.tag_manager_panel import TagManagerPanel
```

### Utility Modules

**Before:**
```python
from path_utils import normalize_path, validate_path_exists
```

**After:**
```python
from src.utils.path_utils import normalize_path, validate_path_exists
```

---

## Files Requiring Import Updates

### Priority 1 - Core Files
- [ ] `src/core/face_processing.py`
- [ ] `src/core/photo_management.py`
- [ ] `src/core/tag_management.py`
- [ ] `src/core/search_stats.py`
- [ ] `src/core/database.py`

### Priority 2 - GUI Files
- [ ] `src/gui/dashboard_gui.py`
- [ ] `src/gui/identify_panel.py`
- [ ] `src/gui/auto_match_panel.py`
- [ ] `src/gui/modify_panel.py`
- [ ] `src/gui/tag_manager_panel.py`
- [ ] `src/gui/gui_core.py`

### Priority 3 - Entry Points
- [ ] `src/photo_tagger.py`
- [ ] `src/setup.py`

### Priority 4 - Tests
- [ ] `tests/test_deepface_gui.py`
- [ ] `tests/test_face_recognition.py`
- [ ] `tests/test_simple_gui.py`

---

## Search & Replace Patterns

Use these patterns to update imports systematically:

### Pattern 1: Core imports
```bash
# Find
from config import
from database import
from face_processing import
from photo_management import
from tag_management import
from search_stats import

# Replace with
from src.core.config import
from src.core.database import
from src.core.face_processing import
from src.core.photo_management import
from src.core.tag_management import
from src.core.search_stats import
```

### Pattern 2: GUI imports
```bash
# Find
from gui_core import
from identify_panel import
from auto_match_panel import
from modify_panel import
from tag_manager_panel import

# Replace with
from src.gui.gui_core import
from src.gui.identify_panel import
from src.gui.auto_match_panel import
from src.gui.modify_panel import
from src.gui.tag_manager_panel import
```

### Pattern 3: Utils imports
```bash
# Find
from path_utils import

# Replace with
from src.utils.path_utils import
```

---

## Running the Application After Restructure

### GUI Dashboard
```bash
# Old
python dashboard_gui.py

# New
python src/gui/dashboard_gui.py
# OR
python -m src.gui.dashboard_gui
```

### CLI Tool
```bash
# Old
python photo_tagger.py

# New
python src/photo_tagger.py
# OR
python -m src.photo_tagger
```

### Tests
```bash
# Old
python test_deepface_gui.py

# New
python tests/test_deepface_gui.py
# OR
python -m pytest tests/
```

---

## Verification Steps

### 1. Check Import Errors
```bash
cd /home/ladmin/Code/punimtag
python -c "from src.core import DatabaseManager; print('Core imports OK')"
python -c "from src.gui import GUICore; print('GUI imports OK')"
python -c "from src.utils import normalize_path; print('Utils imports OK')"
```

### 2. Test Each Module
```bash
# Test core modules
python -c "from src.core.database import DatabaseManager; db = DatabaseManager(':memory:'); print('Database OK')"

# Test GUI modules (may need display)
python -c "from src.gui.gui_core import GUICore; print('GUI Core OK')"
```

### 3. Run Application
```bash
# Try to launch dashboard
python src/gui/dashboard_gui.py
```

### 4. Run Tests
```bash
# Run test suite
python -m pytest tests/ -v
```

---

## Common Issues and Solutions

### Issue 1: ModuleNotFoundError
```
ModuleNotFoundError: No module named 'config'
```

**Solution:** Update import from `from config import` to `from src.core.config import`

### Issue 2: Relative Import Error
```
ImportError: attempted relative import with no known parent package
```

**Solution:** Use absolute imports with `src.` prefix

### Issue 3: Circular Import
```
ImportError: cannot import name 'X' from partially initialized module
```

**Solution:** Check for circular dependencies, may need to refactor

### Issue 4: sys.path Issues
If imports still fail, add to top of file:
```python
import sys
from pathlib import Path

# Add project root to path
project_root = Path(__file__).parent.parent  # Adjust based on file location
sys.path.insert(0, str(project_root))
```

---

## Rollback Plan

If issues arise, you can rollback:

```bash
# Revert git changes
git checkout HEAD -- .

# Or manually move files back
mv src/core/*.py .
mv src/gui/*.py .
mv src/utils/*.py .
mv tests/*.py .
mv docs/*.md .
```

---

## Benefits of New Structure

✅ **Better Organization**: Clear separation of concerns  
✅ **Easier Navigation**: Files grouped by function  
✅ **Professional**: Follows Python community standards  
✅ **Scalable**: Easy to add new modules  
✅ **Testable**: Tests separate from source  
✅ **Maintainable**: Clear dependencies  

---

## Next Steps

1. ✅ Directory structure created
2. ✅ Files moved to new locations
3. ✅ __init__.py files created
4. ✅ Documentation updated
5. ⏳ Update import statements (NEXT)
6. ⏳ Test all functionality
7. ⏳ Update scripts and launchers
8. ⏳ Commit changes

---

## Testing Checklist

After updating imports, verify:

- [ ] Dashboard GUI launches
- [ ] Can scan for photos
- [ ] Face processing works
- [ ] Face identification works
- [ ] Auto-matching works
- [ ] Tag management works
- [ ] Search functionality works
- [ ] Database operations work
- [ ] All tests pass

---

**Status**: Files moved, imports need updating  
**Last Updated**: 2025-10-15  
**Next Action**: Update import statements in all files