ilia/punimtag
1
0
Fork 0
Code Issues 9 Pull Requests 1 Actions Packages Projects Releases Wiki Activity
punimtag/README.md
tanyar09 94385e3dcc migration to web
2025-10-31 12:10:44 -04:00

8.7 KiB
Raw Blame History

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

🏗️ 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