Privacy-First Custom Jigsaw Puzzle Platform

A privacy-focused web application that lets you create custom jigsaw puzzles from your own photos. Built with zero-knowledge encryption to ensure your photos remain private.

Features

• Custom Puzzles: Create jigsaw puzzles from your own photos with adjustable difficulty (4-1000 pieces)
• Zero-Knowledge Encryption: Optional client-side encryption ensures only you can view your encrypted photos
• Progress Saving: Auto-saves puzzle progress every 15 seconds
• Upload Progress Tracking: Real-time progress feedback with speed and ETA during photo uploads
• Customizable Puzzle Background: Change puzzle area background color and opacity for better piece visibility
• Responsive Design: Works seamlessly on desktop and mobile devices with automatic tray repositioning on orientation change
• Dark Mode: Full dark mode support
• Admin Dashboard: User management, site settings, and IP blocking
• Wall of Glory: Showcase completed puzzles in a customizable gallery
• Audit Logging: Track all user and admin actions

Tech Stack

Frontend

• Next.js 16 (App Router)
• TypeScript
• Tailwind CSS
• PixiJS (puzzle canvas rendering)

Backend

• Node.js + Express
• TypeScript
• Lucia Auth (authentication)
• PostgreSQL (database)
• MinIO (S3-compatible object storage)
• ClamAV (virus scanning)

Infrastructure

• Docker Compose
• Zero-knowledge encryption (Web Crypto API)

Quick Start

Prerequisites

• Docker and Docker Compose
• Node.js 20+ (for development)
• npm or yarn (for development)

Option 1: Docker Hub Image (Easiest)

Pull and run the pre-built image with only the infrastructure services:

1. Create a project directory and add the production compose file:

mkdir puzzle && cd puzzle
curl -sO https://raw.githubusercontent.com/<repo>/main/docker-compose.prod.yml
curl -sO https://raw.githubusercontent.com/<repo>/main/.env.production.example
cp .env.production.example .env
# Edit .env with your secure passwords

2. Start everything:

docker compose -f docker-compose.prod.yml up -d

3. Open http://localhost:8080 and register your first user (becomes admin automatically).

Services:

• App (frontend + backend + nginx): http://localhost:8080
• MinIO Console: http://localhost:9001

Option 2: Build from Source

1. Clone the repository:

git clone <repository-url>
cd get_puzzles

2. Copy and configure environment:

cp .env.production.example .env
# Edit .env with your secure passwords

3. Build and start all services:

docker compose -f docker-compose.prod.yml up -d --build

4. Open http://localhost:8080 in your browser

5. Register your first user - they will automatically become an admin

Option 3: Development Setup

For local development with hot reload:

1. Clone the repository:

git clone <repository-url>
cd get_puzzles

2. Copy environment files:

cp .env.example backend/.env
cp .env.example frontend/.env.local

3. Update environment variables in both .env files as needed.

4. Start infrastructure services:

docker compose up -d postgres minio clamav

5. Install and start the backend:

cd backend
npm install
npm run dev

6. Install and start the frontend (in a new terminal):

cd frontend
npm install
npm run dev

7. Open http://localhost:3002 in your browser

8. Register your first user - they will automatically become an admin

View logs (production):

docker compose -f docker-compose.prod.yml logs -f

Stop all services:

docker compose -f docker-compose.prod.yml down

Stop and remove volumes:

docker compose -f docker-compose.prod.yml down -v

Option 2: Development Setup

For local development with hot reload:

1. Clone the repository:

git clone <repository-url>
cd get_puzzles

2. Copy environment files:

cp .env.example backend/.env
cp .env.example frontend/.env.local

3. Update environment variables in both .env files as needed.

4. Start infrastructure services:

docker compose up -d postgres minio clamav

5. Install backend dependencies:

cd backend
npm install

6. Install frontend dependencies:

cd ../frontend
npm install

7. Start the backend:

cd backend
npm run dev

8. Start the frontend (in a new terminal):

cd frontend
npm run dev

9. Open http://localhost:3000 in your browser

10. Register your first user - they will automatically become an admin

Documentation

• Setup Guide - Detailed setup and configuration
• API Documentation - REST API endpoints
• Security Model - Encryption and privacy details
• Architecture - System architecture overview
• Deployment - Production deployment guide

Testing

Unit tests (81 tests):

cd backend
npm test

E2E tests (21 tests — requires running dev stack):

cd backend
npx playwright test

The project includes:

• Unit tests covering auth, uploads, puzzle creation, hints, admin, user settings, and gallery
• E2E tests covering registration, login, admin settings, photo upload, puzzle creation, and user settings

Security Features

• Zero-Knowledge Encryption: Photos can be encrypted client-side before upload
• Virus Scanning: All uploads scanned with ClamAV
• Audit Logging: All actions logged for security review
• IP Blocking: Admin can block suspicious IP addresses
• Password Hashing: Argon2id password hashing
• Session Management: Secure session handling with Lucia Auth

Project Structure

get_puzzles/
├── backend/              # Express API server
│   ├── src/
│   │   ├── controllers/  # Request handlers
│   │   ├── services/     # Business logic
│   │   ├── middleware/   # Express middleware
│   │   └── config/       # Configuration
│   └── e2e/              # Playwright E2E tests
├── frontend/             # Next.js application
│   ├── app/              # App router pages
│   ├── components/       # React components
│   └── lib/              # Utilities and API client
├── docker/               # Docker support files
│   ├── nginx.conf        # Reverse proxy config
│   └── entrypoint.sh     # Container startup script
├── docs/                 # Documentation
├── Dockerfile            # Multi-stage production build
├── docker-compose.yml    # Development compose
├── docker-compose.prod.yml # Production compose
├── init.sql              # Database schema
└── .env.production.example

Development Phases

• ✅ Phase 1: Authentication (Login/Registration)
• ✅ Phase 2: Photo Upload (with virus scanning)
• ✅ Phase 3: Puzzle Creation (jigsaw cut algorithm)
• ✅ Phase 4: Puzzle Solving (drag-and-drop, hints)
• ✅ Phase 5: Admin Dashboard (user management, settings)
• ✅ Phase 6: User Settings (profile, password, encryption)
• ✅ Phase 7: Wall of Glory (gallery showcase)

Contributing

Contributions are welcome! Please ensure:

• All tests pass (npm test)
• Code follows existing patterns
• New features include tests
• Documentation is updated

License

MIT License - see LICENSE file for details

Support

For issues and feature requests, please use the GitHub issue tracker.