punimtag/docs/USER_GUIDE.md

Admin user guide

How to use the PunimTag admin UI (http://localhost:3000) day to day. Viewer browsing is separate (port 3001).

Table of contents

1. Getting started
2. Navigation
3. Pages
4. Workflow examples
5. Tips
6. Troubleshooting

Getting started

First-time setup

1. Start the application: make sure Redis is running, then start the backend API server and the frontend dev server, and open http://localhost:3000.
2. Log in with the credentials from .env (ADMIN_USERNAME / ADMIN_PASSWORD). Change these before any shared deploy.
3. The usual first workflow is Scan (import photos), Process (detect faces), Identify (name the people in your photos), Auto-Match (match similar faces to people you've already identified), Search (find photos by people, dates, or tags), and Tags (tag photos and manage tags).

Navigation

The left sidebar has these pages:

• Dashboard: overview and statistics
• Scan: import photos from folders or upload files
• Process: detect and process faces in photos
• Identify: manually identify people in faces
• Auto-Match: automatically match similar faces to previously identified faces
• Search: search and filter photos
• Modify: edit person information
• Tags: tag photos and manage photo tags
• Faces Maintenance: manage face data
• Settings: application settings

Pages

Login page

Authenticates you and gets you into the app: username/password, JWT-based, with an automatic redirect to the dashboard after login.

How to use it:

1. Enter your username (ADMIN_USERNAME from .env).
2. Enter your password (ADMIN_PASSWORD from .env).
3. Click "Login".
4. You'll land on the Dashboard.

The session persists until logout. Default credentials are for development only; change them before production use.

Dashboard

Shows an overview of your photo collection: collection statistics, quick links to the main features, and a recent activity summary. Use it to check overall system status and jump to other pages from the sidebar.

This is a basic implementation; more stats may be added later.

Scan page

Imports photos into your collection from folders or uploaded files. It scans subfolders recursively if you ask it to, skips duplicates automatically, and shows live progress during import.

How to use it:

1. Click "Browse Folder".
2. Select a folder containing photos.
3. Toggle "Recursive" if you want to include subfolders.
4. Click "Start Scan".
5. Watch the progress bar.
6. Check the results (photos added, existing photos skipped).

What happens during a scan: photos are copied to data/uploads, EXIF metadata is extracted (date taken, orientation, etc.), duplicates are caught by checksum, and photos are added to the database. Faces are not detected yet; that happens on the Process page.

Large folders take time, so plan for that.

Process page

Detects faces in imported photos and generates face encodings. It uses RetinaFace for face detection and ArcFace for face recognition, both chosen for best accuracy at medium speed. You can set a batch size, watch progress live, and cancel a job if needed.

How to use it:

1. Optionally set a batch size (leave empty for the default).
2. Click "Start Processing".
3. Watch progress: the progress bar shows overall completion, the photo count shows photos processed, and the face count shows faces detected and stored.
4. Wait for it to finish, or click "Stop Processing" to cancel.

What happens: DeepFace analyzes each unprocessed photo, detects and locates faces, generates 512-dimensional face encodings, stores face metadata (confidence, quality, location), and marks photos as processed.

You can cancel a run and resume later without losing progress.

Identify page

For manually identifying people in detected faces. It lets you browse unidentified faces, create new person records, compare against a similar faces panel, see match confidence percentages, filter by date, hide duplicate faces of the same person, and view face metadata (confidence, quality, detector/model).

Basic identification:

1. Go to the Identify page.
2. Look at the current face in the left panel.
3. Pick an existing person from the dropdown, or create a new one below it.
4. Enter person details: first name and last name are required; middle name, maiden name, date of birth, email, and phone are optional.
5. Click "Identify".

Using similar faces:

1. Toggle "Compare" to show similar faces.
2. Look at similar faces in the right panel, with color-coded confidence percentages.
3. Select similar faces to bulk-identify along with the current one.
4. Click "Identify" to apply the identification to the left face and any selected faces on the right.

Navigation: "Next" moves to the next unidentified face, "Back" goes to the previous one, and filters narrow down which faces you see.

The "Unique faces only" filter hides duplicates and shows one representative face per person; the similar faces panel stays unfiltered.

Confidence colors: 80%+ is very high (almost certain), 70%+ is high (likely match), 60%+ is medium (possible match), 50%+ is low (questionable), and below 50% is very low (unlikely).

Tips: use similar faces to identify groups of photos at once, use date filtering to focus on a specific period, and use confidence scores to prioritize which faces to work on first.

Auto-Match page

Automatically matches unidentified faces to people you've already identified. It shows the identified person on the left and their matches on the right, with checkboxes to select which faces to identify, color-coded confidence, and navigation between people.

Manual match workflow:

1. Go to the Auto-Match page.
2. Faces load automatically.
3. The identified person shows on the left panel, with matching unidentified faces on the right.
4. Check the boxes next to faces you want to identify.
5. Click "Save changes for [Person Name]".
6. Use "Next" and "Back" to move between people.

Automatic match workflow:

1. Go to the Auto-Match page.
2. Click "Run Auto-Match".
3. All unidentified faces are matched to identified faces using these criteria: similarity above 70%, picture quality above 50%, and profile faces excluded (they hurt accuracy).

The left panel shows the identified person's reference face; the right panel shows unidentified faces that match them, with confidence percentages. Only faces above the threshold are shown.

Checkboxes select which faces to identify. Previously identified faces are pre-checked, and selections persist as you navigate between people. Saving only applies to checked faces, applies immediately, and can be undone by going back and unchecking.

Review matches carefully before saving; confidence above 70% is usually accurate, but check anyway.

Search page

Searches and filters photos by person, date, tag, or folder. Results show in a virtualized grid with pagination.

How to use it:

1. Go to the Search page.
2. Set filters: people (one or more), date taken, date added, tags (one or more), and folder.
3. Click "Search", or let filters apply automatically.
4. Browse matching photos in the grid.
5. Click a photo for details.

Filters combine with AND logic, and you can clear individual filters or reset all of them. The grid is virtualized so it stays responsive with large result sets; scroll to load more, click photos for details or actions.

People filtering is most useful once you've done some identification work.

Modify page

Edits person information and manages person records: choose a person, edit their name fields and date of birth, view and manage their faces, or delete the person record (with confirmation).

Editing person information:

1. Go to the Modify page.
2. Select a person from the dropdown.
3. Edit first name, last name, middle name, maiden name, or date of birth.
4. Click "Save Changes".

Managing faces: view all faces associated with the person, see thumbnails, and remove faces from the person if needed (unmatch).

Use this page to correct identification mistakes or update names as you learn more. Deletion is permanent, so be careful with it.

Tags page

Manages photo tags and which photos they're linked to: a tag list, tag creation and editing, tag deletion, and assigning tags to photos.

Creating tags:

1. Go to the Tags page.
2. Click "Manage Tags".
3. Enter a new tag name.
4. Click "Add tag".

Managing tags: click "Manage Tags" to see the full list, edit names with the edit button, or delete a tag by checking its box and clicking "Delete selected tags". Deleting a tag removes it from all photos.

Assigning tags to photos: select photos from the Tags page or the Search page, then use the tag assignment interface. You can tag multiple selected photos at once with "Tag Selected Photos", tag every photo in a folder via the linkage icon next to the folder name, or tag a single photo via the linkage icon next to that photo.

Use descriptive names and create tags for events, locations, or themes so they're easier to find later. Tags are case-insensitive.

Faces Maintenance page

For removing unwanted faces, mainly low-quality detections: a full face list, quality filtering, deletion, and bulk operations.

Viewing faces:

1. Go to the Faces Maintenance page.
2. Browse the list of all faces, with thumbnails and metadata.
3. Filter by quality to find faces worth deleting.

Deleting faces: select the faces, click "Delete Selected", and confirm. Deletion is permanent.

Bulk operations let you act on multiple faces at once (delete, unidentify, etc.), which is useful for general database cleanup.

Settings page

Configures application settings and preferences.

Complete workflow: import and identify photos

1. Scan photos: go to Scan, browse a folder or upload files, wait for the import to finish.
2. Process faces: go to Process, pick a detector and model (or use the defaults), click "Start Processing", and wait for detection to finish.
3. Identify people: go to Identify, browse faces, create person records, and use similar faces to help.
4. Auto-match remaining: go to Auto-Match, review the automatic matches, select faces to identify, and save.
5. Search and organize: go to Search, filter by people, dates, or tags, find what you need, and assign tags for organization.

Last updated October 2025 (version 1.0, PunimTag Web).

For technical details and development information, see the main README.md