punimtag/README.md

# 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

```bash
# 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

```bash
# 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

**Prerequisites:**
- Redis must be running (for background jobs)
  ```bash
  # Check if Redis is running
  redis-cli ping
  # If not running, start Redis:
  # On Linux: sudo systemctl start redis
  # On macOS with Homebrew: brew services start redis
  # Or run directly: redis-server
  ```

**Terminal 1 - Redis (if not running as service):**
```bash
redis-server
```

**Terminal 2 - Backend API:**
```bash
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 3 - RQ Worker (required for photo import):**
```bash
cd /home/ladmin/Code/punimtag
source venv/bin/activate
export PYTHONPATH=/home/ladmin/Code/punimtag
python -m src.web.worker
```

**Terminal 4 - Frontend:**
```bash
cd /home/ladmin/Code/punimtag/frontend
npm run dev
```

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

**Default Login:**
- Username: `admin`
- Password: `admin`

**Note:** The RQ worker (Terminal 3) is required for background photo import jobs. Without it, jobs will remain in "Pending" status.

---

## 📖 Documentation

- **[Architecture](docs/ARCHITECTURE.md)**: System design and technical details
- **[Web Migration Plan](docs/WEBSITE_MIGRATION_PLAN.md)**: Detailed migration roadmap
- **[Phase 1 Status](docs/PHASE1_FOUNDATION_STATUS.md)**: Phase 1 implementation status
- **[Phase 1 Checklist](docs/PHASE1_CHECKLIST.md)**: 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):**
```bash
# Default location: data/punimtag.db
# No configuration needed
```

**PostgreSQL (Production):**
```bash
export DATABASE_URL=postgresql+psycopg2://user:password@host:port/database
```

### Environment Variables

```bash
# 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

```bash
# 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](docs/PHASE1_CHECKLIST.md) for implementation status
3. Review [Migration Plan](docs/WEBSITE_MIGRATION_PLAN.md) for roadmap

---

**Made with ❤️ for photo enthusiasts**

*For the desktop version, see [README_DESKTOP.md](README_DESKTOP.md)*