punimtag/README.md

PunimTag - Intelligent Photo Management System

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

🚀 Quick Start

# 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: Product goals, target users, and roadmap
• Project Structure: Architecture and organization principles
• Technical Architecture: Technology stack and implementation details
• API Standards: API design and development guidelines
• Testing Standards: Testing strategy and best practices
• Code Conventions: 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

# 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

python main.py

Production

# 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