# PunimTag - Project Architecture

**Version:** 1.0  
**Last Updated:** October 15, 2025  
**Status:** Active Development - Migration to DeepFace Planned

---

## Table of Contents

1. [System Overview](#system-overview)
2. [Architecture Diagram](#architecture-diagram)
3. [Layer Architecture](#layer-architecture)
4. [Core Components](#core-components)
5. [Database Schema](#database-schema)
6. [GUI Architecture](#gui-architecture)
7. [Data Flow](#data-flow)
8. [Technology Stack](#technology-stack)
9. [File Structure](#file-structure)
10. [Design Patterns](#design-patterns)
11. [Future Considerations](#future-considerations)

---

## 1. System Overview

### Purpose
PunimTag is a desktop photo management and tagging application with advanced facial recognition capabilities. It allows users to:
- Import and organize photos from folders
- Automatically detect and identify faces using AI
- Tag photos with custom metadata
- Search photos by people, dates, tags, and other criteria
- Manage identified people and their relationships

### Key Features
- **Face Detection & Recognition**: Automated face detection with person identification
- **Smart Tagging**: Hierarchical tag system with bulk operations
- **Advanced Search**: Multi-criteria search with date ranges, tags, and people
- **Unified Dashboard**: Single-window interface with tabbed navigation
- **Auto-Matching**: Intelligent face matching with quality scoring
- **Batch Processing**: Process multiple photos efficiently

---

## 2. Architecture Diagram

```
┌─────────────────────────────────────────────────────────────────┐
│                      PRESENTATION LAYER                          │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │              Dashboard GUI (dashboard_gui.py)             │  │
│  │  ┌──────────┬──────────┬──────────┬──────────┬─────────┐ │  │
│  │  │ Search   │ Identify │ Auto-    │ Modify   │  Tag    │ │  │
│  │  │ Panel    │ Panel    │ Match    │ Panel    │ Manager │ │  │
│  │  │          │          │ Panel    │          │ Panel   │ │  │
│  │  └──────────┴──────────┴──────────┴──────────┴─────────┘ │  │
│  │                                                            │  │
│  │              GUI Core Utilities (gui_core.py)             │  │
│  └──────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                              ↕
┌─────────────────────────────────────────────────────────────────┐
│                      BUSINESS LOGIC LAYER                        │
│  ┌──────────────────┬──────────────────┬──────────────────────┐ │
│  │  Face Processor  │  Photo Manager   │   Tag Manager        │ │
│  │  (face_          │  (photo_         │   (tag_management.   │ │
│  │  processing.py)  │  management.py)  │   py)                │ │
│  │                  │                  │                      │ │
│  │ • Face Detection │ • Photo Scanning │ • Tag CRUD          │ │
│  │ • Encoding       │ • EXIF Reading   │ • Bulk Operations   │ │
│  │ • Similarity     │ • File Ops       │ • Tag Validation    │ │
│  │ • Quality Score  │ • Metadata       │ • Deduplication     │ │
│  └──────────────────┴──────────────────┴──────────────────────┘ │
│                                                                   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │           Search & Statistics (search_stats.py)          │   │
│  │  • Complex queries  • Date ranges  • Statistical analysis│   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                              ↕
┌─────────────────────────────────────────────────────────────────┐
│                       DATA ACCESS LAYER                          │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │           Database Manager (database.py)                  │  │
│  │                                                            │  │
│  │  • Connection pooling    • Transaction management        │  │
│  │  • Schema management     • CRUD operations               │  │
│  │  • Query optimization    • Data integrity                │  │
│  └──────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                              ↕
┌─────────────────────────────────────────────────────────────────┐
│                        PERSISTENCE LAYER                         │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                SQLite Database (photos.db)                │  │
│  │                                                            │  │
│  │  Tables: photos, faces, people, person_encodings,        │  │
│  │          tags, phototaglinkage                           │  │
│  └──────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                      EXTERNAL DEPENDENCIES                       │
│  ┌──────────────┬──────────────┬──────────────┬─────────────┐  │
│  │ face_        │   PIL/       │    NumPy     │  SQLite3    │  │
│  │ recognition  │   Pillow     │              │             │  │
│  │ (Current)    │              │              │             │  │
│  │──────────────│──────────────│──────────────│─────────────│  │
│  │ DeepFace     │ TensorFlow   │   OpenCV     │ RetinaFace  │  │
│  │ (Planned)    │              │              │             │  │
│  └──────────────┴──────────────┴──────────────┴─────────────┘  │
└─────────────────────────────────────────────────────────────────┘
```

---

## 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
```python
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
```python
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
```python
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
```python
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
```sql
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
);
```

#### people
```sql
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
```sql
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
```sql
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
```sql
CREATE TABLE tags (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    tag_name TEXT UNIQUE NOT NULL,
    created_date DATETIME DEFAULT CURRENT_TIMESTAMP
);
```

#### phototaglinkage
```sql
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
```sql
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:
```python
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`
```python
# 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`
```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