docs: Update architecture documentation and add auto-match load analysis
This commit updates the `ARCHITECTURE.md` file to reflect the transition to a web-based application, including new features and system overview. Additionally, it introduces `AUTOMATCH_LOAD_ANALYSIS.md`, detailing performance issues with the Auto-Match page and recommendations for optimizations. A new document, `CONFIDENCE_CALIBRATION_SUMMARY.md`, is also added to explain the implementation of a confidence calibration system for face recognition, ensuring more accurate match probabilities. These updates enhance the project's documentation and provide insights for future improvements.
This commit is contained in:
@@ -0,0 +1,129 @@
|
||||
# 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
|
||||
|
||||
Reference in New Issue
Block a user