# PunimTag - Intelligent Photo Management System

A Flask-based photo management system with automatic face recognition, tagging, and duplicate detection.

## 🚀 Quick Start

```bash
# Install dependencies
pip install -r requirements.txt

# Run the application
python main.py

# Access the web interface
# http://localhost:5000
```

## 📁 Project Structure

```
PunimTag/
├── src/                    # Main application source code
│   ├── backend/           # Flask backend and API
│   │   ├── app.py         # Main Flask application
│   │   ├── db_manager.py  # Database operations
│   │   └── visual_identifier.py  # Face recognition
│   ├── frontend/          # JavaScript and UI components
│   └── utils/             # Utility functions
│       └── tag_manager.py # Tag management
├── docs/                  # Documentation and steering documents
│   ├── product.md         # Product vision and goals
│   ├── structure.md       # Project organization
│   ├── tech.md           # Technical architecture
│   ├── api-standards.md   # API design standards
│   ├── testing-standards.md # Testing guidelines
│   └── code-conventions.md # Coding standards
├── tests/                 # Test files
│   ├── test_main.py       # Main test suite
│   └── conftest.py        # Test configuration
├── data/                  # Database files and user data
├── config/                # Configuration files
│   ├── settings.py        # Application settings
│   └── punimtag_config.json
├── scripts/               # Utility scripts
├── assets/                # Static assets
├── photos/                # User photo storage
└── main.py                # Application entry point
```

## 🎯 Key Features

- **Automatic Face Recognition**: Identify and tag people in photos
- **Smart Organization**: Group photos by people, events, and locations
- **Duplicate Detection**: Find and manage duplicate photos automatically
- **Intuitive Interface**: Web-based GUI with progressive loading
- **Privacy-First**: Local processing, no cloud dependencies

## 📚 Documentation

### Steering Documents

- **[Product Vision](docs/product.md)**: Product goals, target users, and roadmap
- **[Project Structure](docs/structure.md)**: Architecture and organization principles
- **[Technical Architecture](docs/tech.md)**: Technology stack and implementation details
- **[API Standards](docs/api-standards.md)**: API design and development guidelines
- **[Testing Standards](docs/testing-standards.md)**: Testing strategy and best practices
- **[Code Conventions](docs/code-conventions.md)**: Coding standards and style guides

### Development Guidelines

1. **Follow the steering documents** for consistent development
2. **Use the organized structure** - place code in appropriate directories
3. **Write tests** following the testing standards
4. **Follow API standards** for all endpoints
5. **Adhere to code conventions** for maintainability

## 🧪 Testing

```bash
# Run the main test suite
python tests/test_main.py

# Run with pytest (if installed)
pytest tests/
```

## 🔧 Configuration

Configuration is centralized in `config/settings.py`:

- Database paths
- Face recognition settings
- File upload limits
- Thumbnail sizes

## 🚀 Deployment

### Development

```bash
python main.py
```

### Production

```bash
# Use a WSGI server like Gunicorn
gunicorn -w 4 -b 0.0.0.0:5000 main:app
```

## 📦 Dependencies

- **Flask**: Web framework
- **SQLite**: Database
- **dlib**: Face recognition
- **Pillow**: Image processing
- **NumPy**: Numerical operations

## 🤝 Contributing

1. Read the steering documents in `docs/`
2. Follow the code conventions
3. Write tests for new features
4. Update documentation as needed

## 📄 License

This project is licensed under the MIT License.

## 🆘 Support

For issues and questions:

1. Check the steering documents in `docs/`
2. Review existing tests in `tests/`
3. Check the API standards for endpoint usage