punimtag/QUICK_START.md

PunimTag - Quick Start Guide

🚀 Running the Application

Start Dashboard

source venv/bin/activate
python run_dashboard.py

Run CLI Tool

source venv/bin/activate
python -m src.photo_tagger --help

---

📁 Project Structure

punimtag/
├── src/
│   ├── core/          # Business logic
│   ├── gui/           # GUI components
│   └── utils/         # Utilities
├── tests/             # Test suite
├── docs/              # Documentation
├── .notes/            # Project planning
└── run_dashboard.py   # Main launcher

---

📚 Key Documentation

• README.md - Main documentation
• CONTRIBUTING.md - How to contribute
• docs/ARCHITECTURE.md - System design
• RESTRUCTURE_SUMMARY.md - Restructure details
• IMPORT_FIX_SUMMARY.md - Import fixes

---

🔧 Common Tasks

Add Photos

1. Open dashboard: python run_dashboard.py
2. Click "Scan Photos" in menu
3. Select folder with photos

Process Faces

1. Open dashboard
2. Click "Process Photos" button
3. Wait for face detection to complete

Identify People

1. Open "Identify" tab
2. View unidentified faces
3. Enter person name or select existing
4. Click "Identify"

Search Photos

1. Open "Search" tab
2. Enter search criteria (name, date, tags)
3. View results

---

🐛 Troubleshooting

ModuleNotFoundError

Solution: Use run_dashboard.py launcher, not direct file execution

Import Errors

Solution: Make sure you're in the venv:

source venv/bin/activate

PIL/ImageTk Error

Solution: Install Pillow in venv:

pip install Pillow

---

💡 Tips

• Always activate venv before running
• Use run_dashboard.py for GUI
• Use python -m src.photo_tagger for CLI
• Check .notes/ for planning docs
• Read docs/ARCHITECTURE.md for system design

---

📞 Need Help?

1. Check documentation in docs/
2. Read .notes/ for planning info
3. See CONTRIBUTING.md for guidelines

---

Quick Command Reference:

# Activate environment
source venv/bin/activate

# Run dashboard
python run_dashboard.py

# Run CLI
python -m src.photo_tagger

# Run tests
python -m pytest tests/

# Deactivate environment
deactivate

---

Last Updated: October 15, 2025