punimtag/docs/ARCHITECTURE.md

PunimTag - Project Architecture

Version: 2.0
Last Updated: January 6, 2026
Status: Production Ready - Web Application with DeepFace

---

Table of Contents

1. System Overview
2. Architecture Diagram
3. Layer Architecture
4. Core Components
5. Database Schema
6. GUI Architecture
7. Data Flow
8. Technology Stack
9. File Structure
10. Design Patterns
11. Future Considerations

---

1. System Overview

Purpose

PunimTag is a modern web-based photo management and tagging application with advanced facial recognition capabilities. It allows users to:

• Import and organize photos from folders (including network shares)
• Automatically detect and identify faces using DeepFace AI
• Tag photos with custom metadata
• Search photos by people, dates, tags, and other criteria
• Manage identified people and their relationships
• Access via web browser (admin interface) or public viewer interface

Key Features

• Web-Based Architecture: Modern React admin interface and Next.js viewer
• Face Detection & Recognition: DeepFace with RetinaFace detection and ArcFace recognition
• Smart Tagging: Hierarchical tag system with bulk operations
• Advanced Search: Multi-criteria search with date ranges, tags, and people
• Auto-Matching: Intelligent face matching with quality scoring and confidence calibration
• Batch Processing: Process thousands of photos efficiently with background jobs
• Video Support: Process and identify people in videos
• Role-Based Access Control: Multi-user support with permissions

---

2. Architecture Diagram

┌─────────────────────────────────────────────────────────────────────────┐
│                         PRESENTATION LAYER                               │
│  ┌──────────────────────────────┬──────────────────────────────────┐  │
│  │   Admin Frontend (React)      │   Viewer Frontend (Next.js)      │  │
│  │   ┌────────────────────────┐  │   ┌──────────────────────────┐   │  │
│  │   │ Scan Page              │  │   │ Photo Viewer            │   │  │
│  │   │ Search Page            │  │   │ Tag Management          │   │  │
│  │   │ Identify Page          │  │   │ Person Display          │   │  │
│  │   │ AutoMatch Page         │  │   └──────────────────────────┘   │  │
│  │   │ Modify Page            │  │                                 │  │
│  │   │ Tags Page              │  │                                 │  │
│  │   │ User Management        │  │                                 │  │
│  │   └────────────────────────┘  │                                 │  │
│  └──────────────────────────────┴──────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘
                                    ↕ HTTP/REST API
┌─────────────────────────────────────────────────────────────────────────┐
│                         API LAYER (FastAPI)                              │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │  API Routers:                                                    │   │
│  │  • /api/v1/auth          • /api/v1/photos                       │   │
│  │  • /api/v1/faces         • /api/v1/people                        │   │
│  │  • /api/v1/tags          • /api/v1/jobs                         │   │
│  │  • /api/v1/users         • /api/v1/videos                       │   │
│  └──────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
                                    ↕
┌─────────────────────────────────────────────────────────────────────────┐
│                      BUSINESS LOGIC LAYER                                │
│  ┌──────────────────┬──────────────────┬──────────────────────────┐  │
│  │  Face Service     │  Photo Service   │   Tag Service            │  │
│  │  (DeepFace)       │  (EXIF, Import)  │   (CRUD, Bulk Ops)       │  │
│  │                   │                  │                          │  │
│  │ • Face Detection  │ • Photo Scanning │ • Tag CRUD                │  │
│  │ • ArcFace Encoding│ • EXIF Reading   │ • Bulk Operations        │  │
│  │ • Similarity      │ • File Ops       │ • Tag Validation         │  │
│  │ • Quality Score   │ • Metadata       │ • Deduplication          │  │
│  └──────────────────┴──────────────────┴──────────────────────────┘  │
│                                                                          │
│  ┌──────────────────┬──────────────────┬──────────────────────────┐  │
│  │  Search Service  │  Video Service    │   Auth Service            │  │
│  │  (Multi-criteria)│  (Video Processing)│   (JWT, RBAC)             │  │
│  └──────────────────┴──────────────────┴──────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘
                                    ↕
┌─────────────────────────────────────────────────────────────────────────┐
│                       DATA ACCESS LAYER                                  │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │           SQLAlchemy ORM (Session Management)                    │   │
│  │                                                                   │   │
│  │  • Connection pooling    • Transaction management               │   │
│  │  • Schema management     • CRUD operations                      │   │
│  │  • Query optimization    • Data integrity                      │   │
│  └──────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
                                    ↕
┌─────────────────────────────────────────────────────────────────────────┐
│                        PERSISTENCE LAYER                                 │
│  ┌──────────────────────────────┬──────────────────────────────────┐   │
│  │   Main Database (PostgreSQL)  │   Auth Database (PostgreSQL)     │   │
│  │   ┌────────────────────────┐ │   ┌──────────────────────────┐   │   │
│  │   │ photos                 │ │   │ users                    │   │   │
│  │   │ faces                  │ │   │ pending_photos           │   │   │
│  │   │ people                 │ │   │ pending_identifications  │   │   │
│  │   │ tags                   │ │   │ inappropriate_photo_       │   │   │
│  │   │ phototaglinkage        │ │   │   reports                │   │   │
│  │   │ users                  │ │   └──────────────────────────┘   │   │
│  │   │ role_permissions       │ │                                 │   │
│  │   └────────────────────────┘ │                                 │   │
│  └──────────────────────────────┴──────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────┐
│                      EXTERNAL SERVICES                                   │
│  ┌──────────────────┬──────────────────┬──────────────────────────┐   │
│  │  Redis           │  DeepFace         │   Background Jobs (RQ)   │   │
│  │  (Job Queue)     │  (AI Models)      │   • Face Processing      │   │
│  │                  │                   │   • Photo Import         │   │
│  │                  │                   │   • Video Processing     │   │
│  └──────────────────┴──────────────────┴──────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘

---

3. Layer Architecture

3.1 Presentation Layer

Responsibility: User interface and interaction

Components:

• dashboard_gui.py - Main window and navigation
• identify_panel.py - Face identification interface
• auto_match_panel.py - Automatic face matching UI
• modify_panel.py - Person management interface
• tag_manager_panel.py - Tag management interface
• search_gui.py - Search functionality (legacy, integrated into dashboard)
• gui_core.py - Shared GUI utilities and widgets

Characteristics:

• Tkinter-based GUI
• Event-driven architecture
• Panel-based modular design
• Responsive layout with grid system
• Window size persistence

3.2 Business Logic Layer

Responsibility: Core application logic and algorithms

Components:

Face Processing (face_processing.py)

• FaceProcessor Class: Main face processing engine
  • Face detection using face_recognition library
  • Face encoding generation (128-dimensional vectors)
  • Face similarity calculation (Euclidean distance)
  • Quality scoring (size, sharpness, brightness, contrast, position)
  • Adaptive tolerance based on quality
  • Face crop extraction and caching
  • Multi-encoding support per person

Photo Management (photo_management.py)

• PhotoManager Class: Photo file operations
  • Folder scanning (recursive/non-recursive)
  • EXIF metadata extraction (date taken, camera info)
  • Photo validation and verification
  • Dimension and format detection
  • File system operations
  • Path normalization and validation

Tag Management (tag_management.py)

• TagManager Class: Tag operations
  • Tag CRUD operations
  • Bulk tag assignment
  • Tag deduplication (case-insensitive)
  • Tag parsing from comma-separated strings
  • Tag validation
  • Common tag detection across photos

Search & Statistics (search_stats.py)

• SearchStats Class: Advanced search and analytics
  • Multi-criteria search
  • Date range filtering
  • Tag-based queries (ANY/ALL matching)
  • Person-based search
  • Statistical analysis
  • Folder filtering

3.3 Data Access Layer

Responsibility: Database operations and query management

Component:

• database.py - DatabaseManager Class

Key Features:

• Connection pooling with thread-safety
• Context manager for transaction handling
• Schema initialization and migrations
• CRUD operations for all entities
• Query optimization with indices
• Prepared statements for security
• Case-insensitive queries where appropriate

3.4 Persistence Layer

Responsibility: Data storage

Technology: SQLite database Location: data/photos.db

---

4. Core Components

4.1 FaceProcessor

class FaceProcessor:
    """Handles face detection, encoding, and matching operations"""
    
    Key Methods:
    - process_faces(): Detect faces in unprocessed photos
    - find_similar_faces(): Find matching faces across photos
    - _calculate_face_quality_score(): Multi-factor quality assessment
    - _calculate_adaptive_tolerance(): Dynamic matching threshold
    - _extract_face_crop(): Extract and cache face thumbnails
    - _calculate_cosine_similarity(): Face similarity metric
    
    Features:
    - LRU caching for encodings
    - Progressive processing with callbacks
    - Cooperative cancellation support
    - Quality-based ranking

4.2 DatabaseManager

class DatabaseManager:
    """Handles all database operations"""
    
    Key Methods:
    - init_database(): Create schema with indices
    - add_photo/face/person/tag(): Entity creation
    - update_face_person(): Link faces to people
    - get_unidentified_faces(): Query unmatched faces
    - get_statistics(): System metrics
    
    Features:
    - Thread-safe connection pooling
    - Automatic transaction management
    - Case-insensitive tag/person lookups
    - Optimized indices for performance

4.3 PhotoManager

class PhotoManager:
    """Handles photo scanning and metadata"""
    
    Key Methods:
    - scan_folder(): Import photos from filesystem
    - extract_photo_date(): Parse EXIF timestamps
    - validate_photo_file(): Verify file integrity
    - get_photo_exif_data(): Extract metadata
    
    Features:
    - Recursive folder scanning
    - Duplicate detection
    - EXIF date parsing (multiple formats)
    - Path normalization

4.4 TagManager

class TagManager:
    """Handles tag operations"""
    
    Key Methods:
    - add_tags_to_photo(): Single photo tagging
    - parse_tags_string(): Parse comma-separated tags
    - deduplicate_tags(): Remove duplicates (case-insensitive)
    - get_photos_by_tags(): Query by tags (ANY/ALL)
    
    Features:
    - Case-insensitive tag handling
    - Automatic deduplication
    - Tag validation
    - Bulk operations support

---

5. Database Schema

5.1 Entity Relationship Diagram

┌─────────────┐         ┌─────────────┐         ┌─────────────┐
│   photos    │1      N │    faces    │N      1 │   people    │
│─────────────│◄────────│─────────────│────────►│─────────────│
│ id (PK)     │         │ id (PK)     │         │ id (PK)     │
│ path        │         │ photo_id(FK)│         │ first_name  │
│ filename    │         │ person_id   │         │ last_name   │
│ date_added  │         │ encoding    │         │ middle_name │
│ date_taken  │         │ location    │         │ maiden_name │
│ processed   │         │ confidence  │         │ date_of_    │
└─────────────┘         │ quality_    │         │   birth     │
                        │   score     │         │ created_    │
                        └─────────────┘         │   date      │
                              │                 └─────────────┘
                              │                        │
                              │1                       │1
                              │                        │
                              │N                       │N
                        ┌─────▼────────┐               │
                        │   person_    │               │
                        │   encodings  │               │
                        │──────────────│               │
                        │ id (PK)      │               │
                        │ person_id(FK)├───────────────┘
                        │ face_id (FK) │
                        │ encoding     │
                        │ quality_score│
                        │ created_date │
                        └──────────────┘

┌─────────────┐         ┌─────────────┐         ┌─────────────┐
│    tags     │1      N │   phototag  │N      1 │   photos    │
│─────────────│◄────────│  linkage    │────────►│─────────────│
│ id (PK)     │         │─────────────│         │ (see above) │
│ tag_name    │         │ linkage_id  │         └─────────────┘
│ created_    │         │   (PK)      │
│   date      │         │ photo_id(FK)│
└─────────────┘         │ tag_id (FK) │
                        │ linkage_type│
                        │ created_date│
                        └─────────────┘

5.2 Table Definitions

photos

CREATE TABLE photos (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    path TEXT UNIQUE NOT NULL,
    filename TEXT NOT NULL,
    date_added DATETIME DEFAULT CURRENT_TIMESTAMP,
    date_taken DATE,
    processed BOOLEAN DEFAULT 0,
    file_hash TEXT NOT NULL
);
CREATE INDEX idx_photos_file_hash ON photos(file_hash);

people

CREATE TABLE people (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    first_name TEXT NOT NULL,
    last_name TEXT NOT NULL,
    middle_name TEXT,
    maiden_name TEXT,
    date_of_birth DATE,
    created_date DATETIME DEFAULT CURRENT_TIMESTAMP,
    UNIQUE(first_name, last_name, middle_name, maiden_name, date_of_birth)
);

faces

CREATE TABLE faces (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    photo_id INTEGER NOT NULL,
    person_id INTEGER,
    encoding BLOB NOT NULL,              -- 1024 bytes (128 floats × 8)
    location TEXT NOT NULL,              -- "(top, right, bottom, left)"
    confidence REAL DEFAULT 0.0,
    quality_score REAL DEFAULT 0.0,     -- 0.0 to 1.0
    is_primary_encoding BOOLEAN DEFAULT 0,
    FOREIGN KEY (photo_id) REFERENCES photos (id),
    FOREIGN KEY (person_id) REFERENCES people (id)
);

person_encodings

CREATE TABLE person_encodings (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    person_id INTEGER NOT NULL,
    face_id INTEGER NOT NULL,
    encoding BLOB NOT NULL,
    quality_score REAL DEFAULT 0.0,
    created_date DATETIME DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (person_id) REFERENCES people (id),
    FOREIGN KEY (face_id) REFERENCES faces (id)
);

tags

CREATE TABLE tags (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    tag_name TEXT UNIQUE NOT NULL,
    created_date DATETIME DEFAULT CURRENT_TIMESTAMP
);

phototaglinkage

CREATE TABLE phototaglinkage (
    linkage_id INTEGER PRIMARY KEY AUTOINCREMENT,
    photo_id INTEGER NOT NULL,
    tag_id INTEGER NOT NULL,
    linkage_type INTEGER NOT NULL DEFAULT 0,  -- 0=single, 1=bulk
    created_date DATETIME DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (photo_id) REFERENCES photos (id),
    FOREIGN KEY (tag_id) REFERENCES tags (id),
    UNIQUE(photo_id, tag_id)
);

5.3 Indices

CREATE INDEX idx_faces_person_id ON faces(person_id);
CREATE INDEX idx_faces_photo_id ON faces(photo_id);
CREATE INDEX idx_photos_processed ON photos(processed);
CREATE INDEX idx_faces_quality ON faces(quality_score);
CREATE INDEX idx_person_encodings_person_id ON person_encodings(person_id);
CREATE INDEX idx_person_encodings_quality ON person_encodings(quality_score);
CREATE INDEX idx_photos_date_taken ON photos(date_taken);
CREATE INDEX idx_photos_date_added ON photos(date_added);

---

6. GUI Architecture

6.1 Dashboard Structure

dashboard_gui.py (Main Window)
│
├── Menu Bar
│   ├── File
│   ├── Edit
│   ├── View
│   └── Help
│
├── Toolbar (Quick Actions)
│
├── Notebook (Tabbed Interface)
│   ├── Search Panel (search_gui integrated)
│   ├── Identify Panel (identify_panel.py)
│   ├── Auto-Match Panel (auto_match_panel.py)
│   ├── Modify Panel (modify_panel.py)
│   └── Tag Manager Panel (tag_manager_panel.py)
│
└── Status Bar
    ├── Progress indicator
    ├── Statistics display
    └── Current operation status

6.2 Panel Architecture

Each panel follows this pattern:

class SomePanel:
    def __init__(self, parent_frame, db_manager, other_managers, gui_core):
        self.parent_frame = parent_frame
        self.db = db_manager
        # ... other dependencies
    
    def create_panel(self) -> ttk.Frame:
        """Create and return the panel widget"""
        panel = ttk.Frame(self.parent_frame)
        # Build UI
        return panel
    
    def refresh(self):
        """Refresh panel data"""
        pass
    
    def cleanup(self):
        """Clean up resources"""
        pass

6.3 Event Flow

User Action → GUI Event Handler → Business Logic → Database → Update UI
     ↓
  Validation
     ↓
  Error Handling
     ↓
  User Feedback

---

7. Data Flow

7.1 Photo Import Flow

1. User selects folder
2. PhotoManager.scan_folder()
3. For each image file:
   a. Extract EXIF metadata
   b. DatabaseManager.add_photo()
   c. Update UI with progress
4. Display summary statistics

7.2 Face Processing Flow

1. User triggers face processing
2. FaceProcessor.process_faces()
3. For each unprocessed photo:
   a. Load image with face_recognition
   b. Detect face locations (HOG/CNN)
   c. Generate face encodings (128-dim)
   d. Calculate quality scores
   e. DatabaseManager.add_face()
   f. Update progress callback
4. Mark photos as processed
5. Refresh UI

7.3 Face Identification Flow

1. User opens Identify panel
2. Load unidentified faces (ordered by quality)
3. For each face:
   a. Display face thumbnail
   b. FaceProcessor.find_similar_faces()
   c. Show similar identified faces
   d. User selects person or creates new
   e. DatabaseManager.update_face_person()
   f. Update person_encodings table
4. Move to next face
5. Update statistics

7.4 Auto-Match Flow

1. User triggers auto-match
2. For each unidentified face:
   a. Compare with all identified faces
   b. Calculate similarity (face_distance)
   c. Apply adaptive tolerance
   d. Filter by quality scores
   e. Rank matches by confidence
3. Display matches with confidence %
4. User confirms or rejects matches
5. Bulk update database
6. Refresh UI

7.5 Search Flow

1. User enters search criteria
2. SearchStats builds query based on:
   - Person name (fuzzy match)
   - Date range (from/to)
   - Tags (ANY/ALL matching)
   - Folder location
3. Execute optimized SQL query
4. Load photos in batches
5. Display results in grid/list
6. Support sorting and filtering

---

8. Technology Stack

8.1 Core Dependencies

Current Stack:

• Python 3.12+: Main language
• Tkinter: GUI framework (built-in)
• SQLite3: Database (built-in)
• face_recognition 1.3.0: Face detection & encoding
• dlib: ML backend for face_recognition
• NumPy: Numerical operations
• Pillow (PIL): Image processing
• Click: CLI framework (legacy)

Planned Migration:

• DeepFace 0.0.79+: Advanced face recognition
• TensorFlow 2.13+: Deep learning backend
• OpenCV: Image processing
• RetinaFace: Face detection backend

8.2 Development Tools

• Git: Version control
• venv: Virtual environment
• pip: Package management

8.3 File Formats

• Images: JPG, JPEG, PNG, BMP, TIFF, TIF
• Database: SQLite (.db)
• Config: JSON (.json)
• Code: Python (.py)

---

9. File Structure

punimtag/
├── Core Application
│   ├── dashboard_gui.py          # Main unified dashboard
│   ├── photo_tagger.py           # Legacy CLI entry point
│   └── config.py                 # Configuration constants
│
├── Business Logic
│   ├── face_processing.py        # Face detection/recognition
│   ├── photo_management.py       # Photo file operations
│   ├── tag_management.py         # Tag operations
│   └── search_stats.py           # Search and statistics
│
├── Data Access
│   └── database.py               # Database manager
│
├── GUI Components
│   ├── gui_core.py               # Common GUI utilities
│   ├── identify_panel.py         # Face identification UI
│   ├── auto_match_panel.py       # Auto-matching UI
│   ├── modify_panel.py           # Person modification UI
│   ├── tag_manager_panel.py      # Tag management UI
│   └── search_gui.py             # Legacy search (integrated)
│
├── Utilities
│   ├── path_utils.py             # Path normalization
│   └── gui_config.json           # GUI preferences
│
├── Database
│   └── data/
│       └── photos.db             # SQLite database
│
├── Testing
│   ├── test_deepface_gui.py     # DeepFace testing
│   ├── test_face_recognition.py # Face rec testing
│   ├── debug_face_detection.py  # Debug utilities
│   └── demo_photos/              # Test images
│
├── Scripts
│   └── scripts/
│       └── drop_all_tables.py    # Database utilities
│
├── Documentation
│   ├── README.md                 # Main documentation
│   ├── DEMO.md                   # Demo guide
│   └── README_UNIFIED_DASHBOARD.md
│
└── Configuration
    ├── requirements.txt          # Python dependencies
    ├── setup.py                  # Package setup
    └── venv/                     # Virtual environment

---

10. Design Patterns

10.1 Patterns Used

Manager Pattern

• DatabaseManager: Centralized database access
• PhotoManager: Photo operations
• TagManager: Tag operations
• FaceProcessor: Face processing operations

Repository Pattern

• Database layer abstracts SQL from business logic
• All data access goes through DatabaseManager

Panel/Component Pattern

• Each GUI panel is self-contained
• Consistent interface: create_panel(), refresh(), cleanup()

Observer Pattern

• Progress callbacks during long operations
• UI updates when data changes

Strategy Pattern

• Different face detection models (HOG/CNN)
• Configurable similarity thresholds
• Multiple tag matching modes (ANY/ALL)

Singleton Pattern

• DatabaseManager maintains single connection pool
• GUICore provides shared utilities

Factory Pattern

• Panel creation in dashboard
• Face crop generation

10.2 Principles Applied

SOLID Principles

• Single Responsibility: Each class has one clear purpose
• Open/Closed: Extendable without modification (panels)
• Liskov Substitution: Panels can be swapped
• Interface Segregation: Minimal required interfaces
• Dependency Inversion: Depends on abstractions (managers)

DRY (Don't Repeat Yourself)

• Shared utilities in gui_core.py
• Common database operations in DatabaseManager
• Reusable face processing functions

Separation of Concerns

• Presentation (GUI) separate from logic
• Business logic separate from data access
• Database abstraction from SQL

---

11. Future Considerations

11.1 Planned Enhancements

DeepFace Migration (In Progress)

• Replace face_recognition with DeepFace
• Support multiple detection backends (RetinaFace, MTCNN, SSD)
• Use ArcFace model for better accuracy
• 512-dimensional encodings (vs 128)
• Cosine similarity metric

Web Interface

• Current GUI designed with web migration in mind
• Panel-based architecture maps to web pages
• REST API for backend
• React/Vue frontend

Cloud Storage

• Support for cloud photo storage
• S3/Google Drive integration
• Remote database sync

Advanced Features

• Video face detection
• Face clustering (unsupervised grouping)
• Age progression tracking
• Photo similarity (beyond faces)
• Timeline visualization
• Map view with geolocation

11.2 Scalability Considerations

Database

• Consider PostgreSQL for larger datasets (>100K photos)
• Implement database sharding
• Add read replicas for queries

Performance

• Implement face encoding caching
• Use GPU acceleration for processing
• Add background job queue
• Implement lazy loading in UI

Architecture

• Microservices for face processing
• Message queue for async operations
• Containerization (Docker)
• Kubernetes orchestration

11.3 Known Limitations

Current Constraints

• Single-user desktop application
• No concurrent user support
• Limited to local storage
• Face recognition accuracy depends on photo quality
• Processing speed limited by CPU (no GPU support yet)
• Large databases (>50K photos) may slow down

Technical Debt

• Legacy CLI code needs cleanup
• Some database methods incomplete (marked with TODO)
• Inconsistent error handling in places
• Limited test coverage
• Documentation gaps in some modules

---

12. Configuration & Customization

12.1 Configuration Files

config.py

# Database
DEFAULT_DB_PATH = "data/photos.db"
DB_TIMEOUT = 30.0

# Face Detection
DEFAULT_FACE_DETECTION_MODEL = "hog"  # or "cnn"
DEFAULT_FACE_TOLERANCE = 0.6
MIN_FACE_QUALITY = 0.3

# GUI
FACE_CROP_SIZE = 100
ICON_SIZE = 20
MAX_SUGGESTIONS = 10

# Processing
DEFAULT_BATCH_SIZE = 20
DEFAULT_PROCESSING_LIMIT = 50

gui_config.json

{
    "window_size": "1400x900",
    "last_folder": "/path/to/photos",
    "theme": "default"
}

12.2 Customization Points

• Face detection model (HOG vs CNN)
• Similarity tolerance
• Quality thresholds
• Batch sizes
• UI themes (planned)
• Keyboard shortcuts (planned)

---

13. Security & Privacy

13.1 Current Security Measures

• Local-only storage (no cloud by default)
• SQL injection prevention (prepared statements)
• Path validation and normalization
• File type validation

13.2 Privacy Considerations

• Face encodings stored locally
• No external API calls (except DeepFace model downloads)
• User controls all data
• No telemetry or analytics

13.3 Future Security Enhancements

• Database encryption at rest
• User authentication (multi-user support)
• Encrypted backups
• Audit logging
• GDPR compliance features (data export/deletion)

---

14. Maintenance & Support

14.1 Monitoring

• Database statistics (get_statistics())
• Processing metrics (timing, success/failure rates)
• Quality score distribution
• Storage usage tracking (planned)

14.2 Backup & Recovery

• Manual database backup (copy photos.db)
• Planned: Automated backup scheduling
• Planned: Point-in-time recovery
• Planned: Export to portable format

14.3 Debugging

• Verbose logging levels (0-3)
• Debug scripts in project root
• Error tracking in UI
• Database query logging (planned)

---

15. Development Workflow

15.1 Adding New Features

1. Design: Document in architecture
2. Database: Update schema if needed
3. Business Logic: Implement in appropriate manager
4. GUI: Create/update panel
5. Integration: Connect to dashboard
6. Testing: Create test cases
7. Documentation: Update README

15.2 Code Standards

• PEP 8: Python style guide
• Type Hints: Use where appropriate
• Docstrings: All public methods
• Error Handling: Try-except with specific exceptions
• Logging: Use verbose levels consistently

15.3 Git Workflow

• main/master: Stable releases
• develop: Integration branch
• feature/*: Feature branches
• bugfix/*: Bug fix branches
• release/*: Release preparation

---

Glossary

• Face Encoding: Numerical representation of a face (128 or 512 dimensions)
• Face Location: Bounding box coordinates (top, right, bottom, left)
• Quality Score: 0-1 rating of face detection quality
• Tolerance: Threshold for face similarity matching
• Person Encoding: Collection of encodings for one person
• Adaptive Tolerance: Dynamic threshold based on quality
• Linkage Type: Single (0) or bulk (1) tag assignment
• Panel: Self-contained GUI component in dashboard
• Manager: Business logic component handling specific domain

---

Document Status: Living Document - Updated as architecture evolves

Maintainers: PunimTag Development Team

Last Review: October 15, 2025