punimtag/docs/tech.md

PunimTag Technical Architecture

Technology Stack

Backend

• Framework: Flask (Python web framework)
• Database: SQLite (lightweight, file-based)
• Face Recognition: dlib (C++ library with Python bindings)
• Image Processing: Pillow (PIL fork)
• Data Processing: NumPy (numerical operations)

Frontend

• Language: Vanilla JavaScript (ES6+)
• Styling: CSS3 with Grid/Flexbox
• HTTP Client: Fetch API
• Progressive Loading: Intersection Observer API
• No Frameworks: Pure JavaScript for simplicity

Development Tools

• Version Control: Git
• Package Management: pip (Python), npm (optional for frontend tools)
• Testing: pytest (Python), Jest (JavaScript)
• Code Quality: flake8, black (Python), ESLint (JavaScript)

Core Technologies

Face Recognition Pipeline

1. Image Loading: Pillow for image processing
2. Face Detection: dlib's CNN face detector
3. Feature Extraction: dlib's 128-dimensional face encodings
4. Similarity Matching: Euclidean distance calculation
5. Storage: Binary encoding storage in SQLite

Database Schema

-- Core tables
images (id, filename, path, date_taken, metadata)
faces (id, image_id, person_id, encoding, coordinates, confidence)
people (id, name, created_date)
tags (id, name)
image_tags (image_id, tag_id)

-- Supporting tables
face_encodings (id, face_id, encoding_data)
photo_metadata (image_id, exif_data, gps_data)

API Design

• RESTful Endpoints: Standard HTTP methods (GET, POST, DELETE)
• JSON Responses: Consistent response format
• Error Handling: HTTP status codes with descriptive messages
• Pagination: Offset-based for large datasets

Performance Considerations4

Image Processing

• Thumbnail Generation: On-demand with caching
• Face Detection: Optimized for speed vs accuracy
• Batch Processing: Efficient handling of large photo sets
• Memory Management: Streaming for large images

Database Optimization

• Indexing: Strategic indexes on frequently queried columns
• Connection Pooling: Efficient database connections
• Query Optimization: Minimize N+1 query problems
• Data Archiving: Move old data to separate tables

Frontend Performance

• Progressive Loading: Load data in chunks
• Image Lazy Loading: Load images as they become visible
• Caching: Browser caching for static assets
• Debouncing: Prevent excessive API calls

Security Considerations

Data Protection

• Local Storage: No cloud dependencies
• Input Validation: Sanitize all user inputs
• SQL Injection Prevention: Parameterized queries
• File Upload Security: Validate file types and sizes

Privacy

• Face Data: Stored locally, not shared
• Metadata: User controls what's stored
• Access Control: Local access only
• Data Export: User can export/delete their data

Scalability

Current Limitations

• Single User: Designed for personal use
• Local Storage: Limited by disk space
• Processing Power: CPU-intensive face recognition
• Memory: Large photo collections require significant RAM

Future Scalability

• Multi-User Support: Database schema supports multiple users
• Cloud Integration: Optional cloud storage and processing
• Distributed Processing: GPU acceleration for face recognition
• Microservices: Separate services for different functions

Development Workflow

Code Organization

• Modular Design: Separate concerns into modules
• Configuration Management: Environment-based settings
• Error Handling: Comprehensive error catching and logging
• Documentation: Inline code documentation

Testing Strategy

• Unit Tests: Test individual functions and classes
• Integration Tests: Test API endpoints and database operations
• End-to-End Tests: Test complete user workflows
• Performance Tests: Test with large datasets

Deployment

• Local Development: Flask development server
• Production: WSGI server (Gunicorn) with reverse proxy
• Containerization: Docker for consistent environments
• Monitoring: Logging and health checks