Back to Documentation

user guide

# User Guide - How to Use Akoto Verify

## Overview
This guide covers the complete process of using Akoto Verify, from initial signup to daily operations for all user types.

## Navigation Structure

### Public Pages
- **`/`** - Landing page with overview and navigation
- **`/about`** - About Us page with company information
- **`/how-to-use`** - This comprehensive usage guide
- **`/changelog`** - Version history and release notes
- **`/plans`** - Pricing plans and signup options
- **`/contact`** - Contact Us page for support and inquiries
- **`/faq`** - Frequently Asked Questions and answers

### Signup Endpoints
- **`/plans/free`** - Free plan signup (0-3 employees)
- **`/plans/pro`** - Pro plan signup (up to 100 employees)
- **`/plans/premium`** - Premium plan signup (up to 300 employees)
- **`/plans/elite`** - Elite plan signup (up to 900 employees)
- **`/enterprise/contact`** - Enterprise inquiry form (1000+ employees)

### System Management
- **`/backoffice`** - System owner access (password protected)
- **`/companies`** - Company management dashboard

### Company-Specific Endpoints
- **`/[company]`** - Company landing page (choose login type)
- **`/[company]/admin`** - HR admin panel
- **`/[company]/login`** - Employee login
- **`/[company]/settings`** - Company settings
- **`/[company]/search`** - Employee log search
- **`/[company]/security`** - Security notifications

## User Workflows

### 1. Customer Onboarding

#### Step 1: Plan Selection
1. Visit `/plans` to view pricing options
2. Compare features and pricing tiers
3. Select appropriate plan based on employee count

#### Step 2: Account Creation

**Free Plan Process:**
1. Click "Create Free Account" → `/plans/free`
2. Fill form: Company name, HR email, password
3. Submit form
4. Account created immediately
5. HR receives email with credentials

**Paid Plan Process (Pro/Premium/Elite):**
1. Click "Get Started" on chosen plan
2. Select billing period (monthly/6-month/12-month)
3. Fill company information form
4. Proceed to Stripe payment
5. Complete payment
6. Account created after successful payment
7. HR receives email with credentials

**Enterprise Process:**
1. Click "Contact Sales" → `/enterprise/contact`
2. Fill detailed inquiry form
3. Submit inquiry
4. Sales team contacts within 24 hours
5. Custom solution developed

#### Step 3: Initial Setup
1. HR receives email with:
   - Company name and HR User ID
   - HR password
   - Direct link to admin panel
2. HR accesses admin panel to begin setup

### 2. HR Administrator Operations

#### Initial Configuration
1. **Access Admin Panel:**
   - Visit `/[company]/admin`
   - Login with HR User ID and password

2. **Configure Settings:**
   - Click "Settings" link
   - Set HR email address (required for notifications)
   - Configure employee log access preferences
   - Set security options (anti-spoofing, geolocation)
   - Configure work hours and tracking options

#### Employee Management
1. **Add New Employee:**
   - Upload employee photo (JPG format)
   - Enter first and last name
   - System generates unique employee ID
   - HR receives email notification
   - Provide employee ID to new hire

2. **Monitor Employees:**
   - View live dashboard of logged-in employees
   - Search employee time logs
   - Generate and email reports
   - Review security incidents

3. **Manage Employee Records:**
   - Delete employees if needed
   - Update employee information
   - Export employee data

#### Reporting and Analytics
1. **Payroll & Analytics:**
   - Access `/[company]/search`
   - Filter by employee name and date range
   - View detailed time records
   - Export payroll-ready reports (Excel/CSV)
   - Compatible with Xero, Sage, QuickBooks
   - Pre-validated for overlaps and missing clock-outs

2. **Automated Reports:**
   - Configure in Settings
   - Set frequency (weekly/monthly)
   - Specify recipient email
   - Receive scheduled timesheet reports

3. **Security Monitoring:**
   - Access `/[company]/security`
   - Review anti-spoofing incidents
   - View screenshot evidence
   - Mark incidents as resolved

### 3. Employee Daily Operations

#### Clock In Process
1. **Access Login Page:**
   - Visit `/[company]/login`

2. **Face Verification:**
   - Click "Start Face Verification"
   - Position face in camera frame
   - System matches face against all registered employees
   - Complete verification process (no ID needed)

3. **Late Arrival Handling:**
   - If clocking in after scheduled time
   - Select reason from dropdown or enter custom reason
   - Submit late reason
   - Proceed to dashboard

4. **Location Tracking (if enabled):**
   - Browser requests location permission
   - Employee can consent or decline
   - Location recorded with clock-in time

#### Clock Out Process
1. **Manual Logout:**
   - Click logout button on dashboard
   - System calculates hours worked
   - Display confirmation with total hours

2. **Automatic Logout:**
   - Close browser tab/window
   - System automatically records logout
   - Hours calculated and saved

#### Self-Service Features
1. **View Personal Logs:**
   - Click "View My Work Logs" while logged in
   - Complete face verification (if required)
   - View time records for configured period
   - See hours worked and attendance history

2. **Colleague Visibility (if enabled):**
   - See other employees currently logged in
   - View names only (admin sees more details)
   - Updates automatically every 5 seconds

### 4. System Owner Management

#### Backoffice Access
1. **Login:**
   - Visit `/backoffice`
   - Enter password from `AKOTOTECHPASSWORD` environment variable

2. **Company Management:**
   - View all companies and statistics
   - Create companies manually
   - Set employee limits and plan types
   - Delete companies if needed

3. **System Monitoring:**
   - Monitor total usage across all companies
   - Access individual company admin panels
   - Manage enterprise deployments

## Loading Indicators and Progress Feedback

### Employee Login Process Loading

During employee login, users will see several loading indicators:

**Face Verification Loading:**
- **Camera initialization:** "Initializing camera..." (2-3 seconds)
- **Face detection:** "Detecting face..." (1-2 seconds)
- **Liveness check:** "Verifying liveness..." (3-5 seconds)
- **Face matching:** "Matching face..." (2-4 seconds)
- **Login processing:** "Logging you in..." (1-2 seconds)

**Total expected time:** 9-16 seconds depending on device performance

**What each step means:**
- Camera initialization: System accessing webcam and preparing capture
- Face detection: AI identifying face boundaries in camera feed
- Liveness check: Anti-spoofing verification to prevent photo attacks
- Face matching: Comparing captured image with registered employee photo
- Login processing: Creating session and redirecting to dashboard

### Employee Creation Progress (HR)

HR administrators see progress indicators when adding new employees:

**Photo Upload Process:**
- **File validation:** "Validating image..." (1 second)
- **Image processing:** "Processing photo..." (2-3 seconds)
- **Face extraction:** "Extracting face data..." (3-4 seconds)
- **Database storage:** "Saving employee..." (1-2 seconds)
- **Email notification:** "Sending notification..." (2-3 seconds)

**Total expected time:** 9-13 seconds per employee

**What each step means:**
- File validation: Checking image format, size, and quality
- Image processing: Optimizing photo for face recognition
- Face extraction: Creating facial recognition template
- Database storage: Saving employee record and photo data
- Email notification: Sending HR confirmation email

### Settings Update Progress

When HR updates company settings, progress indicators show:

**Settings Save Process:**
- **Validating changes:** "Checking settings..." (1 second)
- **Updating database:** "Saving changes..." (2-3 seconds)
- **Email configuration:** "Testing email settings..." (3-5 seconds)
- **Cache refresh:** "Updating system..." (1-2 seconds)

**Total expected time:** 7-11 seconds

**What each step means:**
- Validating changes: Ensuring all settings are properly formatted
- Updating database: Storing new configuration values
- Email configuration: Verifying SMTP settings work correctly
- Cache refresh: Updating system cache with new settings

### Additional Loading Scenarios

**Employee Log Search:**
- **Query processing:** "Searching records..." (2-4 seconds)
- **Data formatting:** "Preparing results..." (1-2 seconds)

**Report Generation:**
- **Data collection:** "Gathering timesheet data..." (3-6 seconds)
- **Excel creation:** "Generating report..." (2-4 seconds)
- **Email preparation:** "Sending report..." (2-3 seconds)

**Security Incident Review:**
- **Loading screenshots:** "Loading evidence..." (2-3 seconds)
- **Incident analysis:** "Processing data..." (1-2 seconds)

### Performance Expectations

**Factors affecting loading times:**
- Internet connection speed
- Device processing power
- Camera quality and lighting
- Database server load
- Number of employees in system

**Optimal conditions timing:**
- Fast internet, modern device: Lower end of time ranges
- Slow internet, older device: Upper end of time ranges
- Peak usage hours: Add 20-30% to expected times

**When to contact support:**
- Loading takes longer than maximum expected time
- Progress indicators freeze or don't advance
- Repeated timeouts during any process
- Error messages appear during loading

## Key Features Explained

### Anti-Spoofing Security
- **Purpose:** Prevent photo/video attacks during face verification
- **How it works:** Analyzes webcam frames for liveness indicators
- **Detection methods:** Blur variance, color variance, movement analysis
- **Response:** Screenshots captured, HR notified, login blocked
- **Management:** View incidents in Security Notifications dashboard

### Geolocation Tracking
- **GDPR Compliance:** Requires explicit employee consent
- **Data captured:** Coordinates at clock-in and clock-out
- **Address resolution:** Converts coordinates to street addresses
- **Visualization:** Interactive maps available for HR
- **Privacy:** Employees can decline and still clock in

### Multi-Tenant Architecture
- **Isolation:** Each company has separate database tables
- **Security:** No data sharing between organizations
- **Scalability:** Supports unlimited companies
- **Employee ranges:** Each company gets 999 employee slots

### Automated Reporting
- **Formats:** Excel and CSV attachments
- **Scheduling:** Weekly, bi-weekly, monthly options
- **Content:** Employee names, times, hours worked
- **Delivery:** Email to configured HR address

## Support and Help Resources

### Contact Us Page (`/contact`)

The Contact Us page provides a direct way for users to reach out for support, sales inquiries, or general questions. The contact form includes:

**Form Fields:**
- **Name** - Full name of the person contacting us
- **Email** - Contact email address for responses
- **Company** - Organization name (optional for general inquiries)
- **Subject** - Brief description of the inquiry topic
- **Message** - Detailed description of the question or issue

**When to Use Contact Form:**
- Technical support issues not covered in FAQ
- Sales inquiries for custom solutions
- Partnership or integration requests
- Billing and account questions
- Feature requests and feedback
- Enterprise deployment discussions

**Response Times:**
- General inquiries: 24-48 hours
- Technical support: 12-24 hours
- Sales inquiries: Same business day
- Enterprise contacts: Within 4 hours

### FAQ Page (`/faq`)

The FAQ page provides comprehensive answers to common questions organized by category:

**Account and Billing:**
- Plan differences and feature comparisons
- Payment methods and billing cycles
- Upgrade/downgrade procedures
- Refund policies and cancellation
- Enterprise pricing and custom solutions

**Technical Support:**
- Face verification troubleshooting
- Browser compatibility requirements
- Camera and lighting setup
- Login and access issues
- Data export and reporting

**Privacy and Security:**
- Data protection and GDPR compliance
- Geolocation tracking policies
- Anti-spoofing technology
- Data retention and deletion
- Security incident handling

**Employee Management:**
- Adding and removing employees
- Employee ID management
- Time tracking and reporting
- Late arrival procedures
- Self-service features

**System Administration:**
- HR admin panel navigation
- Settings configuration
- Email notifications setup
- Report generation and scheduling
- Security monitoring

### Navigation Integration

Contact Us and FAQ links are now available on all main pages:

**Homepage (`/`):**
- "Contact Us" button in header navigation
- "FAQ" link in footer section
- "Get Help" section with quick links

**About Page (`/about`):**
- "Contact Us" call-to-action in company information section
- "FAQ" reference for common questions

**How-to-Use Page (`/how-to-use`):**
- "Still have questions?" section with Contact Us link
- FAQ references throughout guide sections
- "Need more help?" footer with support options

### Getting Support

**Self-Service Options:**
1. **Check FAQ first** - Most common questions are answered
2. **Review User Guide** - Comprehensive documentation available
3. **Try troubleshooting steps** - Step-by-step solutions provided

**Contact Support When:**
- FAQ doesn't address your specific issue
- Technical problems persist after troubleshooting
- Account or billing questions arise
- Custom feature requirements needed
- Enterprise deployment planning required

**Support Channels:**
- **Primary:** Contact form at `/contact`
- **Enterprise:** Direct form at `/enterprise/contact`
- **Documentation:** Complete guides at `/how-to-use`
- **FAQ:** Quick answers at `/faq`

## Troubleshooting

### Common Issues

**Employee Can't Log In:**
1. Verify User ID is correct
2. Check if anti-spoofing is causing issues
3. Ensure good lighting for face verification
4. Try different browser or clear cache

**HR Not Receiving Emails:**
1. Check HR email is configured in Settings
2. Verify SMTP settings in environment variables
3. Check spam/junk folders
4. Test with different email address

**Face Verification Failing:**
1. Ensure good lighting conditions
2. Position face properly in camera frame
3. Remove glasses or hats if needed
4. Check if anti-spoofing is too sensitive

### Face Verification Troubleshooting

#### Common Error Messages
- **"No face detected"** - Camera cannot identify a face in the image
- **"Poor lighting conditions"** - Image is too dark or has harsh shadows
- **"Face doesn't match"** - Verification failed against registered photo
- **"Multiple faces detected"** - More than one person visible in camera
- **"Face too small/large"** - Face needs to be properly positioned in frame

#### Tips for Successful Face Verification
- **Good lighting:** Use natural light or bright, even indoor lighting
- **Look directly at camera:** Face the camera straight-on, avoid tilting head
- **Clear image:** Remove glasses, hats, or anything covering your face
- **Proper distance:** Position yourself 18-24 inches from camera
- **Stable position:** Keep still during verification process
- **Clean camera:** Ensure webcam lens is clean and unobstructed

#### When Verification Fails
1. **Try again immediately** with improved conditions
2. **Check lighting** - move to better lit area or adjust room lighting
3. **Verify User ID** - ensure you're using the correct employee ID
4. **Clear browser cache** and refresh the page
5. **Try different browser** if issues persist
6. **Contact HR** if repeated failures occur

#### Error Page Guidance
When face verification fails, the error page will:
- Display the specific error message
- Provide tips relevant to the error type
- Include a "Try Again" button to restart verification
- Guide you back to the login process automatically

**Payment Issues:**
1. Verify Stripe payment links are configured
2. Check environment variables are set
3. Ensure Stripe account is active
4. Contact support for payment failures

### Support Resources
- **FAQ Page:** Quick answers to common questions at `/faq`
- **Contact Form:** Direct support requests at `/contact`
- **Documentation:** Complete technical documentation in repository
- **Enterprise Support:** Custom solutions through `/enterprise/contact`
- **User Guide:** Comprehensive usage guide at `/how-to-use`

## Best Practices

### For HR Administrators
1. **Configure email first** before adding employees
2. **Test face verification** with sample employee
3. **Set appropriate work hours** for your organization
4. **Enable geolocation** only if needed for compliance
5. **Review security incidents** regularly

### For Employees
1. **Use good lighting** for face verification
2. **Position face properly** in camera frame
3. **Clock out manually** when possible
4. **Provide accurate late reasons** when required
5. **Keep User ID secure** and don't share

### For System Owners
1. **Regular backups** of database
2. **Monitor system performance** and usage
3. **Keep environment variables secure**
4. **Update Stripe payment links** as needed
5. **Review enterprise inquiries** promptly

This guide provides comprehensive coverage of all Akoto Verify functionality for successful implementation and daily operations.