punimtag/.notes/restructure_migration.md

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:

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:

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:

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:

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:

from path_utils import normalize_path, validate_path_exists

After:

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

# 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

# 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

# Find
from path_utils import

# Replace with
from src.utils.path_utils import

---

Running the Application After Restructure

GUI Dashboard

# Old
python dashboard_gui.py

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

CLI Tool

# Old
python photo_tagger.py

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

Tests

# Old
python test_deepface_gui.py

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

---

Verification Steps

1. Check Import Errors

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

# 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

# Try to launch dashboard
python src/gui/dashboard_gui.py

4. Run Tests

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

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:

# 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