docs: Update architecture documentation and add auto-match load analysis
This commit updates the `ARCHITECTURE.md` file to reflect the transition to a web-based application, including new features and system overview. Additionally, it introduces `AUTOMATCH_LOAD_ANALYSIS.md`, detailing performance issues with the Auto-Match page and recommendations for optimizations. A new document, `CONFIDENCE_CALIBRATION_SUMMARY.md`, is also added to explain the implementation of a confidence calibration system for face recognition, ensuring more accurate match probabilities. These updates enhance the project's documentation and provide insights for future improvements.
This commit is contained in:
Tanya
+93
-74
@@ -1,8 +1,8 @@
|
||||
# PunimTag - Project Architecture
|
||||
|
||||
**Version:** 1.0
|
||||
**Last Updated:** October 15, 2025
|
||||
**Status:** Active Development - Migration to DeepFace Planned
|
||||
**Version:** 2.0
|
||||
**Last Updated:** January 6, 2026
|
||||
**Status:** Production Ready - Web Application with DeepFace
|
||||
|
||||
---
|
||||
|
||||
@@ -25,91 +25,110 @@
|
||||
## 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
|
||||
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
|
||||
- **Face Detection & Recognition**: Automated face detection with person identification
|
||||
- **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
|
||||
- **Unified Dashboard**: Single-window interface with tabbed navigation
|
||||
- **Auto-Matching**: Intelligent face matching with quality scoring
|
||||
- **Batch Processing**: Process multiple photos efficiently
|
||||
- **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 │
|
||||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||||
│ │ 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 │ │
|
||||
│ └──────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ 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 DEPENDENCIES │
|
||||
│ ┌──────────────┬──────────────┬──────────────┬─────────────┐ │
|
||||
│ │ face_ │ PIL/ │ NumPy │ SQLite3 │ │
|
||||
│ │ recognition │ Pillow │ │ │ │
|
||||
│ │ (Current) │ │ │ │ │
|
||||
│ │──────────────│──────────────│──────────────│─────────────│ │
|
||||
│ │ DeepFace │ TensorFlow │ OpenCV │ RetinaFace │ │
|
||||
│ │ (Planned) │ │ │ │ │
|
||||
│ └──────────────┴──────────────┴──────────────┴─────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ EXTERNAL SERVICES │
|
||||
│ ┌──────────────────┬──────────────────┬──────────────────────────┐ │
|
||||
│ │ Redis │ DeepFace │ Background Jobs (RQ) │ │
|
||||
│ │ (Job Queue) │ (AI Models) │ • Face Processing │ │
|
||||
│ │ │ │ • Photo Import │ │
|
||||
│ │ │ │ • Video Processing │ │
|
||||
│ └──────────────────┴──────────────────┴──────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user