# PunimTag - Quick Start Guide

## 🚀 Running the Application

### Start Dashboard
```bash
source venv/bin/activate
python run_dashboard.py
```

### Run CLI Tool
```bash
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:
```bash
source venv/bin/activate
```

### PIL/ImageTk Error
**Solution**: Install Pillow in venv:
```bash
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:**

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