PunimTag Web

Modern Photo Management and Facial Recognition System

A fast, simple, and modern web application for organizing and tagging photos using state-of-the-art DeepFace AI with ArcFace recognition model.

---

🎯 Features

• 🌐 Web-Based: Modern React frontend with FastAPI backend
• 🔥 DeepFace AI: State-of-the-art face detection with RetinaFace and ArcFace models
• 🎯 Superior Accuracy: 512-dimensional embeddings (4x more detailed than face_recognition)
• ⚙️ Multiple Detectors: Choose from RetinaFace, MTCNN, OpenCV, or SSD detectors
• 🎨 Flexible Models: Select ArcFace, Facenet, Facenet512, or VGG-Face recognition models
• 👤 Person Identification: Identify and tag people across your photo collection
• 🤖 Smart Auto-Matching: Intelligent face matching with quality scoring and cosine similarity
• 🔍 Advanced Search: Search by people, dates, tags, and folders
• 🏷️ Tag Management: Organize photos with hierarchical tags
• ⚡ Batch Processing: Process thousands of photos efficiently
• 🔒 Privacy-First: All data stored locally, no cloud dependencies

---

🚀 Quick Start

Prerequisites

• Python 3.12 or higher
• Node.js 18+ and npm
• Virtual environment (recommended)

Installation

# Clone the repository
git clone <repository-url>
cd punimtag

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install Python dependencies
pip install -r requirements.txt

# Install frontend dependencies
cd frontend
npm install
cd ..

Database Setup

# Generate and run initial migration
source venv/bin/activate
export PYTHONPATH=/home/ladmin/Code/punimtag
alembic revision --autogenerate -m "Initial schema"
alembic upgrade head

This creates the SQLite database at data/punimtag.db (default). For PostgreSQL, set the DATABASE_URL environment variable.

Running the Application

Terminal 1 - Backend API:

cd /home/ladmin/Code/punimtag
source venv/bin/activate
export PYTHONPATH=/home/ladmin/Code/punimtag
uvicorn src.web.app:app --host 127.0.0.1 --port 8000

Terminal 2 - Frontend:

cd /home/ladmin/Code/punimtag/frontend
npm run dev

Then open your browser to http://localhost:3000

Default Login:

• Username: admin
• Password: admin

---

📖 Documentation

• Architecture: System design and technical details
• Web Migration Plan: Detailed migration roadmap
• Phase 1 Status: Phase 1 implementation status
• Phase 1 Checklist: Complete Phase 1 checklist

---

🏗️ Project Structure

punimtag/
├── src/                    # Source code
│   ├── web/               # Web backend
│   │   ├── api/           # API routers
│   │   ├── db/            # Database models and session
│   │   ├── schemas/       # Pydantic models
│   │   └── services/      # Business logic services
│   └── core/              # Legacy desktop business logic
├── frontend/               # React frontend
│   ├── src/
│   │   ├── api/           # API client
│   │   ├── components/    # React components
│   │   ├── context/       # React contexts (Auth)
│   │   ├── hooks/         # Custom hooks
│   │   └── pages/         # Page components
│   └── package.json
├── tests/                  # Test suite
├── docs/                   # Documentation
├── data/                   # Application data (database, images)
├── alembic/                # Database migrations
└── deploy/                 # Docker deployment configs

---

📊 Current Status

Phase 1: Foundations ✅ COMPLETE

Backend:

• ✅ FastAPI application with CORS middleware
• ✅ Health, version, and metrics endpoints
• ✅ JWT authentication (login, refresh, user info)
• ✅ Job management endpoints (RQ/Redis integration)
• ✅ API routers for photos, faces, people, tags (placeholders)
• ✅ SQLAlchemy models for all entities
• ✅ Alembic migrations configured and applied
• ✅ Database initialized (SQLite default, PostgreSQL supported)

Frontend:

• ✅ React + Vite + TypeScript setup
• ✅ Tailwind CSS configured
• ✅ Authentication flow with login page
• ✅ Protected routes with auth context
• ✅ Navigation layout (left sidebar + top bar)
• ✅ All page routes (Dashboard, Scan, Process, Search, Identify, Auto-Match, Tags, Settings)

Database:

• ✅ All tables created: photos, faces, people, person_embeddings, tags, photo_tags
• ✅ Indices configured for performance
• ✅ SQLite database at data/punimtag.db

Next: Phase 2 - Processing & Identify

• Photo import (folder scan and upload)
• Face detection and processing pipeline
• Identify workflow UI
• Auto-match engine
• Scan and Process tab implementations

---

🔧 Configuration

Database

SQLite (Default for Development):

# Default location: data/punimtag.db
# No configuration needed

PostgreSQL (Production):

export DATABASE_URL=postgresql+psycopg2://user:password@host:port/database

Environment Variables

# Database (optional, defaults to SQLite)
DATABASE_URL=sqlite:///data/punimtag.db

# JWT Secrets (change in production!)
SECRET_KEY=your-secret-key-here

# Single-user credentials (change in production!)
ADMIN_USERNAME=admin
ADMIN_PASSWORD=admin

---

🧪 Testing

# Backend tests (to be implemented)
cd /home/ladmin/Code/punimtag
source venv/bin/activate
export PYTHONPATH=/home/ladmin/Code/punimtag
pytest tests/

# Frontend tests (to be implemented)
cd frontend
npm test

---

🗺️ Roadmap

✅ Phase 1: Foundations (Complete)

• FastAPI backend scaffold
• React frontend scaffold
• Authentication system
• Database setup
• Basic API endpoints

🔄 Phase 2: Processing & Identify (In Progress)

• Photo import (scan/upload)
• DeepFace processing pipeline
• Identify workflow UI
• Auto-match engine
• Scan and Process tabs

📋 Phase 3: Search & Tags

• Search endpoints with filters
• Tag management UI
• Virtualized photo grid
• Advanced filtering

🎨 Phase 4: Polish & Release

• Performance optimization
• Accessibility improvements
• Production deployment
• Documentation

---

🏗️ Architecture

Backend:

• Framework: FastAPI (Python 3.12+)
• Database: SQLite (dev), PostgreSQL (production)
• ORM: SQLAlchemy 2.0
• Migrations: Alembic
• Jobs: Redis + RQ
• Auth: JWT (python-jose)

Frontend:

• Framework: React 18 + TypeScript
• Build Tool: Vite
• Styling: Tailwind CSS
• State: React Query + Context API
• Routing: React Router

Deployment:

• Docker Compose for local development
• Containerized services for production

---

📦 Dependencies

Backend:

• fastapi==0.115.0
• uvicorn[standard]==0.30.6
• pydantic==2.9.1
• SQLAlchemy==2.0.36
• alembic==1.13.2
• python-jose[cryptography]==3.3.0
• redis==5.0.8
• rq==1.16.2
• deepface>=0.0.79
• tensorflow>=2.13.0

Frontend:

• react==18.2.0
• react-router-dom==6.20.0
• @tanstack/react-query==5.8.4
• axios==1.6.2
• tailwindcss==3.3.5

---

🔒 Security

• JWT-based authentication with refresh tokens
• Password hashing (to be implemented in production)
• CORS configured for development (restrict in production)
• SQL injection prevention via SQLAlchemy ORM
• Input validation via Pydantic schemas

⚠️ Note: Default credentials (admin/admin) are for development only. Change in production!

---

🐛 Known Limitations

• Single-user mode only (multi-user support planned)
• SQLite for development (PostgreSQL recommended for production)
• No password hashing yet (plain text comparison - fix before production)
• GPU acceleration not yet implemented
• Large databases (>50K photos) may require optimization

---

📝 License

[Add your license here]

---

👥 Authors

PunimTag Development Team

---

🙏 Acknowledgments

• DeepFace library by Sefik Ilkin Serengil - Modern face recognition framework
• ArcFace - Additive Angular Margin Loss for Deep Face Recognition
• RetinaFace - State-of-the-art face detection
• TensorFlow, React, FastAPI, and all open-source contributors

---

📧 Support

For questions or issues:

1. Check documentation in docs/
2. See Phase 1 Checklist for implementation status
3. Review Migration Plan for roadmap

---

Made with ❤️ for photo enthusiasts

For the desktop version, see README_DESKTOP.md