Upload 22 files

Dockerfile

@@ -0,0 +1,26 @@
+FROM python:3.11-slim
+
+# Install system dependencies for face_recognition
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    cmake \
+    libopenblas-dev \
+    liblapack-dev \
+    libx11-dev \
+    libgtk-3-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Install Python dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY . .
+
+# Expose port
+EXPOSE 5000
+
+# Run with gunicorn
+CMD ["gunicorn", "--bind", "0.0.0.0:5000", "--workers", "2", "--timeout", "120", "run:app"]

app/__init__.py

@@ -0,0 +1,49 @@
+"""Flask application factory."""
+import os
+from flask import Flask
+from flask_cors import CORS
+from flask_pymongo import PyMongo
+
+from config import config
+
+mongo = PyMongo()
+
+
+def create_app(config_name=None):
+    """Create and configure the Flask application."""
+    if config_name is None:
+        config_name = os.environ.get('FLASK_ENV', 'development')
+    
+    app = Flask(__name__)
+    app.config.from_object(config[config_name])
+    
+    # Initialize extensions
+    CORS(app, resources={
+        r"/api/*": {
+            "origins": ["http://localhost:3000", "http://localhost:5173"],
+            "methods": ["GET", "POST", "PUT", "DELETE", "PATCH"],
+            "allow_headers": ["Content-Type", "Authorization"]
+        }
+    })
+    
+    mongo.init_app(app)
+    
+    # Initialize Cloudinary
+    from app.services.cloudinary_service import init_cloudinary
+    init_cloudinary(app.config)
+    
+    # Register blueprints
+    from app.routes.people import people_bp
+    from app.routes.images import images_bp
+    from app.routes.stats import stats_bp
+    
+    app.register_blueprint(people_bp, url_prefix='/api/people')
+    app.register_blueprint(images_bp, url_prefix='/api/images')
+    app.register_blueprint(stats_bp, url_prefix='/api/stats')
+    
+    # Health check route
+    @app.route('/api/health')
+    def health_check():
+        return {'status': 'healthy', 'message': 'Image Organizer API is running'}
+    
+    return app

app/models.py

@@ -0,0 +1,71 @@
+"""Database models and schemas."""
+from datetime import datetime
+from bson import ObjectId
+
+
+class PersonModel:
+    """Person model for MongoDB."""
+    
+    @staticmethod
+    def create_person(name, face_encoding=None, thumbnail_url=None):
+        """Create a new person document."""
+        return {
+            'name': name,
+            'face_encodings': [face_encoding] if face_encoding else [],
+            'thumbnail_url': thumbnail_url,
+            'image_count': 0,
+            'created_at': datetime.utcnow(),
+            'updated_at': datetime.utcnow()
+        }
+    
+    @staticmethod
+    def to_response(person):
+        """Convert person document to API response."""
+        return {
+            'id': str(person['_id']),
+            'name': person['name'],
+            'thumbnail_url': person.get('thumbnail_url'),
+            'image_count': person.get('image_count', 0),
+            'created_at': person['created_at'].isoformat() if person.get('created_at') else None,
+            'updated_at': person['updated_at'].isoformat() if person.get('updated_at') else None
+        }
+
+
+class ImageModel:
+    """Image model for MongoDB."""
+    
+    @staticmethod
+    def create_image(cloudinary_url, cloudinary_public_id, original_filename, 
+                     face_encodings=None, person_id=None, face_locations=None):
+        """Create a new image document."""
+        return {
+            'cloudinary_url': cloudinary_url,
+            'cloudinary_public_id': cloudinary_public_id,
+            'original_filename': original_filename,
+            'face_encodings': face_encodings or [],
+            'face_locations': face_locations or [],
+            'person_id': ObjectId(person_id) if person_id else None,
+            'has_face': bool(face_encodings and len(face_encodings) > 0),
+            'is_identified': person_id is not None,
+            'created_at': datetime.utcnow(),
+            'updated_at': datetime.utcnow()
+        }
+    
+    @staticmethod
+    def to_response(image, include_person=False):
+        """Convert image document to API response."""
+        response = {
+            'id': str(image['_id']),
+            'url': image['cloudinary_url'],
+            'original_filename': image.get('original_filename'),
+            'has_face': image.get('has_face', False),
+            'is_identified': image.get('is_identified', False),
+            'face_count': len(image.get('face_locations', [])),
+            'person_id': str(image['person_id']) if image.get('person_id') else None,
+            'created_at': image['created_at'].isoformat() if image.get('created_at') else None
+        }
+        
+        if include_person and image.get('person'):
+            response['person'] = PersonModel.to_response(image['person'])
+        
+        return response

app/routes/__init__.py

@@ -0,0 +1,6 @@
+"""Routes package."""
+from .people import people_bp
+from .images import images_bp
+from .stats import stats_bp
+
+__all__ = ['people_bp', 'images_bp', 'stats_bp']

app/routes/images.py

@@ -0,0 +1,433 @@
+"""Image management routes."""
+from flask import Blueprint, request, jsonify, current_app
+from bson import ObjectId
+from bson.errors import InvalidId
+from datetime import datetime
+from werkzeug.utils import secure_filename
+import os
+
+from app import mongo
+from app.models import ImageModel, PersonModel
+from app.services.cloudinary_service import upload_image, delete_image, get_thumbnail_url
+from app.services.face_recognition_service import get_face_service
+
+images_bp = Blueprint('images', __name__)
+
+
+def allowed_file(filename):
+    """Check if file extension is allowed."""
+    allowed_extensions = current_app.config.get('ALLOWED_EXTENSIONS', {'png', 'jpg', 'jpeg', 'gif', 'webp'})
+    return '.' in filename and filename.rsplit('.', 1)[1].lower() in allowed_extensions
+
+
+@images_bp.route('', methods=['GET'])
+def get_images():
+    """Get all images with filtering options."""
+    try:
+        page = int(request.args.get('page', 1))
+        per_page = int(request.args.get('per_page', 20))
+        filter_type = request.args.get('filter', 'all')  # all, identified, unidentified
+        
+        skip = (page - 1) * per_page
+        
+        # Build query based on filter
+        query = {}
+        if filter_type == 'identified':
+            query['is_identified'] = True
+        elif filter_type == 'unidentified':
+            query['has_face'] = True
+            query['is_identified'] = False
+        
+        # Get images with pagination
+        images = list(
+            mongo.db.images.find(query)
+            .sort('created_at', -1)
+            .skip(skip)
+            .limit(per_page)
+        )
+        
+        # Get person info for identified images
+        person_ids = [img['person_id'] for img in images if img.get('person_id')]
+        people = {str(p['_id']): p for p in mongo.db.people.find({'_id': {'$in': person_ids}})}
+        
+        # Attach person to images
+        for img in images:
+            if img.get('person_id') and str(img['person_id']) in people:
+                img['person'] = people[str(img['person_id'])]
+        
+        total = mongo.db.images.count_documents(query)
+        
+        return jsonify({
+            'success': True,
+            'data': [ImageModel.to_response(img, include_person=True) for img in images],
+            'pagination': {
+                'page': page,
+                'per_page': per_page,
+                'total': total,
+                'pages': (total + per_page - 1) // per_page
+            }
+        })
+        
+    except Exception as e:
+        return jsonify({'success': False, 'error': str(e)}), 500
+
+
+@images_bp.route('/<image_id>', methods=['GET'])
+def get_image(image_id):
+    """Get a specific image by ID."""
+    try:
+        image = mongo.db.images.find_one({'_id': ObjectId(image_id)})
+        
+        if not image:
+            return jsonify({'success': False, 'error': 'Image not found'}), 404
+        
+        # Get person info if assigned
+        if image.get('person_id'):
+            person = mongo.db.people.find_one({'_id': image['person_id']})
+            if person:
+                image['person'] = person
+        
+        return jsonify({
+            'success': True,
+            'data': ImageModel.to_response(image, include_person=True)
+        })
+        
+    except InvalidId:
+        return jsonify({'success': False, 'error': 'Invalid image ID'}), 400
+    except Exception as e:
+        return jsonify({'success': False, 'error': str(e)}), 500
+
+
+@images_bp.route('/upload', methods=['POST'])
+def upload_images():
+    """Upload one or more images with face detection."""
+    try:
+        if 'files' not in request.files:
+            return jsonify({'success': False, 'error': 'No files provided'}), 400
+        
+        files = request.files.getlist('files')
+        
+        if not files or all(f.filename == '' for f in files):
+            return jsonify({'success': False, 'error': 'No files selected'}), 400
+        
+        face_service = get_face_service(current_app.config.get('FACE_RECOGNITION_TOLERANCE', 0.6))
+        people = list(mongo.db.people.find({'face_encodings': {'$ne': []}}))
+        
+        results = []
+        
+        for file in files:
+            if file and file.filename:
+                if not allowed_file(file.filename):
+                    results.append({
+                        'filename': file.filename,
+                        'success': False,
+                        'error': 'File type not allowed'
+                    })
+                    continue
+                
+                original_filename = secure_filename(file.filename)
+                
+                # Read file data for both upload and face detection
+                file_data = file.read()
+                
+                # Upload to Cloudinary
+                upload_result = upload_image(file_data)
+                
+                if not upload_result['success']:
+                    results.append({
+                        'filename': original_filename,
+                        'success': False,
+                        'error': upload_result.get('error', 'Upload failed')
+                    })
+                    continue
+                
+                # Detect faces
+                face_result = face_service.detect_faces(file_data)
+                
+                face_encodings = face_result.get('face_encodings', [])
+                face_locations = face_result.get('face_locations', [])
+                
+                # Try to match faces to existing people
+                matched_person_id = None
+                if face_encodings:
+                    for encoding in face_encodings:
+                        matched_person_id = face_service.find_matching_person(encoding, people)
+                        if matched_person_id:
+                            break
+                
+                # Create image document
+                image_doc = ImageModel.create_image(
+                    cloudinary_url=upload_result['url'],
+                    cloudinary_public_id=upload_result['public_id'],
+                    original_filename=original_filename,
+                    face_encodings=face_encodings,
+                    face_locations=face_locations,
+                    person_id=str(matched_person_id) if matched_person_id else None
+                )
+                
+                result = mongo.db.images.insert_one(image_doc)
+                image_doc['_id'] = result.inserted_id
+                
+                # Update person's image count and thumbnail if matched
+                if matched_person_id:
+                    person = mongo.db.people.find_one({'_id': matched_person_id})
+                    update_data = {
+                        'image_count': person.get('image_count', 0) + 1,
+                        'updated_at': datetime.utcnow()
+                    }
+                    
+                    # Set thumbnail if not set
+                    if not person.get('thumbnail_url'):
+                        update_data['thumbnail_url'] = get_thumbnail_url(upload_result['url'])
+                    
+                    # Add face encoding to person if new
+                    if face_encodings:
+                        mongo.db.people.update_one(
+                            {'_id': matched_person_id},
+                            {
+                                '$set': update_data,
+                                '$addToSet': {'face_encodings': face_encodings[0]}
+                            }
+                        )
+                    else:
+                        mongo.db.people.update_one(
+                            {'_id': matched_person_id},
+                            {'$set': update_data}
+                        )
+                
+                results.append({
+                    'filename': original_filename,
+                    'success': True,
+                    'image': ImageModel.to_response(image_doc),
+                    'faces_detected': len(face_encodings),
+                    'matched_person': str(matched_person_id) if matched_person_id else None
+                })
+        
+        successful = sum(1 for r in results if r['success'])
+        
+        return jsonify({
+            'success': True,
+            'message': f'Uploaded {successful} of {len(results)} images',
+            'results': results
+        })
+        
+    except Exception as e:
+        return jsonify({'success': False, 'error': str(e)}), 500
+
+
+@images_bp.route('/<image_id>', methods=['DELETE'])
+def delete_image_route(image_id):
+    """Delete an image."""
+    try:
+        image = mongo.db.images.find_one({'_id': ObjectId(image_id)})
+        
+        if not image:
+            return jsonify({'success': False, 'error': 'Image not found'}), 404
+        
+        # Delete from Cloudinary
+        cloudinary_result = delete_image(image.get('cloudinary_public_id'))
+        
+        # Update person's image count
+        if image.get('person_id'):
+            mongo.db.people.update_one(
+                {'_id': image['person_id']},
+                {
+                    '$inc': {'image_count': -1},
+                    '$set': {'updated_at': datetime.utcnow()}
+                }
+            )
+        
+        # Delete from database
+        mongo.db.images.delete_one({'_id': ObjectId(image_id)})
+        
+        return jsonify({
+            'success': True,
+            'message': 'Image deleted successfully'
+        })
+        
+    except InvalidId:
+        return jsonify({'success': False, 'error': 'Invalid image ID'}), 400
+    except Exception as e:
+        return jsonify({'success': False, 'error': str(e)}), 500
+
+
+@images_bp.route('/<image_id>/assign', methods=['PATCH'])
+def assign_image(image_id):
+    """Assign or reassign an image to a person."""
+    try:
+        data = request.get_json()
+        person_id = data.get('person_id')
+        
+        image = mongo.db.images.find_one({'_id': ObjectId(image_id)})
+        if not image:
+            return jsonify({'success': False, 'error': 'Image not found'}), 404
+        
+        old_person_id = image.get('person_id')
+        
+        # Handle unassignment
+        if not person_id:
+            mongo.db.images.update_one(
+                {'_id': ObjectId(image_id)},
+                {'$set': {
+                    'person_id': None,
+                    'is_identified': False,
+                    'updated_at': datetime.utcnow()
+                }}
+            )
+            
+            # Update old person's count
+            if old_person_id:
+                mongo.db.people.update_one(
+                    {'_id': old_person_id},
+                    {
+                        '$inc': {'image_count': -1},
+                        '$set': {'updated_at': datetime.utcnow()}
+                    }
+                )
+            
+            return jsonify({
+                'success': True,
+                'message': 'Image unassigned successfully'
+            })
+        
+        # Verify person exists
+        person = mongo.db.people.find_one({'_id': ObjectId(person_id)})
+        if not person:
+            return jsonify({'success': False, 'error': 'Person not found'}), 404
+        
+        # Update image
+        mongo.db.images.update_one(
+            {'_id': ObjectId(image_id)},
+            {'$set': {
+                'person_id': ObjectId(person_id),
+                'is_identified': True,
+                'updated_at': datetime.utcnow()
+            }}
+        )
+        
+        # Update old person's count
+        if old_person_id and old_person_id != ObjectId(person_id):
+            mongo.db.people.update_one(
+                {'_id': old_person_id},
+                {
+                    '$inc': {'image_count': -1},
+                    '$set': {'updated_at': datetime.utcnow()}
+                }
+            )
+        
+        # Update new person's count and face encoding
+        update_ops = {
+            '$set': {'updated_at': datetime.utcnow()}
+        }
+        
+        if old_person_id != ObjectId(person_id):
+            update_ops['$inc'] = {'image_count': 1}
+        
+        # Add face encoding to help future matching
+        if image.get('face_encodings') and len(image['face_encodings']) > 0:
+            mongo.db.people.update_one(
+                {'_id': ObjectId(person_id)},
+                {
+                    **update_ops,
+                    '$addToSet': {'face_encodings': image['face_encodings'][0]}
+                }
+            )
+        else:
+            mongo.db.people.update_one(
+                {'_id': ObjectId(person_id)},
+                update_ops
+            )
+        
+        # Set thumbnail if not set
+        if not person.get('thumbnail_url'):
+            mongo.db.people.update_one(
+                {'_id': ObjectId(person_id)},
+                {'$set': {'thumbnail_url': get_thumbnail_url(image['cloudinary_url'])}}
+            )
+        
+        return jsonify({
+            'success': True,
+            'message': f'Image assigned to {person["name"]}'
+        })
+        
+    except InvalidId:
+        return jsonify({'success': False, 'error': 'Invalid ID'}), 400
+    except Exception as e:
+        return jsonify({'success': False, 'error': str(e)}), 500
+
+
+@images_bp.route('/<image_id>/reprocess', methods=['POST'])
+def reprocess_image(image_id):
+    """Reprocess an image to re-detect faces."""
+    try:
+        image = mongo.db.images.find_one({'_id': ObjectId(image_id)})
+        
+        if not image:
+            return jsonify({'success': False, 'error': 'Image not found'}), 404
+        
+        # Download image from Cloudinary and reprocess
+        import requests
+        from io import BytesIO
+        
+        response = requests.get(image['cloudinary_url'])
+        if response.status_code != 200:
+            return jsonify({'success': False, 'error': 'Failed to download image'}), 500
+        
+        face_service = get_face_service(current_app.config.get('FACE_RECOGNITION_TOLERANCE', 0.6))
+        face_result = face_service.detect_faces(response.content)
+        
+        face_encodings = face_result.get('face_encodings', [])
+        face_locations = face_result.get('face_locations', [])
+        
+        # Try to match faces
+        matched_person_id = None
+        if face_encodings:
+            people = list(mongo.db.people.find({'face_encodings': {'$ne': []}}))
+            for encoding in face_encodings:
+                matched_person_id = face_service.find_matching_person(encoding, people)
+                if matched_person_id:
+                    break
+        
+        # Update image
+        old_person_id = image.get('person_id')
+        
+        update_data = {
+            'face_encodings': face_encodings,
+            'face_locations': face_locations,
+            'has_face': bool(face_encodings),
+            'updated_at': datetime.utcnow()
+        }
+        
+        if matched_person_id:
+            update_data['person_id'] = matched_person_id
+            update_data['is_identified'] = True
+        
+        mongo.db.images.update_one(
+            {'_id': ObjectId(image_id)},
+            {'$set': update_data}
+        )
+        
+        # Update person counts
+        if old_person_id and old_person_id != matched_person_id:
+            mongo.db.people.update_one(
+                {'_id': old_person_id},
+                {'$inc': {'image_count': -1}}
+            )
+        
+        if matched_person_id and old_person_id != matched_person_id:
+            mongo.db.people.update_one(
+                {'_id': matched_person_id},
+                {'$inc': {'image_count': 1}}
+            )
+        
+        return jsonify({
+            'success': True,
+            'message': f'Reprocessed image. Found {len(face_encodings)} face(s).',
+            'faces_detected': len(face_encodings),
+            'matched_person': str(matched_person_id) if matched_person_id else None
+        })
+        
+    except InvalidId:
+        return jsonify({'success': False, 'error': 'Invalid image ID'}), 400
+    except Exception as e:
+        return jsonify({'success': False, 'error': str(e)}), 500

app/routes/people.py

@@ -0,0 +1,219 @@
+"""People management routes."""
+from flask import Blueprint, request, jsonify
+from bson import ObjectId
+from bson.errors import InvalidId
+from datetime import datetime
+
+from app import mongo
+from app.models import PersonModel, ImageModel
+from app.services.cloudinary_service import get_thumbnail_url
+
+people_bp = Blueprint('people', __name__)
+
+
+@people_bp.route('', methods=['GET'])
+def get_people():
+    """Get all people with optional search."""
+    try:
+        search = request.args.get('search', '').strip()
+        sort_by = request.args.get('sort', 'name')
+        order = request.args.get('order', 'asc')
+        
+        # Build query
+        query = {}
+        if search:
+            query['name'] = {'$regex': search, '$options': 'i'}
+        
+        # Sort options
+        sort_order = 1 if order == 'asc' else -1
+        sort_field = sort_by if sort_by in ['name', 'created_at', 'image_count'] else 'name'
+        
+        people = list(mongo.db.people.find(query).sort(sort_field, sort_order))
+        
+        return jsonify({
+            'success': True,
+            'data': [PersonModel.to_response(p) for p in people],
+            'total': len(people)
+        })
+        
+    except Exception as e:
+        return jsonify({'success': False, 'error': str(e)}), 500
+
+
+@people_bp.route('/<person_id>', methods=['GET'])
+def get_person(person_id):
+    """Get a specific person by ID."""
+    try:
+        person = mongo.db.people.find_one({'_id': ObjectId(person_id)})
+        
+        if not person:
+            return jsonify({'success': False, 'error': 'Person not found'}), 404
+        
+        return jsonify({
+            'success': True,
+            'data': PersonModel.to_response(person)
+        })
+        
+    except InvalidId:
+        return jsonify({'success': False, 'error': 'Invalid person ID'}), 400
+    except Exception as e:
+        return jsonify({'success': False, 'error': str(e)}), 500
+
+
+@people_bp.route('', methods=['POST'])
+def create_person():
+    """Create a new person."""
+    try:
+        data = request.get_json()
+        
+        if not data or not data.get('name'):
+            return jsonify({'success': False, 'error': 'Name is required'}), 400
+        
+        name = data['name'].strip()
+        
+        # Check if person with same name exists
+        existing = mongo.db.people.find_one({'name': {'$regex': f'^{name}$', '$options': 'i'}})
+        if existing:
+            return jsonify({'success': False, 'error': 'A person with this name already exists'}), 400
+        
+        person = PersonModel.create_person(name)
+        result = mongo.db.people.insert_one(person)
+        
+        person['_id'] = result.inserted_id
+        
+        return jsonify({
+            'success': True,
+            'message': 'Person created successfully',
+            'data': PersonModel.to_response(person)
+        }), 201
+        
+    except Exception as e:
+        return jsonify({'success': False, 'error': str(e)}), 500
+
+
+@people_bp.route('/<person_id>', methods=['PUT'])
+def update_person(person_id):
+    """Update a person's details."""
+    try:
+        data = request.get_json()
+        
+        if not data:
+            return jsonify({'success': False, 'error': 'No data provided'}), 400
+        
+        person = mongo.db.people.find_one({'_id': ObjectId(person_id)})
+        if not person:
+            return jsonify({'success': False, 'error': 'Person not found'}), 404
+        
+        update_data = {'updated_at': datetime.utcnow()}
+        
+        if 'name' in data:
+            name = data['name'].strip()
+            if not name:
+                return jsonify({'success': False, 'error': 'Name cannot be empty'}), 400
+            
+            # Check for duplicate name
+            existing = mongo.db.people.find_one({
+                'name': {'$regex': f'^{name}$', '$options': 'i'},
+                '_id': {'$ne': ObjectId(person_id)}
+            })
+            if existing:
+                return jsonify({'success': False, 'error': 'A person with this name already exists'}), 400
+            
+            update_data['name'] = name
+        
+        mongo.db.people.update_one(
+            {'_id': ObjectId(person_id)},
+            {'$set': update_data}
+        )
+        
+        updated_person = mongo.db.people.find_one({'_id': ObjectId(person_id)})
+        
+        return jsonify({
+            'success': True,
+            'message': 'Person updated successfully',
+            'data': PersonModel.to_response(updated_person)
+        })
+        
+    except InvalidId:
+        return jsonify({'success': False, 'error': 'Invalid person ID'}), 400
+    except Exception as e:
+        return jsonify({'success': False, 'error': str(e)}), 500
+
+
+@people_bp.route('/<person_id>', methods=['DELETE'])
+def delete_person(person_id):
+    """Delete a person and optionally their images."""
+    try:
+        delete_images = request.args.get('delete_images', 'false').lower() == 'true'
+        
+        person = mongo.db.people.find_one({'_id': ObjectId(person_id)})
+        if not person:
+            return jsonify({'success': False, 'error': 'Person not found'}), 404
+        
+        if delete_images:
+            # Delete all images associated with this person
+            from app.services.cloudinary_service import delete_image
+            
+            images = mongo.db.images.find({'person_id': ObjectId(person_id)})
+            for image in images:
+                delete_image(image.get('cloudinary_public_id'))
+            
+            mongo.db.images.delete_many({'person_id': ObjectId(person_id)})
+        else:
+            # Just unassign images from this person
+            mongo.db.images.update_many(
+                {'person_id': ObjectId(person_id)},
+                {'$set': {'person_id': None, 'is_identified': False, 'updated_at': datetime.utcnow()}}
+            )
+        
+        # Delete the person
+        mongo.db.people.delete_one({'_id': ObjectId(person_id)})
+        
+        return jsonify({
+            'success': True,
+            'message': f'Person deleted successfully. Images {"deleted" if delete_images else "unassigned"}.'
+        })
+        
+    except InvalidId:
+        return jsonify({'success': False, 'error': 'Invalid person ID'}), 400
+    except Exception as e:
+        return jsonify({'success': False, 'error': str(e)}), 500
+
+
+@people_bp.route('/<person_id>/images', methods=['GET'])
+def get_person_images(person_id):
+    """Get all images for a specific person."""
+    try:
+        person = mongo.db.people.find_one({'_id': ObjectId(person_id)})
+        if not person:
+            return jsonify({'success': False, 'error': 'Person not found'}), 404
+        
+        page = int(request.args.get('page', 1))
+        per_page = int(request.args.get('per_page', 20))
+        skip = (page - 1) * per_page
+        
+        images = list(
+            mongo.db.images.find({'person_id': ObjectId(person_id)})
+            .sort('created_at', -1)
+            .skip(skip)
+            .limit(per_page)
+        )
+        
+        total = mongo.db.images.count_documents({'person_id': ObjectId(person_id)})
+        
+        return jsonify({
+            'success': True,
+            'data': [ImageModel.to_response(img) for img in images],
+            'person': PersonModel.to_response(person),
+            'pagination': {
+                'page': page,
+                'per_page': per_page,
+                'total': total,
+                'pages': (total + per_page - 1) // per_page
+            }
+        })
+        
+    except InvalidId:
+        return jsonify({'success': False, 'error': 'Invalid person ID'}), 400
+    except Exception as e:
+        return jsonify({'success': False, 'error': str(e)}), 500

app/routes/stats.py

@@ -0,0 +1,110 @@
+"""Statistics and dashboard routes."""
+from flask import Blueprint, jsonify
+from datetime import datetime, timedelta
+
+from app import mongo
+from app.models import PersonModel, ImageModel
+
+stats_bp = Blueprint('stats', __name__)
+
+
+@stats_bp.route('', methods=['GET'])
+def get_stats():
+    """Get dashboard statistics."""
+    try:
+        # Count totals
+        total_images = mongo.db.images.count_documents({})
+        total_people = mongo.db.people.count_documents({})
+        identified_images = mongo.db.images.count_documents({'is_identified': True})
+        unidentified_faces = mongo.db.images.count_documents({
+            'has_face': True,
+            'is_identified': False
+        })
+        
+        # Calculate percentages
+        identification_rate = (identified_images / total_images * 100) if total_images > 0 else 0
+        
+        return jsonify({
+            'success': True,
+            'data': {
+                'total_images': total_images,
+                'total_people': total_people,
+                'identified_images': identified_images,
+                'unidentified_faces': unidentified_faces,
+                'identification_rate': round(identification_rate, 1)
+            }
+        })
+        
+    except Exception as e:
+        return jsonify({'success': False, 'error': str(e)}), 500
+
+
+@stats_bp.route('/recent', methods=['GET'])
+def get_recent():
+    """Get recent uploads."""
+    try:
+        # Get recent images (last 7 days)
+        week_ago = datetime.utcnow() - timedelta(days=7)
+        
+        recent_images = list(
+            mongo.db.images.find({'created_at': {'$gte': week_ago}})
+            .sort('created_at', -1)
+            .limit(12)
+        )
+        
+        # Get person info for identified images
+        person_ids = [img['person_id'] for img in recent_images if img.get('person_id')]
+        people = {str(p['_id']): p for p in mongo.db.people.find({'_id': {'$in': person_ids}})}
+        
+        for img in recent_images:
+            if img.get('person_id') and str(img['person_id']) in people:
+                img['person'] = people[str(img['person_id'])]
+        
+        return jsonify({
+            'success': True,
+            'data': [ImageModel.to_response(img, include_person=True) for img in recent_images]
+        })
+        
+    except Exception as e:
+        return jsonify({'success': False, 'error': str(e)}), 500
+
+
+@stats_bp.route('/unidentified', methods=['GET'])
+def get_unidentified():
+    """Get images with unidentified faces."""
+    try:
+        unidentified = list(
+            mongo.db.images.find({
+                'has_face': True,
+                'is_identified': False
+            })
+            .sort('created_at', -1)
+            .limit(12)
+        )
+        
+        return jsonify({
+            'success': True,
+            'data': [ImageModel.to_response(img) for img in unidentified]
+        })
+        
+    except Exception as e:
+        return jsonify({'success': False, 'error': str(e)}), 500
+
+
+@stats_bp.route('/people-summary', methods=['GET'])
+def get_people_summary():
+    """Get people with most images."""
+    try:
+        people = list(
+            mongo.db.people.find()
+            .sort('image_count', -1)
+            .limit(8)
+        )
+        
+        return jsonify({
+            'success': True,
+            'data': [PersonModel.to_response(p) for p in people]
+        })
+        
+    except Exception as e:
+        return jsonify({'success': False, 'error': str(e)}), 500

app/services/__init__.py

@@ -0,0 +1,12 @@
+"""Services package."""
+from .cloudinary_service import upload_image, delete_image, get_thumbnail_url, init_cloudinary
+from .face_recognition_service import FaceRecognitionService, get_face_service
+
+__all__ = [
+    'upload_image',
+    'delete_image', 
+    'get_thumbnail_url',
+    'init_cloudinary',
+    'FaceRecognitionService',
+    'get_face_service'
+]

app/services/cloudinary_service.py

@@ -0,0 +1,97 @@
+"""Cloudinary service for image uploads and management."""
+import cloudinary
+import cloudinary.uploader
+import cloudinary.api
+from werkzeug.utils import secure_filename
+
+
+def init_cloudinary(config):
+    """Initialize Cloudinary with configuration."""
+    cloudinary.config(
+        cloud_name=config.get('CLOUDINARY_CLOUD_NAME'),
+        api_key=config.get('CLOUDINARY_API_KEY'),
+        api_secret=config.get('CLOUDINARY_API_SECRET'),
+        secure=True
+    )
+
+
+def upload_image(file, folder='image-organizer'):
+    """
+    Upload an image to Cloudinary.
+    
+    Args:
+        file: File object or file path
+        folder: Cloudinary folder to store the image
+        
+    Returns:
+        dict: Upload result containing url and public_id
+    """
+    try:
+        result = cloudinary.uploader.upload(
+            file,
+            folder=folder,
+            resource_type='image',
+            transformation=[
+                {'quality': 'auto:good'},
+                {'fetch_format': 'auto'}
+            ]
+        )
+        return {
+            'success': True,
+            'url': result['secure_url'],
+            'public_id': result['public_id'],
+            'width': result.get('width'),
+            'height': result.get('height'),
+            'format': result.get('format')
+        }
+    except Exception as e:
+        return {
+            'success': False,
+            'error': str(e)
+        }
+
+
+def delete_image(public_id):
+    """
+    Delete an image from Cloudinary.
+    
+    Args:
+        public_id: Cloudinary public ID of the image
+        
+    Returns:
+        dict: Deletion result
+    """
+    try:
+        result = cloudinary.uploader.destroy(public_id)
+        return {
+            'success': result.get('result') == 'ok',
+            'result': result
+        }
+    except Exception as e:
+        return {
+            'success': False,
+            'error': str(e)
+        }
+
+
+def get_thumbnail_url(url, width=200, height=200):
+    """
+    Generate a thumbnail URL for an image.
+    
+    Args:
+        url: Original Cloudinary URL
+        width: Thumbnail width
+        height: Thumbnail height
+        
+    Returns:
+        str: Thumbnail URL
+    """
+    if not url:
+        return None
+    
+    # Insert transformation into Cloudinary URL
+    parts = url.split('/upload/')
+    if len(parts) == 2:
+        transformation = f'c_fill,w_{width},h_{height},g_face'
+        return f'{parts[0]}/upload/{transformation}/{parts[1]}'
+    return url

app/services/face_recognition_service.py

@@ -0,0 +1,155 @@
+"""Face recognition service for detecting and matching faces."""
+import face_recognition
+import numpy as np
+from io import BytesIO
+from PIL import Image
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class FaceRecognitionService:
+    """Service for face detection and recognition."""
+    
+    def __init__(self, tolerance=0.6):
+        """
+        Initialize the face recognition service.
+        
+        Args:
+            tolerance: How much distance between faces to consider it a match.
+                      Lower is stricter. 0.6 is typical best performance.
+        """
+        self.tolerance = tolerance
+    
+    def detect_faces(self, image_data):
+        """
+        Detect faces in an image.
+        
+        Args:
+            image_data: Image file data (bytes or file-like object)
+            
+        Returns:
+            dict: Contains face_encodings (list) and face_locations (list)
+        """
+        try:
+            # Load image
+            if isinstance(image_data, bytes):
+                image = face_recognition.load_image_file(BytesIO(image_data))
+            else:
+                image_data.seek(0)
+                image = face_recognition.load_image_file(image_data)
+            
+            # Detect face locations
+            face_locations = face_recognition.face_locations(image, model='hog')
+            
+            if not face_locations:
+                return {
+                    'success': True,
+                    'face_encodings': [],
+                    'face_locations': [],
+                    'face_count': 0
+                }
+            
+            # Get face encodings
+            face_encodings = face_recognition.face_encodings(image, face_locations)
+            
+            # Convert to serializable format
+            encodings_list = [encoding.tolist() for encoding in face_encodings]
+            locations_list = [list(loc) for loc in face_locations]
+            
+            return {
+                'success': True,
+                'face_encodings': encodings_list,
+                'face_locations': locations_list,
+                'face_count': len(face_locations)
+            }
+            
+        except Exception as e:
+            logger.error(f"Face detection error: {str(e)}")
+            return {
+                'success': False,
+                'error': str(e),
+                'face_encodings': [],
+                'face_locations': [],
+                'face_count': 0
+            }
+    
+    def find_matching_person(self, face_encoding, people):
+        """
+        Find a matching person for a face encoding.
+        
+        Args:
+            face_encoding: The face encoding to match (list)
+            people: List of person documents with face_encodings
+            
+        Returns:
+            ObjectId or None: The matched person's ID or None
+        """
+        if not face_encoding or not people:
+            return None
+        
+        target_encoding = np.array(face_encoding)
+        best_match = None
+        best_distance = float('inf')
+        
+        for person in people:
+            person_encodings = person.get('face_encodings', [])
+            
+            for stored_encoding in person_encodings:
+                if not stored_encoding:
+                    continue
+                    
+                stored_np = np.array(stored_encoding)
+                
+                # Calculate face distance
+                distance = np.linalg.norm(target_encoding - stored_np)
+                
+                if distance < self.tolerance and distance < best_distance:
+                    best_distance = distance
+                    best_match = person['_id']
+        
+        return best_match
+    
+    def compare_faces(self, encoding1, encoding2):
+        """
+        Compare two face encodings.
+        
+        Args:
+            encoding1: First face encoding (list)
+            encoding2: Second face encoding (list)
+            
+        Returns:
+            dict: Contains 'match' (bool) and 'distance' (float)
+        """
+        try:
+            enc1 = np.array(encoding1)
+            enc2 = np.array(encoding2)
+            
+            distance = np.linalg.norm(enc1 - enc2)
+            is_match = distance <= self.tolerance
+            
+            return {
+                'match': is_match,
+                'distance': float(distance),
+                'confidence': max(0, 1 - (distance / self.tolerance)) if is_match else 0
+            }
+        except Exception as e:
+            logger.error(f"Face comparison error: {str(e)}")
+            return {
+                'match': False,
+                'distance': float('inf'),
+                'confidence': 0,
+                'error': str(e)
+            }
+
+
+# Global service instance
+face_service = None
+
+
+def get_face_service(tolerance=0.6):
+    """Get or create the face recognition service instance."""
+    global face_service
+    if face_service is None:
+        face_service = FaceRecognitionService(tolerance)
+    return face_service

config.py

@@ -0,0 +1,46 @@
+"""Application configuration."""
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+class Config:
+    """Base configuration."""
+    SECRET_KEY = os.environ.get('SECRET_KEY', 'dev-secret-key')
+    MONGO_URI = os.environ.get('MONGODB_URI')
+    
+    # Cloudinary settings
+    CLOUDINARY_CLOUD_NAME = os.environ.get('CLOUDINARY_CLOUD_NAME')
+    CLOUDINARY_API_KEY = os.environ.get('CLOUDINARY_API_KEY')
+    CLOUDINARY_API_SECRET = os.environ.get('CLOUDINARY_API_SECRET')
+    
+    # Face recognition settings
+    FACE_RECOGNITION_TOLERANCE = float(os.environ.get('FACE_RECOGNITION_TOLERANCE', 0.6))
+    
+    # File upload settings
+    MAX_CONTENT_LENGTH = 16 * 1024 * 1024  # 16MB
+    ALLOWED_EXTENSIONS = {'png', 'jpg', 'jpeg', 'gif', 'webp'}
+
+
+class DevelopmentConfig(Config):
+    """Development configuration."""
+    DEBUG = True
+
+
+class ProductionConfig(Config):
+    """Production configuration."""
+    DEBUG = False
+
+
+class TestingConfig(Config):
+    """Testing configuration."""
+    TESTING = True
+
+
+config = {
+    'development': DevelopmentConfig,
+    'production': ProductionConfig,
+    'testing': TestingConfig,
+    'default': DevelopmentConfig
+}

requirements.txt

@@ -0,0 +1,23 @@
+# Flask and extensions
+Flask==3.0.0
+Flask-CORS==4.0.0
+Flask-PyMongo==2.3.0
+python-dotenv==1.0.0
+
+# MongoDB
+pymongo==4.6.1
+dnspython==2.4.2
+
+# Face Recognition
+face-recognition==1.3.0
+numpy==1.26.2
+Pillow==10.1.0
+
+# Cloudinary
+cloudinary==1.37.0
+
+# Utilities
+Werkzeug==3.0.1
+gunicorn==21.2.0
+python-dateutil==2.8.2
+requests==2.32.5

run.py

@@ -0,0 +1,7 @@
+"""Application entry point."""
+from app import create_app
+
+app = create_app()
+
+if __name__ == '__main__':
+    app.run(host='0.0.0.0', port=5000, debug=True)