ilia/punimtag
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Scrub active admin guides for plainer tone
CI / skip-ci-check (pull_request) Successful in 31s
Details
CI / docker-ci (pull_request) Successful in 33s
Details
CI / python-lint (pull_request) Successful in 34s
Details
CI / secret-scan (pull_request) Successful in 38s
Details
CI / admin-unit (pull_request) Successful in 57s
Details
CI / viewer-unit (pull_request) Successful in 1m37s
Details
CI / e2e (pull_request) Successful in 1m56s
Details

Browse Source 
Rewrite docs/USER_GUIDE.md, docs/DEPLOYMENT.md, docs/DEPLOY_FROM_SCRATCH.md,
and DEPLOYMENT_CHECKLIST.md to drop AI-generated tells: bold-colon feature
walls, Title Case headings, em dashes, and rule-of-three lists. Facts
(commands, paths, ports, URLs) are unchanged. Historical scratch docs
(PHOTO_VIEWER_*, FIX_*, *_REVIEW, *_PLAN, etc.) and the cPanel-specific
runbooks are untouched.
This commit is contained in:
ilia
2026-08-05 17:05:21 -04:00
parent 2d3f1dee92
commit 31e44cc737
4 changed files with 385 additions and 609 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/USER_GUIDE.md
+239 -419
View File
@@ -17,457 +17,277 @@ Viewer browsing is separate (port 3001).
### First-time setup
1. **Start the Application**
- Ensure Redis is running
- Start the backend API server
- Start the frontend development server
- Open your browser to `http://localhost:3000`
2. **Login**
- Default credentials:
- Use credentials from `.env` (`ADMIN_USERNAME` / `ADMIN_PASSWORD`)
- Change these credentials before any shared deploy.
3. **Initial Workflow**
- **Scan** → Import your photos
- **Process** → Detect faces in photos
- **Identify** → Name the people in your photos
- **Auto-Match** → Automatically match similar faces to previously identified people
- **Search** → Find photos by people, dates, or tags
- **Tags** → Tag photos and manage tags
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 application uses a **left sidebar navigation** with the following pages:
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
- 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
### Login page
Purpose: Authenticate and access the application
Authenticates you and gets you into the app: username/password, JWT-based,
with an automatic redirect to the dashboard after login.
Features:
- Username and password login
- JWT-based authentication
- Automatic redirect to 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.
How to use:
1. Enter your username (`ADMIN_USERNAME` from `.env`)
2. Enter your password (`ADMIN_PASSWORD` from `.env`)
3. Click "Login" button
4. You'll be redirected to the Dashboard
Notes:
- Session persists until logout
- Default credentials are for development only
- Change credentials in production for security
The session persists until logout. Default credentials are for development
only; change them before production use.
### Dashboard
Purpose: Overview of your photo collection and statistics
Features:
- Collection statistics
- Quick access to main features
- Recent activity summary
How to use:
- View statistics about your photo collection
- Navigate to other pages using the sidebar
- Monitor overall system status
Status: Basic implementation - more stats may be added later
### Scan Page
Purpose: Import photos into your collection from folders or upload files
Features:
- **Folder Selection**: Browse and select folders containing photos
- **Recursive Scanning**: Option to scan subfolders recursively
- **Duplicate Detection**: Automatically detects and skips duplicate photos
- **Real-time Progress**: Live progress tracking during import
How to use:
**Folder Scan**
1. Click "Browse Folder" button
2. Select a folder containing photos
3. Toggle "Recursive" if you want to include subfolders
4. Click "Start Scan" button
5. Monitor progress in the progress bar
6. View results (photos added, existing photos skipped)
**What Happens**:
- Photos are copied to `data/uploads` directory
- EXIF metadata is extracted (date taken, orientation, etc.)
- Duplicate detection by checksum
- Photos are added to database
- Faces are NOT detected yet (use Process page for that)
**Tips**:
- Large folders may take time - be patient!
### Process Page
Purpose: Detect faces in imported photos and generate face encodings
Features:
- **face detection method used - `retinaface` - Best accuracy, medium speed
- **Face recognition model used - `ArcFace` - Best accuracy, medium speed
- **Batch Size**: Configure how many photos to process at once
- **Real-time Progress**: Live progress tracking
- **Job Cancellation**: Stop processing if needed
How to use:
1. Optionally set **Batch Size** (leave empty for default)
2. Click "Start Processing" button
3. Monitor progress:
- Progress bar shows overall completion
- Photo count shows photos processed
- Face count shows faces detected and stored
4. Wait for completion or click "Stop Processing" to cancel
**What Happens**:
- DeepFace analyzes each unprocessed photo
- Faces are detected and located
- 512-dimensional face encodings are generated
- Face metadata is stored (confidence, quality, location)
- Photos are marked as processed
**Tips**:
- You can cancel and resume later
### Identify Page
Purpose: Manually identify people in detected faces
Features:
- **Face Navigation**: Browse through unidentified faces
- **Person Creation**: Create new person records
- **Similar Faces Panel**: View similar faces for comparison
- **Confidence Display**: See match confidence percentages
- **Date Filtering**: Filter faces by date taken or processed
- **Unique Faces Filter**: Hide duplicate faces of same person
- **Face Information**: View face metadata (confidence, quality, detector/model)
How to use:
**Basic Identification**:
1. Navigate to Identify page
2. View the current face on the left panel
3. Select existing person from the drop down list or create new person below
4. Enter person information:
- First Name (required)
- Last Name (required)
- Middle Name (optional)
- Maiden Name (optional)
- Date of Birth (optional)
- Email (optional)
- Phone (optional)
5. Click "Identify" button to identify the face
**Using Similar Faces**:
1. Toggle "Compare" checkbox to show similar faces
2. View similar faces in the right panel
3. See confidence percentages (color-coded)
4. Select similar faces to bulk identify with the current left face
5. Click "Identify" button to bulk identify left and all selected on the right faces to that person.
**Navigation**:
- Use "Next" button to move to next unidentified face
- Use "Back" button to go to previous face
- Use filters to narrow down faces to identify
**Unique Faces Filter**:
- Check "Unique faces only" to hide duplicates
- Shows only one representative face per person
- Similar faces panel remains unfiltered
**Confidence Colors**:
- **80%+** = Very High (Almost Certain)
- **70%+** = High (Likely Match)
- **60%+** = Medium (Possible Match)
- **50%+** = Low (Questionable)
- **<50%** = Very Low (Unlikely)
**Tips**:
- Use similar faces to identify groups of photos
- Date filtering helps focus on specific time periods
- Unique faces filter reduces clutter
- Confidence scores help prioritize identification
### Auto-Match Page
Purpose: Automatically match unidentified faces to identified people
Features:
- **Person-Centric View**: Shows identified person on left, matches on right
- **Checkbox Selection**: Select which faces to identify
- **Confidence Display**: Color-coded match confidence
- **Batch Identification**: Identify multiple faces at once
- **Navigation**: Move between different people
How to use:
**Manual Match Workflow**:
1. Navigate to Auto-Match page
2. Faces load automatically on page load
3. View identified person on the left panel
4. View matching unidentified faces on the right panel
5. Check boxes next to faces you want to identify
6. Click "Save changes for [Person Name]" button
7. Use "Next" and "Back" buttons to navigate between people
***Automatic Match Workflow**:
1. Navigate to Auto-Match page
2. Click Run Auto-Match button
3. All unidentified faces will be matched to identified faces based on the following clitiria:
simillarity higher than 70%
picture quality higher than 50%
profile faces are excluded for better accuracy
**Understanding Matches**:
- Left panel shows an identified person with their reference face
- Right panel shows unidentified faces that match this person
- Confidence percentages show match quality
- Only faces above threshold are shown
**Selecting Faces**:
- Check boxes to select faces to identify
- Uncheck boxes to deselect
- Previously identified faces are pre-checked
- Selections persist when navigating between people
**Saving Changes**:
- Click "Save changes" button in left panel
- Only checked faces are identified
- Changes are saved immediately
- You can go back and uncheck faces to unidentify them
**Navigation**:
- "Next" button moves to next person (disabled on last person)
- "Back" button moves to previous person (disabled on first person)
- Navigation preserves checkbox selections
**Tips**:
- Review matches carefully before saving
- Use confidence scores to guide decisions
- You can correct mistakes by going back and unchecking
- High confidence matches (>70%) are usually accurate
### Search Page
Purpose: Search and filter photos by various criteria
Features:
- **People Filter**: Filter by identified people
- **Date Filter**: Filter by date taken or date added
- **Tag Filter**: Filter by photo tags
- **Folder Filter**: Filter by source folder
- **Photo Grid**: Virtualized grid of matching photos
- **Pagination**: Navigate through search results
How to use:
**Basic Search**:
1. Navigate to Search page
2. Use filter dropdowns to set criteria:
- **People**: Select one or more people
- **Date Taken**: Set date range
- **Date Added**: Set date range
- **Tags**: Select one or more tags
- **Folder**: Select source folder
3. Click "Search" or filters apply automatically
4. View matching photos in the grid
5. Click on photos to view details
**Filters**:
- Multiple filters can be combined
- All filters work together (AND logic)
- Clear individual filters or reset all
**Photo Grid**:
- Virtualized for performance with large result sets
- Scroll to load more photos
- Click photos for details or actions
**Tips**:
- Combine filters for precise searches
- Use date ranges to find photos from specific periods
- Tag filtering helps find themed photos
- People filter is most useful after identification
### Modify Page
Purpose: Edit person information and manage person records
Features:
- **Person Selection**: Choose person to edit
- **Information Editing**: Update names and date of birth
- **Face Management**: View and manage person's faces
- **Person Deletion**: Remove person records (with confirmation)
How to use:
**Editing Person Information**:
1. Navigate to Modify page
2. Select person from dropdown
3. Edit information fields:
- First Name
- Last Name
- Middle Name
- Maiden Name
- Date of Birth
4. Click "Save Changes" button
**Managing Faces**:
- View all faces associated with person
- See face thumbnails
- Remove faces from person if needed (unmatch)
**Tips**:
- Use this to correct mistakes in identification
- Update names if you learn more information
- Be careful with deletion - it's permanent
### Tags Page
Purpose: Manage photo tags and tag-photo relationships
Features:
- **Tag List**: View all existing tags
- **Tag Creation**: Create new tags
- **Tag Editing**: Edit tag names
- **Tag Deletion**: Remove tags
- **Photo-Tag Linkage**: Assign tags to photos
How to use:
**Creating Tags**:
1. Navigate to Tags page
2. Click "Manage Tags" button
3. Enter new tag name
4. Click "Add tag" button
**Managing Tags**:
- Click "Manage Tags" button
- View all tags in a list
- Edit tag names by clicking edit button
- Delete tags by selecting it's check box and clicking "Delete selected tags" button
- **Warning**: Deleting a tag removes it from all photos
**Assigning Tags to Photos**:
- Select photos from Tags page(or from Search page)
- Use tag assignment interface
- Tags can be assigned to multiple photos at once by selecting multiple photos and clicking "Tag Selected Photos" button
- Tags can be assigned to all photos in a specific folder at once by clicking the linkage icon next to the folder name
- Tags can be assigned to a single photo by clicking the linkage icon on the right of each photo
**Tips**:
- Use descriptive tag names
- Create tags for events, locations, themes
- Tags help organize and find photos later
Note: Tags are case insensitive!*********
### Faces Maintenance Page
Purpose: Remove unwanted faces - mainly due to low quality face detections
Features:
- **Face List**: View all faces in database
- **Face Filtering**: Filter quality
- **Face Deletion**: Remove unwanted faces
- **Bulk Operations**: Perform actions on multiple faces
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.
How to use:
This is a basic implementation; more stats may be added later.
**Viewing Faces**:
1. Navigate to Faces Maintenance page
2. View list of all faces
3. See face thumbnails and metadata
4. Filter faces by quality (delete faces with low quality)
**Deleting Faces**:
- Select faces to delete
- Click "Delete Selected" button
- Confirm deletion
- **Warning**: Deletion is permanent
### Scan page
**Bulk Operations**:
- Select multiple faces
- Perform bulk actions (delete, unidentify, etc.)
- Useful for cleaning up database
**Tips**:
- Remove low-quality face detections
- Regular maintenance keeps database clean
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.
### Settings Page
Large folders take time, so plan for that.
Purpose: Configure application settings and preferences
### 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.
### Complete Workflow: Import and Identify Photos
1. **Scan Photos**
- Go to Scan page
- Browse folder or upload files
- Wait for import to complete
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.
2. **Process Faces**
- Go to Process page
- Select detector and model (or use defaults)
- Click "Start Processing"
- Wait for face detection to complete
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.
3. **Identify People**
- Go to Identify page
- Browse through faces
- Create person records and identify faces
- Use similar faces to help identification
You can cancel a run and resume later without losing progress.
4. **Auto-Match Remaining**
- Go to Auto-Match page
- Review automatic matches
- Select faces to identify
- Save changes
5. **Search and Organize**
- Go to Search page
- Filter by people, dates, or tags
- Find specific photos
- Assign tags for organization
### 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).
**Last Updated**: October 2025
**Version**: 1.0
**Application**: PunimTag Web
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*