Chunks — 35-37. Contractor Portal_

✅ 1. Contractor auth

# **Functional Requirements Document (FRD) – Contractor Portal**

## **1\. Module Overview**

# **Module Name:** Contractor Portal (Authentication & Onboarding)

# **Purpose:** Enable contractors to set up and complete profile setup, and access their dedicated portal for project management

# **Business Goal:** Streamline contractor onboarding and create a centralized contractor-agency collaboration platform

### **Contractor Definition**

# Contractors are freelancers, employees, solo operators, or agency owners who execute events assigned by the agency. (photographers, videographers, content creators, drone operators). They handle event attendance, deliverables, and timing requirements as specified by agency admins.

### **Contractor Types & Roles**

# **Primary Types:** Videographer, Photographer, Content Creator, Drone Operator

# **Role Categories: (Roles will be categorized or defined by the agency )**

# **Lead Shooter** - Main shoot leader

# **Second Shooter** - Lead shooter assistant

# **Drone Operator** - Drone services provider

# **Assistant** - Service support to the lead or other shooters

1.  **Backup Shooter - An additional shooter type/tag for use in the event of** last-minute unavailability of the assigned contractors.

# Note: Contractors can have different roles across agencies. The agency owner determines pay rates as on the contractor's expertise.

##

## **2\. User Roles & Permissions**

# **Role**

# **Description**

# **Key Permissions**

# **Contractor**

# Freelance service providers

# Create/edit profiles, view assigned projects, update availability, sign agreements, upload invoices, update questionnaires, update tax forms, update deliverables, Task management, and maintain notes

# **Agency Admin**

# Agency owner/administrator

# Send invitations, manage contractors, assign projects, and set rates

# **Agency Manager**

# Team leader

# View contractor data, limited project assignment

## **3\. User Flow**

### **Primary Flow - New Contractor:**

#### **Scenario 1: New Invitation (1 agency, single or multiple brands, single or multiple services)**

1.  **Invitation Email** → Contractor receives the invitation URL via email
2.  **Profile Setup** → Complete basic profile information (name, email, password)
3.  **Complete 5-Step Onboarding:**
    *   **Step 1:** Profile Setup (completed above)
    *   **Step 2:** Travel & Location Preferences
    *   **Step 3:** Gear Details (role-based sections)
    *   **Step 4:** Additional Information (dietary, allergies)
    *   **Step 5:** Working Days & Availability
4.  **Dashboard Access** → Redirect to contractor dashboard

#### **Scenario 2: Same Agency, Different Brand**

**2a. Same Services:** Already invited in 1 brand of the same agency, and invited in another/new brand of the same agency with the same services

*   **Flow:** Invitation → Auto-association with new brand → Dashboard update
*   **Result:** No additional onboarding is required

**2b. Different Services:** Same agency, different brand, but different services (e.g., photographer first, then invited as videographer)

*   **Flow:** Invitation → Email notification with redirection link
*   **Action:** Direct to Settings > Gear section to add new service equipment
*   **Result:** Contractor adds videography gear without full re-onboarding

#### **Scenario 3: New Agency, New Brand**

**3a. Same Service:** Contractor invited to a new brand of a different agency with the same service type

*   **Flow:** Invitation → Profile verification → Travel Preferences only
*   **Requirements:** Fill travel preferences (with/without fees) based on the new agency's settings
*   **Skip:** Gear details, additional info, working days (already configured)

**3b. Different Service:** Contractor invited to a new brand of a different agency with a different service type

*   **Flow:** Invitation → Profile verification → Travel Preferences + Gear Details
*   **Requirements:**
    *   Fill in travel preferences based on the new agency's distance settings
    *   Complete gear details for the new service type
*   **Skip:** Additional info, working days (already configured)

## **4\. Field Details & Validations**

### **4.1 Profile Setup Screen**

# **Notifier Display:** Invited brand name, inviter’s name, role assignment, and brand logo. Multi-brand invitations show sequentially.

**Field Name**

**Type**

**Required**

**Validation Rules**

Brand Logo Display

Image

Display Only

Shows the inviting brand's logo (top section)

Role

Text

Display Only

Shows assigned role (e.g., "Photographer")

Multi-Brand Indicator

Text

Display Only

Shows "Multiple Brands" if multiple invitations

First Name

Text

Yes

Text-only, 2-50 characters

Last Name

Text

Yes

Text-only, 2-50 characters

Email Address

Email

Yes

Valid email format, check disposable emails, pre-filled if invited via email

Phone Number

Phone

Yes

Valid phone format with country code selector

Website/Portfolio

Link

No

Valid URL format

Password

Password

Yes

Min 6 chars, 1 uppercase, 1 lowercase, 1 number, 1 special char, Max 20 chars

Eye Toggle

Icon

No

Toggle password visibility

Set up profile

Action Button

Yes

Redirection to the Profile setup

Continue with Google

Action button

Conditional

Direct sign-in and redirection to profile setup

Terms and conditions

Link

–

–

Privacy policy

Link

–

–

Terms of service

Link

–

–

### **4.2 Travel & Location Preferences (Step 2)**

**Field Name**

**Type**

**Required**

**Validation Rules**

Address Line

Text Input

Yes

Google Place API  

City

Text input

Auto-filled

Auto-populated via the data of the Google Place API

State/Province

Text input

Auto-filled

Auto-populated via the data of Google Place API

Country

Text input

Auto-filled

Auto-populated via the data of Google Place API

Zip code

Text input

Auto-filled

Auto-populated via the data of the Google Place API

Travel distance without fees

Dropdown

Yes

Dropdown options: 25-250+ miles (25 increments).

The default initial start value will be fetched from the invited agency’s settings. The increment will be by 25 miles.

For eg, if the agency sets 100 miles, then the increment will be 100, 125, 150, 175, 200, 225, 250, Any.

Travel distance with fees

Dropdown

Yes

This will depend on the “Distance without fees”. The dropdown values will be greater than the distance selected in the “Distance without fees”.

If the contractor selects 150 miles in the Distance without fees field, then the 1st value in the with fees dropdown will be 175 miles (increment of 25)

The “Any” option will be provided as one of the options in the dropdown.

### **4.3 Gear Details- (Role-based Gears setup) (Step 3)**

**Field Name**

**Type**

**Required**

**Validation Rules**

Photography Gear Section

Collapsible Section

Conditional

Only visible if the "Photographer" role is selected

Camera Type

Multi-select Dropdown

Conditional (if photographer)

Multiple selection allowed

Camera Type (Other)

Text

Yes (if others are selected)

Max 250 characters. Comma separated

Lenses

Multi-select Dropdown

Yes (if photographer)

Multiple selection allowed

Lenses (Other)

Text

Yes (if others are selected)

Max 250 characters. Comma separated

On-Camera Flash

Toggle

No

Default: Off, visual toggle with label

Off-Camera Flash

Toggle

No

Default: Off, visual toggle with label

Videography Gear Section

Collapsible Section

Conditional

Only visible if the "Videographer" role is selected

Video Camera Type

Dropdown

Conditional (if videographer)

Single selection

Video camera (Other)

Text

Yes (if others are selected)

Max 250 characters. Comma separated

Video Lenses

Multi-select Dropdown

Yes (if videographer)

Multiple selection allowed

Video Lenses(other)

Text

Yes (if others are selected)

Max 250 characters. Comma separated

Content Creation Gear Section

Collapsible Section

Conditional

Only visible if the "Content Creator" role is selected

Phone Model

Dropdown

Yes (if content creator)

Single selection, with comma-separated values

Phone Model (Other)

Text

Yes (if others are selected)

Max 250 characters. Comma separated

Drone Section

Collapsible Section

Conditional

The drone is NOT a separate service - it's an equipment option across all services, the drone the other devices or both can be used

Drone Model

Dropdown

Conditional,

Single selection

Drone Model(others)

Text

Yes (if others are selected)

Max 250 characters. Comma separated

Commercial License

Toggle

Conditional

Default: Off, visual toggle with the label only needs to upload if the user has the license toggle on l

Upload License

File Upload

Conditional

PDF only, max 5MB, required if license toggle ON

Upload File Delete

Icon

Conditional

The existing license will be removed. Progress is blocked until a new document is uploaded; an inline error will ask the user to upload a valid license

Other Gears Section

Collapsible Section

Always Visible

Always shown regardless of roles

Other Gear

Text Area

No

Max 250 characters, placeholder: "Lightning, audio, stabilizers, etc."

### **4.4 Additional Information (Step 4)**

**Field Name**

**Type**

**Required**

**Validation Rules**

Preferred Name

Text

Yes

By default first name will be fetched, but it can be edited

Max 100 characters, no special symbols, auto-filled from Step 1

Meal Preferences

Radio Button

Options :

\- Chicken

\- Beef

\- Fish

\- Vegetarian

\- Vegan/Gluten-free

No

Single selection

Dietary Restrictions

Toggle

No

Default: Off

Dietary Restriction Details

Text

Conditional

Max 250 chars, required if toggle ON

Allergy Information

Toggle

No

Default: Off

Allergy Details

Text

Conditional

Max 250 chars, required if toggle ON

Meal Preferences Tooltip data

Meal preferences will be shared with the client if meals are offered.

### **4.5 Working Days & Availability (Step 5)**

**Field Name**

**Type**

**Required**

**Validation Rules**

Days of Availability

Toggle Buttons

Yes

All the options will be on by default

All days of the week will be available from Sunday to Saturday

At least one day must be selected, default all ON

Future Days Availability

Dropdown

Yes

Options: No limits, 3,6,9,12, months, Any

**5\. Error Message Handling**

**Field Validation Scenario**

**Error Message**

**Profile Setup**

First Name empty

"First name required"

First Name too long

First name too short

“First Name exceeds 50 characters.”

“First Name requires at least 2 characters.”

Last Name empty

"Last name required."

Last Name too long

Last name too short

“Last Name exceeds 50 characters ”

“Last Name requires at least 2 characters.”

Phone Number empty

“Phone number required.”

Phone Number Invalid format

“Invalid phone number."

Email Invalid format

"Invalid email address."

Email disposable check

"Invalid email address."

Email Empty

"Email address required."

Password empty

"Please enter your password."

Password weak/Short/long

Show only the next missing condition as the user types, updating the message after each requirement is met.  
Requirement:  
\- “Password must be at least 6 characters.”

\- “Password must contain at least one uppercase letter.”

\- “Password must contain at least one number.”

\- “Password must contain at least one special character.”

\- “Password must contain at least one lowercase letter.”

\- “Password cannot exceed 20 characters.”

Website empty

“Website link required.”

Website Invalid URL

“Invalid website URL.”

**Travel Preferences**

Address line empty

" Address is required."

Google Place API failure

"Unable to find address. Please check and try again."

No travel distance selected

"Travel limit is required."

**Gear Details**

No camera type selected

"Please select your camera type to proceed.”.

No lenses selected

" Please select at least one photography lens."

Camera type "Other" but no custom input

"Please specify your camera type."

The drone license toggle is ON but no upload

"Please upload your commercial drone license."

The file upload size exceeded

"File size must be under 5MB."

File upload wrong format

"Invalid format."

**Additional Information**

Preferred name empty

" Preferred name is required."

The preferred name is too long

“Preferred name must be between 2 and 50 characters.”

Dietary restrictions are ON, but no details

"Please provide dietary restriction details."

Allergy toggle ON, but no details

"Please provide allergy information details."

More than one meal preference selected

“Please select only one meal type.”

**Working Days**

No days selected

" Please select at least one day of availability."

**General Errors**

Server timeout

"Connection timed out. Please try again."

The invitation link by the agency has expired

“Your invitation has expired.”

The session expired during onboarding

"Your session has expired."

Network connectivity issue

"Check your internet connection and please try again."

Form submission failure

"Unable to save your information."

## **6\. Functional Logic**

### **Core Business Rules:**

*   **One-Time Onboarding:** Contractors complete onboarding once per agency, not per brand
*   **Step consistency:** If a user closes the system during the setup process, they will be able to resume from the same step when they return to complete the setup.
*   **Multi-Brand Support:** Contractors can work with multiple brands under the same agency without re-onboarding. **Multi-Brand Navigation** → Contractor can switch between associated brands
*   **Dynamic Gear Sections:** Only show gear sections relevant to the contractor's assigned roles
    *   **Primary Services:** Photography, Videography, Content Creation (Drone is not a separate service)
    *   **Flexible Gear Access:** Each service type has access to both standard and drone equipment
    *   **Minimum Requirement:** Contractor must select at least one gear type per assigned service (Eg, camera OR drone, OR both)
    *   **Cross-Service Logic:** All service types include a drone as an optional secondary gear if the primary service gear details are filled.
    *   **Validation Rule:** The system ensures at least one gear selection per service before allowing progression
    *   **Photography Service:** Contractor can use cameras, drones, or both to capture photos
    *   **Videography Service:** Contractor can use video cameras, drones, or both to record videos
    *   **Content Creation Service:** Contractor can use phones, drones, or both for content
*   **Agency-Level Settings:** Travel policies, gear requirements, and rates are set at the agency level. In case of any service update with another gear, the user will be notified to fill in the details.
*   **Real-Time Availability:** Availability updates apply to future events only, not assigned projects
*   **Automatic Distance Filtering:** Travel distance options are filtered based on the agency's base distance settings

1.  **Distance Without Fees**:
    *   Dropdown values begin from a configurable start\_value defined by the agency.
    *   Values increment in 25-mile steps up to 250 miles.
    *   The final option is "Any".  
        
2.  **Distance With Fees**:
    *   This dropdown depends on the user's selection in **Distance Without Fees**.
    *   It starts from 25 miles _greater_ than the selected "without fees" value.
    *   Also increments by 25 miles up to 250.
    *   Includes “Any" as the last option.

### **Edge Case: Agency Updates “Distance Without Fees” Base Setting**

## **When the agency increases the "Distance Without Fees" base value (e.g., from 100 to 200 miles), contractor profiles will be updated as follows:  
**

## If a contractor's existing "Distance Without Fees" value is below the new base (e.g., 150 miles), it will be updated to match the new base (200 miles).

## If a contractor's value is already equal to or above the new base (e.g., 225, 250 miles, or "Any"), no changes will be made.

## **The "Distance With Fees" value, which depends on the "Distance Without Fees," will also adjust automatically:  
**

## For contractors whose "Distance Without Fees" was updated, their "Distance With Fees" will be set to at least 25 miles above the new base (i.e., 225 miles in the above example).

## Contractors who already have "Distance With Fees" above this threshold or have selected "Any" will not be changed**.**

#### **System Behavior:**

*   On agency update of the base setting, the system will:  
    *   Revalidate all saved contractor distance preferences.  
        
    *   Trigger a user alert requiring contractors to review and confirm updated distance preferences before continuing.  
        
    *   Send both email and system notifications to impacted contractors informing them of the update.  
        
    *   Display an alert confirmation message to the agency before finalizing the base setting update.  
        
*   The updated distance parameters will apply only to new projects created after the update. Existing assigned projects will retain their original distance settings.  
    
*   **Drone operation:** Drone Model Field: Contractors can specify which drone models they own
*   **Future availability Logic:** Indicates the availability of contractors and how far they can be booked in advance.
    *   **Rolling Window Behavior**
*   The selected time frame (e.g., 6 months) is always counted from today’s date, not a fixed calendar range.
*   As the current date progresses, the system automatically adds one more day at the end of the window, maintaining the selected duration (rolling availability).
*   This ensures agencies can always book up to the chosen future period without the contractor having to update it daily.
*   If “Any” is selected, then an agency can book the contractor at any time.
*   Future availability will be throughout the system for all the agencies.

## **7\. Edge Cases**

**Scenario**

**Expected Behavior**

**Invitation link expires**

Show an error message with the option to request a new invitation

**Google Place API fails**

Allow manual address entry with a validation prompt

**File upload fails during license upload**

Retry mechanism with clear error messaging

**Session timeout during onboarding**

Auto-save progress and resume from the last completed step

**Contractor updates availability while having committed events**

Update only affects future bookings; a warning message is displayed

**Multiple brand invitations were received simultaneously**

Show all pending invitations, allow sequential acceptance

**The agency changes the base travel distance after contractor onboarding**

Pop up to the agency about the change before proceeding, and a change notification and mail will be sent to the contractor, and the change will be reflected in the system

**The contractor has different travel distances set for different agencies**

Each agency sees the contractor's agency-specific travel settings; no cross-contamination

**Contractor selects only drone gear for the Photography service**

The system accepts the selection as valid; camera gear is optional for the Photography, and either the photo or the drone can be used

**The contractor tries to proceed without any gear selection for the assigned service**

Validation error prevents progression until the minimum gear requirement is met

**Contractor adds new gear while working with multiple agencies**

New gear becomes available for all agencies where relevant service is assigned

**8\. Test Cases**

Test cases link: [https://docs.google.com/spreadsheets/d/1RNM15mQt\_Ax15liD7LeQZTvi\_N01Hax4yZXSNIcN2dI/edit?gid=1054361793#gid=1054361793](https://docs.google.com/spreadsheets/d/1RNM15mQt_Ax15liD7LeQZTvi_N01Hax4yZXSNIcN2dI/edit?gid=1054361793#gid=1054361793)

##

## **9\. Acceptance Criteria**

*   **Profile Setup:** The contractor can successfully set up according to the invitation they receive
*   **Onboarding Completion:** All 5 steps must be completed before dashboard access the user will not be able to move to the next page until all required fields are not filled, and the user will be shown the error messages that need to be resolved to get to the next step and the step path must be shown and the current step highlighted, eg: if the user is in step 4 then the 4th in steps at the header must be highlighted
*   **Data Persistence:** All entered data is saved as the user navigates through the setup steps. If the user exits before completing the setup, they will return to the same step with their previously entered information intact when they come back to the system.
*   **Multi-Brand Support:** Existing contractors can accept new brand invitations without full re-onboarding
*   **Real-Time Validation:** Field validation occurs in real-time with clear error messaging
*   **Geolocation Integration:** Address fields auto-populate using Google Place API
*   **File Upload:** Drone license upload supports PDF files up to 5MB
*   **Availability Logic:** Future availability calculation works correctly with rolling date windows
*   **Dynamic Increment Logic:** 25-mile increments calculate properly from agency-defined start values
*   **Dependent Dropdown Logic:** "Distance With Fees" options correctly start 25 miles above "Distance Without Fees" selection
*   **Responsive Design:** Interface works on desktop and mobile devices
*   **"Any" Availability Handling:** Unlimited booking capability functions properly when "Any" is selected
*   **Cross-Agency Availability:** Future availability settings apply consistently across all associated agencies
*   **Rolling Window Calculation:** Future availability windows correctly roll forward daily from the current date

## **10\. Dependencies**

**Module/System**

**Dependency Type**

**Impact if Unavailable**

**Agency Management**

Data dependency

Cannot validate invitation or apply agency settings

**Geolocation API**

External service

Manual address entry required

**File Storage System**

Infrastructure

Cannot upload drone licenses

**Email Service**

External service

Cannot send invitation links

**Stripe Integration**

Payment processing

Cannot set up payment profiles

**Dashboard Module**

Navigation dependency

Cannot redirect after onboarding completion

**Project Management**

Data consumer

Cannot assign projects to contractors

## **12\. References**

# **Figma Design:** [**Contractor Portal**](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=13461-123513&t=jmuQRlKXWo7LKcL1-0)

# **Test Cases:** [**Google Sheets**](https://docs.google.com/spreadsheets/d/1RNM15mQt_Ax15liD7LeQZTvi_N01Hax4yZXSNIcN2dI/edit?gid=1054361793#gid=1054361793)

*   **Drop-down values:** [**For Photo, Video, Drone, Content creation**](https://docs.google.com/document/d/1KukN8q3E8zJ13OXlMMeg_fvNGjFPxApquZg5RNMcSvA/edit?tab=t.0)

✅ Alternate Flows - Login State Management:

**Alternate Contractor Onboarding & Login Scenarios**

#### **Below are various scenarios where contractor is onboarding and logging in :**

### **Scenario 1: Straightforward New Invitation**

**Context:** 1 agency, 1 brand, single or multiple services

1.  **Invitation Email** → Contractor receives invitation URL via email
2.  **Profile Setup** → Complete basic profile information (name, email, password)
3.  **Complete 5-Step Onboarding:**
    *   **Step 1:** Profile Setup (completed above)
    *   **Step 2:** Travel & Location Preferences
    *   **Step 3:** Gear Details (role-based sections)
    *   **Step 4:** Additional Information (dietary, allergies)
    *   **Step 5:** Working Days & Availability
4.  **Dashboard Access** → Redirect to contractor dashboard

### **Scenario 2: Same Agency, Different Brand**

**2a. Same Services:** Already invited in 1 brand of the same agency, and invited in another/new brand of the same agency with the same services

*   **Flow:** Invitation → Auto-association with new brand → Dashboard update
*   **Result:** No additional onboarding is required

**2b. Different Services:** Same agency, different brand, but different services (e.g., photographer first, then invited as videographer)

*   **Flow:** Invitation → Email notification with redirection link
*   **Action:** Direct to Settings > Gear section to add new service equipment
*   **Result:** Contractor adds videography gear without full re-onboardin

#### **Scenario 3: Different Agency, New Brand**

**3a. Same Service:** Contractor invited to new brand of different agency with same service type

*   **Flow:** Invitation → Profile verification → Travel Preferences only
*   **Requirements:** Fill in travel preferences (with/without fees) based on the new agency's settings
*   **Skip:** Gear details, additional info, working days (already configured)

**3b. Different Service:** Contractor invited to new brand of different agency with different service type

*   **Flow:** Invitation → Profile verification → Travel Preferences + Gear Details
*   **Requirements:**
    *   Fill in travel preferences based on the new agency's distance settings
    *   Complete gear details for new service type
*   **Skip:** Additional info, working days (already configure)

### **Alternate Flows - Login State Management:**

### **Alternate Flow 1: User Already Logged In with Matching Email**

**Context:** User is already logged in and the logged-in email matches the invited email address

1.  **Invitation Click** → System detects the user is already logged in with a matching email
2.  **Email Validation** → System maps invitation link with logged-in email and validates role assignment
3.  **Dashboard Check** → System checks if onboarding is complete
4.  **Branch Logic:**
    *   **4a. Onboarding Complete:** Direct to the dashboard with new brand/agency association
    *   **4b. Onboarding Incomplete:** Resume from last incomplete step
5.  **Agency Association** → Complete association with inviting agency/brand
6.  **Dashboard Access** → Successful login and dashboard access with updated associations

#### **Alternate Flow 2: User Not Logged In, Associated with Different Agency**

**Context:** The user is not logged in but has an existing account associated with a different agency

1.  **Invitation Click** → System displays login screen with invitation context
2.  **Login Attempt** → User enters credentials
3.  **Credential Validation** → System validates login credentials
4.  **Branch Logic:**
    *   **4a. Valid Credentials:**
        *   Email mapping with invitation successful
        *   Proceed to existing contractor flow (Scenario 3a or 3b based on service type)
        *   Complete partial onboarding as required
    *   **4b. Invalid Credentials:**
        *   Display error: "Invalid credentials. Please try again or set up a new profile"
        *   Options provided: "Try Again" or "Set Up Profile"
        *   If "Set Up Profile" is selected → Proceed to Scenario 1 (new contractor flow)
5.  **Agency Association** → System associates contractor with the new agency (multi-agency support)
6.  **Dashboard Access** → Login successfully with multiple agency associations

####

####

#### **Alternate Flow 3: User Not Logged In, No Existing Association**

**Context:** The user is not logged in and not associated with any agency

1.  **Invitation Click** → System displays login/signup screen with invitation context
2.  **User Choice:**
    *   **2a. Login Attempt:** The user tries to log in with existing credentials
        *   **Valid Credentials:** Email mapping with invitation → Proceed to onboarding
        *   **Invalid Credentials:** Error display → Option to "Set Up Profile"
    *   **2b. Set Up Profile:** Direct signup process
3.  **Email Mapping** → System validates invitation email with signup/login email
4.  **Profile Creation** → Complete Scenario 1 (new contractor flow)
5.  **Agency Association** → Associate with inviting agency based on the invitation linkage
6.  **Dashboard Access** → Complete onboarding and dashboard access

#### **Alternate Flow 4: User Logged In with Non-Matching Email**

**Context:** The user is already logged in but the logged-in email does not match the invited email address

1.  **Invitation Click** → System detects email mismatch between logged-in user and invitation
2.  **Logout Confirmation Screen** → Display logout confirmation with an explanation
    *   **Message:** "You are logged in with \[current-email\] but this invitation is for \[invited-email\]. Please log out and sign in with the invited email address."
    *   **Options:** "Logout and Continue" or "Cancel"
3.  **Logout Process** → User confirms logout
4.  **Redirect to Login/Signup** → System redirects to the authentication screen
5.  **Authentication with Invited Email:**
    *   **5a. Login:** User logs in with invited email credentials
    *   **5b. Signup:** The user creates a new account with the invited email
6.  **Email Validation** → System maps authenticated email with an invitation
7.  **Onboarding Process** → Proceed based on the user's existing association status:
    *   **New User:** Complete Scenario 1 (full onboarding)
    *   **Existing User:** Follow Scenario 2 or 3 based on agency relationship
8.  **Agency Association** → Associate with inviting agency
9.  **Dashboard Access** → Successful completion and dashboard redirect

☑️ Header section

# **Header Section (Contractor Portal)**

## **1\. Module Overview**

*   **Module Name:** Header Section (Contractor Portal)
*   **Purpose:** Provide contractors with quick access to global search, theme preferences, tasks, notifications, and profile settings through a persistent navigation header.
*   **Business Goal:** Enhance user experience by offering easy navigation and quick access to frequently used features from any page within the Contractor Portal.

**2\. User Roles & Permissions**

**Role**

**Description**

**Key Permissions**

Contractor

Contractors working with multiple agencies

Access global search, toggle dark/light mode, view tasks, view notifications, and access profile menu

## **3\. User Flow**

**Navigation Path:** Visible on all pages in Contractor Portal (Persistent Header)

### **Step-by-Step Flow:**

1.  Contractor logs into the Contractor Portal
2.  The header section loads at the top of every page, with all components visible
3.  Contractor can interact with any header element:
    *   Use the global search to search for the project name
    *   Toggle between dark and light mode
    *   Access tasks
    *   View notifications
    *   Open profile menu
4.  The header remains fixed at the top during page scrolling
5.  All interactions are accessible from any page within the portal

**4\. Functional Logic**

### **4.1 Header Structure and Layout**

*   The header is fixed at the top of all pages in the Contractor Portal
*   Header remains visible when the user scrolls down the page (fixed position)
*   The header contains five main components from left to right:
    1.  Global Search
    2.  Dark/Light Mode Toggle
    3.  Tasks Icon
    4.  Notifications Icon
    5.  Profile Avatar/Menu

### **4.2 Global Search**

#### **4.2.1 Search Icon and Trigger**

*   The search icon is displayed on the left side of the header
*   Icon includes "⌘K" (or "Ctrl+K" on Windows) keyboard shortcut indicator
*   Clicking the search icon opens the global search modal/dropdown
*   Pressing Ctrl+K (or Cmd+K on Mac) keyboard shortcut opens global search from anywhere in the portal
*   Search functionality is specifically designed for user search only

#### **4.2.2 Search Functionality**

*   Search is designed to find users within the platform
*   For detailed search logic, filters, results display, and user interactions, refer to: \[Click Here - Global Search FRD Link\]
*   Search results appear in a dropdown/modal overlay
*   Search is accessible from any page without navigation

#### **4.2.3 Search States**

*   Default state: Search icon visible with keyboard shortcut indicator
*   Active state: Search modal/dropdown opens when clicked or triggered via keyboard shortcut
*   Closed state: Search modal closes when user clicks outside or presses Escape key

###

### **4.3 Dark/Light Mode Toggle**

#### **4.3.1 Toggle Display**

*   Toggle switch is displayed next to the global search icon
*   Shows sun icon for light mode and moon icon for dark mode
*   Current mode is visually indicated on the toggle
*   Toggle has smooth animation when switching between modes

#### **4.3.2 Toggle Functionality**

*   Contractor clicks on the toggle to switch between dark mode and light mode
*   Toggle action is instant - theme changes immediately across the current page
*   Theme preference is saved for the logged-in contractor
*   Theme preference persists across browser sessions and different devices
*   When the contractor logs in again, their last selected theme is applied automatically
*   Theme preference is user-specific (not global) - each contractor has their own preference
*   Toggle state reflects the currently active theme

#### **4.3.3 Theme Application**

*   Theme changes apply to the entire Contractor Portal interface
*   All pages, components, modals, and UI elements adapt to the selected theme
*   Theme transition is smooth with appropriate CSS transitions
*   No page reload required when switching themes
*   System respects the contractor's preference and does not automatically change based on device settings

#### **4.3.4 Persistence Logic**

*   Theme preference is stored in the database associated with the contractor's user ID
*   When the contractor logs in, the system retrieves their saved theme preference
*   If no preference exists (first-time login), the default theme is light mode
*   Theme preference syncs across all active sessions
*   Preference is saved immediately upon toggle action

### **4.4 Tasks Section**

*   Task icon is displayed in the header with a numeric badge showing unread/pending task count
*   Badge displays count when there are new or pending tasks
*   Badge disappears when count is zero
*   Clicking the task icon opens the tasks panel/dropdown
*   For detailed task functionality, panel layout, task actions, and behaviors, refer to: \[Click Here - Tasks Module FRD Link\]
*   Tasks are accessible from any page in the portal

### **4.5 Notifications Section**

*   The notification bell icon is displayed in the header
*   The numeric badge shows the count of unread notifications
*   Badge color may indicate urgency (e.g., red for critical notifications)
*   The badge displays a count when there are unread notifications
*   The badge disappears when all notifications are read
*   Clicking the notification icon opens the notifications panel/dropdown
*   For detailed notification types, panel layout, mark as read functionality, and behaviors, refer to: **\[Click Here - Notifications Module FRD Link\]**
*   Notifications are accessible from any page in the portal

### **4.6 Profile Section**

#### **4.6.1 Profile Display**

*   Profile avatar is displayed on the far right of the header
*   If the contractor has uploaded a profile photo, it displays in the avatar
*   If no profile photo exists, the avatar shows the contractor's initials with a background color
*   Avatar has a circular shape with appropriate sizing

#### **4.6.2 Profile Menu**

*   Clicking on the profile avatar opens a dropdown menu
*   Dropdown appears below the avatar with proper positioning
*   Dropdown menu contains profile-related options and navigation links
*   For detailed profile menu items, actions, and behaviors, refer to: \[Click Here - Profile Menu FRD Link\]
*   Clicking outside the dropdown closes it
*   Dropdown is accessible from any page in the portal

**5\. Field Details & Validations**

### **5.1 Global Search**

**Element**

**Behavior**

**Validation**

Search Icon

Clickable, opens search modal

N/A

Keyboard Shortcut (Ctrl+K)

Opens search modal from anywhere

Must be active when the portal is in focus

### **5.2 Dark/Light Mode Toggle5.3 Interactive Elements**

**Element**

**Behavior**

**Validation**

Toggle Switch

Switches between dark and light mode

Instant response required

Theme Preference

Saved to database

Must persist across sessions

### 

**Element**

**Behavior**

**Validation**

Notification Icon

Shows badge count, opens notifications panel

Badge shows accurate unread count

Profile Avatar

Opens profile dropdown menu

Shows correct avatar or initials

## **8\. Edge Cases**

**Scenario**

**Expected Behavior**

Contractor has no notifications

Notification badge is hidden; clicking icon shows "No new notifications" message

Contractor has no tasks

Task badge is hidden; clicking icon shows "No tasks" or empty state

Profile photo fails to load

Display avatar with initials as fallback

Search triggered when already open

Keep search modal open; focus on search input field

Keyboard shortcut conflicts with browser

Portal shortcut takes priority when portal is in focus

Multiple rapid theme toggles

Debounce toggle action to prevent multiple API calls; apply last selected theme

Theme fails to apply to some components

Log error, apply theme to majority of components, allow user to retry

Network error during theme save

Show error message; theme persists in current session but may not save for future sessions

Long contractor name in avatar initials

Display first 2 characters only (first name initial + last name initial)

Badge count exceeds 99

Display "99+" instead of exact count

Dropdown opens off-screen

Adjust dropdown position to stay within viewport

## **9\. Acceptance Criteria**

**Header Structure:**

*   Header is visible and fixed at the top of all pages in Contractor Portal
*   Header remains visible when scrolling (sticky/fixed position)
*   All header components are properly aligned and spaced

**Global Search:**

*   Search icon with Ctrl+K shortcut indicator is displayed
*   Clicking search icon opens search modal/dropdown
*   Pressing Ctrl+K (Cmd+K on Mac) opens search from anywhere
*   Search functionality works for user search as per linked FRD

**Dark/Light Mode Toggle:**

*   Toggle switch displays correctly with sun/moon icons
*   Clicking toggle switches between dark and light mode instantly
*   Theme preference is saved to database for logged-in contractor
*   Theme preference persists across browser sessions and devices
*   Last selected theme is applied automatically on next login
*   Theme changes apply to entire Contractor Portal without page reload
*   Default theme is light mode for first-time users

**Tasks Section:**

*   Task icon is displayed with badge showing pending task count
*   Badge displays count when tasks exist; hidden when count is zero
*   Clicking task icon opens tasks panel as per linked FRD
*   Tasks are accessible from any page

**Notifications Section:**

*   Notification bell icon is displayed with badge showing unread count
*   Badge displays count when unread notifications exist; hidden when zero
*   Clicking notification icon opens notifications panel as per linked FRD
*   Notifications are accessible from any page

**Profile Section:**

*   Profile avatar displays contractor's photo or initials
*   Clicking avatar opens profile dropdown menu
*   Dropdown menu contains options as per linked FRD
*   Clicking outside dropdown closes it
*   Profile menu is accessible from any page

**Responsive Behavior:**

*   Header adapts to different screen sizes appropriately
*   All interactive elements remain accessible on mobile devices
*   Dropdowns and modals position correctly on all screen sizes

**Performance:**

*   Header loads instantly with page
*   Theme switching is smooth with no lag
*   Badge counts update in real-time or with minimal delay

## **10\. Dependencies**

**Module/System**

**Dependency Type**

**Impact if Unavailable**

User Authentication

Security Dependency

Cannot identify contractor; cannot load personalized header elements

Global Search Module

Integration Dependency

Search functionality unavailable; icon may be disabled

Tasks Module

Integration Dependency

Tasks panel cannot be displayed; badge may not show

Notifications Module

Integration Dependency

Notifications panel cannot be displayed; badge may not show

Profile Module

Integration Dependency

Profile dropdown cannot be displayed

Theme/Styling System

UI Dependency

Theme toggle may not function; visual inconsistencies

Database

Data Dependency

Theme preference cannot be saved or retrieved

WebSocket/Real-time Service

Integration Dependency

Badge counts may not update in real-time; manual refresh required

## **10\. References**

*   **Figma Link -** [**Click Here**](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=7948-184648&t=0ByRl7J146jJn5dx-0)

✅ 2. Dashboard

# **Contractor Dashboard**

## **1\. Module Overview**

*   **Module Name:** Contractor Dashboard
*   **Purpose:** Provide contractors with a comprehensive global dashboard to manage projects, track earnings, view self-availability, handle payments, and collaborate with multiple agencies across multiple brands
*   **Business Goal:** Create a unified dashboard that enables contractors to efficiently manage their freelance work across multiple agencies and brands while maintaining a clear separation of data and workflows with appropriate access controls

## **2\. User Roles & Permissions**

**Role**

**Description**

**Key Permissions**

Contractor

Contractor assigned to the events

View assigned projects across all agencies and their brands, manage personal availability, view payments, sign agreements, create personal tasks, switch between agency contexts, view all the KPIs, View Task management, check availability, and view finance and performance.

# **3\. Contractor Dashboard – User Flow**

### **Primary Dashboard Flow**

*   **Sign Up -** Upon successful sign-up, the contractor is redirected to a dashboard view. And contractors who don't have any events assigned see empty states
*   **Dashboard Overview:** Displays KPIs, upcoming events, and tasks aggregated across agencies. Greeting shown (Welcome / Welcome Back)
*   **Single Agency Context:** If the contractor is associated with only one brand/agency, → no brand dropdown or agency switch options shown
*   **Agency Context Management:**
    *   Data from other agencies = **read-only**
    *   Clicking cross-agency items prompts an **agency switch**
*   **Brand Switching:**
    *   **The brand filter** appears only if the contractor is working with multiple brands of the same or different agencies

**4\. Functional Logic**

**4.1 Global Dashboard**

*   The contractor dashboard is global, meaning it displays the dashboard data across every agency to which the contractor is associated.
*   However, the contractor can view event details information for events only within the agency corresponding to the current workspace.
*   Events from other agency workspaces will be view-only.
*   To access the full details of an event belonging to a different agency, the contractor must switch to that agency’s workspace. **Refer** \- [**Click Here**](#e64cmqeopr9y)

**4.2 Header Section**

*   The header section of the contractor dashboard will display a welcome message that displays the contractor's name.

**4.2.1 Greeting message**

### **Message Format Rules**

### **First-time Login:** “Welcome \[Contractor First Name\] ”

### **Returning User:** “Welcome Back, \[Contractor First Name\]”

### **Name > 15 chars:** Truncate if longer name→ “Welcome \[Truncated Contractor First Name\]... ”

**4.2.2 Brand Dropdown**

*   The brand dropdown will only be displayed when the contractor is assigned to events from more than one brand; otherwise, it will not be shown
    *   If the contractor is assigned to events from more than one brand, all the brands will be displayed in the brand dropdown.
    *   By default “All Brands” option will be selected

**4.3 Empty State – Dashboard**

*   When a contractor logs into the portal for the first time, or they do not have any assigned events for any brand, they land on a blank dashboard screen (Empty State)
*   All **dashboard KPI cards** (i.e., Projects Completed, Upcoming Events, Year Wise Earnings, Upcoming Earnings) will display **“0”.**
*   The event tabs (Upcoming, Post Event, and Completed) will appear with zero records and an empty-state message: “You have no events yet”.
*   The **Earnings Section** (graph and earnings panel) displays an empty state as follows:
    *   **Total Income Chart:** Shows $0.00 with a straight placeholder graph
    *   **Comparison Indicator:** Displays +0.0% last week
    *   **Earnings Panel:**
        *   Pending, Upcoming, and Paid displays $0.00k
*   **Payments Section:**
    *   Displays empty state message: “You have no payments yet.”
*   **Do Not Book Days Calendar:**
    *   It remains visible and displays unavailable days (DNB) marked by the contractor as a grayed color, and upon clicking any date, the contractor is redirected to the Calendar module
*   **Service Agreements Section:**
    *   Displays empty state message: “You have no agreements yet.”
*   **Events by Type Section:**
    *   Shows an empty circular chart with a label: **“Total Events – 0.”**
*   **Task Management Section:**
    *   Displays empty state message: “You have no tasks yet.”
    *   The Create New Task button remains visible, and upon clicking it, the contractor is redirected to the Task module, where the Create New Task panel opens from the right side

**4.4 Brand Switching & Multi-Tenant Access Logic**

*   If a contractor is invited by (working with) more than one agency, the Dashboard remains **global** across all the agencies they are associated with
*   By default, the contractor will be logged in to the agency they most recently accessed
*   Data from other agency databases is **read-only**. To take action on them (view event details or change task status), the contractor must **switch to that specific agency database**
*   **Brand Filters** will be available only if the contractor is associated with multiple brands. By default, the filter will have “All Brands” in the filter in case of having multiple brands
*   **Agency Switching:**
    *   A contractor can switch to an agency by using the profile menu and changing the workspace

**4.5 Header Section KPI Summary Cards**

*   **Projects Completed**
    *   It displays the **count of all completed events**.
    *   Completed events are those for which the event date has passed, all deliverables have been uploaded by the contractor, and the agency has fully paid the contractor assigned to that event.
*   **Upcoming Events**
    *   It displays the **count of all upcoming events**.
    *   Upcoming events are those scheduled for today or any future date (i.e., events that have not yet occurred)
*   **\[Year\] Earnings**
    *   Displays the total payment received for the current year across all events and all agencies. Only amounts paid by the agency are counted; pending payments are excluded.
    *   The \[Year\] is dynamic and updated every new calendar year. When the year is changed (for example, 2025 to 2026), the total amount will be calculated starting from $0
*   **Upcoming Earnings**
    *   It will display the **amount of upcoming earnings**. Upcoming earnings are the sum of contractor fees pending from all the agencies across all events
    *   For example, if an event has a contractor fee of $200 and $100 has already been paid, the remaining $100 will be included in the upcoming earnings

### **4.6 Events Data Table**

### This section will have the list of events that are assigned to the contractor, and are in the following stages of the project life cycle

### **Upcoming** **Events, Post Event, Completed Events**: **Refer** \- [**Click Here**](#sggmg4h0amfq) for the logic determining which events are displayed under each tab

*   *   To access the full details of an event belonging to a different agency, the contractor must switch to that agency’s workspace. **Refer** \- [**Click Here**](#e64cmqeopr9y)
    *   Clicking the “**View all**” button redirects the contractor to the Events module, with the tab preselected based on the section from which the button was clicked
*   Each section will display the top 5 rows from the event listing

**Sorting Logic:**

*   By default, events are sorted by **Event Date** in ascending order (earliest date first)
*   Users can sort the list by clicking on the column headers:
    *   **Event Date** - Ascending/Descending
    *   **Project** - Alphabetical (A-Z / Z-A)
    *   **Brand** - Alphabetical (A-Z / Z-A)
    *   **Venue** - Alphabetical (A-Z / Z-A)
*   The sort direction is indicated by an arrow icon (↑↓) next to the column header

### **4.7 Total Income Chart**

*   A widget displaying earnings across **all agency brands according to the dropdown period option**

#### **Period Selector (Dropdown):** Options: “This Month”, “Last Month”, “This Year”, “Last Year”, and it will display only “Paid” payments within the selected period across all agencies

*   **Total Income:** It will display the total paid amount received from all the agencies for the selected dropdown period
*   **Growth Indicator**
    *   **Formula:** Growth (%) = ((Current Period Value − Previous Period Value) ÷ Previous Period Value) × 100
    *   **Rules:**
        *   If **Growth (%)** is **positive** → Display **green arrow** (e.g., +43%)
        *   If **Growth (%)** is **negative** → Display **red arrow** (e.g., -12.5%)
        *   If **Growth (%)** is **zero** → Display (0.0%)
        *   If **Previous = 0** → Display **100%** (if current > 0) or **0%** (if current = 0)
*   **Comparison Logic:**
    *   Always compares against the equivalent of the previous period.
    *   **Example:** If the filter is “This Month”, the comparison is shown against “Last Month.”
*   **Graph Line Logic**
    *   On hover, it will display the total paid amount for the specific day or month based on the X-axis value (Month or Year) selected
*   **X-Axis:**
    *   If the **Monthly** filter is selected, → displays the days of the month based on whether the **This Month** or **Last Month** filter is selected
        *   **This Month:** Displays the days of the current month
        *   **Last Month:** Displays the days of the previous month
    *   **If the Yearly filter is selected, →** displays the months based on whether the **This Year** or **Last Year** filter is selected
        *   **This Year:** Displays the months of the current year
        *   **Last Year:** Displays the months of the previous year
    *   The axis **auto-scales dynamically** based on the selected filter
*   **Y-Axis:**
    *   Displays the **total income in USD**
*   **Hover Interaction:** On hover, the graph displays the paid amount on the specific date/month.

#### **Status Bar Breakdown:** On the right side of the graph, a status bar will be displayed with proportional lengths and corresponding currency values based on the Pending, Upcoming, and Paid statuses

*   **Pending (Orange):**
    *   The event date has passed
    *   Payment not made
    *   **Invoice raised OR invoice not raised**
    *   **Example**
        *   Event: Wedding Photoshoot
        *   Event Date: 05 Nov 2025 **(past)**
        *   Contractor Fee: **$500**
        *   Amount Paid by Agency: **$0**
        *   Remaining Amount: **$500**
        *   Invoice Status: Can be raised or not raised
*   **Upcoming (Grey):**
    *   The event date is in the future
    *   Some payment has already been made (partial payment)
    *   Invoice raised OR invoice not raised
    *   Payment is pending
    *   **Example**
        *   Event: Corporate Shoot
        *   Event Date: **30 Dec 2025** (future)
        *   Contractor Fee: **$400**
        *   Agency already paid: **$200**
        *   Upcoming Amount: **$200**
        *   Invoice status: Can be raised or not raised
*   **Paid (Green):** Displays the total of all the payments that have been successfully made by the agencies.

#### **Calculation Logic**

#### **Total Income = Only “Paid” amounts** (within chosen timeframe).

**4.8 Calendar Management (Do Not Book)**

*   Do Not Book: Along with the heading, an info (tooltip) icon will be displayed. On hover, it will show the tooltip message
*   The Do Not Book Days calendar displays dates when the contractor is unavailable or already booked for events across all agency brands. By default, the current month is displayed.
*   By clicking on any date, the contractor will be redirected to the calendar module, from where the contractor can set up their availability
*   **Date Visual States:** The calendar displays dates with the following visual indicators:
    *   **Available dates**: Black text
    *   **Unavailable/Booked dates**: Grey text
    *   **Current day**: Highlighted with a colored background
    *   **Past dates**: Grey text
*   Navigation Controls: The calendar includes month/year navigation with left/right arrow buttons for moving between months. Clicking on the month/year label opens a scrollable year selection panel displaying multiple years in a grid format. The contractor can scroll through the list and select any year, and the calendar will automatically display the current selected month for that chosen year
*   When the contractor navigates to any other module and returns to the dashboard, the calendar will automatically reset to display the current month and year
*   If an agency owner removes a contractor from an event, the date automatically displays as available

**4.9 Payments Table**

### **Payments Table Widget**

### A scrollable widget that displays all payment records, auto-fetched from Stripe, with status indicators, amounts, and actions

*   **Payment Status (Badge):** Displays Pending, Upcoming, Paid, Failed (Stripe-synced)
    *   **Upcoming** - It will display the Upcoming status when the contractor fee is associated with an upcoming event, including cases where the invoice has been raised but payment is still pending, and the event date is in the future
    *   **Pending** - It will display the Pending status when the invoice has been raised by the contractor, the event date has passed, and payment has not yet been made by the agency
    *   **Paid** - It will display the Paid status when all the total payments have been successfully made by the agency
*   **Payment Date:**
    *   For **Upcoming** – It will display “--” when the invoice has not been generated, and if the invoice is generated, it will display the invoice due date
    *   For **Pending** – It will display the invoice due date
    *   For **Paid** – It will display the date on which the invoice was successfully paid by the agency
*   **Amount:** It will display the amount based on two situations – if no invoice has been generated, it will display the **contractor fee**; if an invoice has been generated, it will display the **invoice due amount**
*   **Project**: This column will display the Project and event name (with event color code) for which the payment is paid, pending, or upcoming
*   **Actions (Button):** The “View Invoice” button, when clicked, opens the invoice for the corresponding payment. If no invoice has been generated, it will display “--”
*   **View All:** On click, redirects to the Payments module
*   **Payment Sorting:**
    *   The column can be sorted by Date and Amount
    *   By default, Newest payments appear on top
    *   Older ones follow in descending order
    *   By default, only **11 records** are shown in the widget listing

**4.10 Service Agreements Section:**

*   **Service Agreements**: Along with the heading, an info (tooltip) icon will be displayed. On hover, it will show the tooltip message
*   This section displays a list of all service agreements sent by all agencies for events that have not yet been signed by the contractor
*   Once the contractor signs an agreement, it will be removed from the list
*   **Event details displayed:**
    *   Event name with its corresponding color code for which the service agreement was sent by the agency
    *   Date and time when the service agreement was sent
*   **Sign Now Button:** On click, it redirects and opens the service agreement for the event, allowing the contractor to review and sign the agreement
*   **Post-signature:** Agreement removed from widget
*   **Sorting:** Oldest agreements appear at the top, and newer ones appear below

**4.11 Events by Type**

*   This section provides a visual summary of all events assigned to the contractor, categorized by event type, allowing quick viewing of event distribution and total count
*   **Events by Type**: Along with the heading, an info (tooltip) icon will be displayed. On hover, it will show the tooltip message
*   **Total Events Counter:** A display-only number positioned at the center of the doughnut chart, showing the total count of events assigned to the contractor across all categories
*   **Chart Segments:** A doughnut chart visually representing event types. Each segment is color-coded based on the event’s assigned color, and the size of each segment is proportional to the number of events in that category
*   **Chart Interaction:** On hover or click, detailed information about the selected event category (name and count of that specific event type) is displayed as a tooltip
*   Below the chart, it displays each event type (i.e., Wedding, Rehearsal dinner) assigned to the contractor, along with its respective color code
*   **Display Logic:** Data is dynamically fetched based on all events associated with the logged-in contractor

### **4.12 Task Management**

*   **Task Display:** The widget displays a list of tasks where the contractor is either assigned by the agency or has created the task themselves
*   Tasks are listed by nearest due date first, and if any tasks are overdue, they are displayed before all upcoming tasks.
*   Each task card includes:
    *   **Task Name**
    *   **Task Priority Icon (High, Medium & Low)**
    *   **Event Name** (if the task is linked to an event (assigned by the agency))
    *   **Contractor Role:** Displays the role of the contractor for the event for which the task is assigned by the agency
    *   **Due Date:** Display the due date of the task
        *   A “**Due Today”** label will be displayed if the due date matches the current date and the task status is not “Completed”.
        *   An **"Overdue"** label will be displayed if the due date has already passed, and the task status is not “Completed”.
    *   **Avatar Images** of assignees (contractor) & reporter to the same task for an event
*   **Dropdown Filter:** A dropdown menu is available at the top right corner of the widget with the following filter options:
    *   **To Do**
    *   **In Progress**
    *   **Completed**
*   Selecting an option will move the task to the selected status
*   **Kebab Menu (⋮) Options:** A three-dot menu (kebab icon) is displayed for each task card
    *   On click, the menu shows dynamic options based on the task’s current status:
    *   If the task is **To Do**, it displays: **Move to In Progress** and **Move to Completed**
    *   If the task is **In Progress**, it displays: **Move to Completed** and **Move to To Do**
    *   If the task is **completed**, it displays: **Move to In Progress** and **Move to To Do**
*   Selecting an option updates the task status both in the widget and in the **Task Management Module** accordingly
*   **Delete Task Option:**
    *   A Delete option appears only for **self-created tasks** (not for agency-assigned tasks). On clicking Delete, a **confirmation pop-up** appears. And if confirmed, the task is permanently deleted and removed from both the widget and the **Task Management Module**
*   **Task Completion via Checkbox:**
    *   **To Do** & **In Progress** Task card includes a **round checkbox**
    *   On click, the task is marked as **Completed**, and its status is automatically updated in the **Task Management Module**
*   **Task Count and Expansion:**
    *   If more than two tasks are available, a **Show More (+X Tasks)** link appears below the task list (e.g., Show More (+10 Tasks))
*   On click, the widget expands to display all remaining tasks in a scrollable view
*   Once expanded, a **Show Less** option allows the contractor to collapse the view back to its default state

**5\. Success Messages Table**

## **Category**

## **Scenario**

## **Success Message**

## **Multi-Agency Context**

## Agency switch successful

## Successfully switched to \[Agency Name\].

## **User Authentication & Profile**

## Studio mode activated

## "Successfully switched to \[Business Name\] studio mode."

## **Task Management**

Task Updated

“Task has been successfully updated.”

## **6\. Edge Cases**

**Scenario**

**Expected Behavior**

The agency manually marks the project as "Completed" before the contractor’s invoice is paid

The system automatically updates the contractor dashboard to show the project as completed and moves earnings to the PENDING category. The contractor must contact the agency directly to resolve any completion status disagreements

Internet connection lost during task completion

Auto-save progress to localStorage, sync when connection restored, show an offline indicator

Agency removes contractor access mid-session

Log out with an explanation message, redirect to login with an informational notice

The contractor completes onboarding, but no projects are assigned

Empty state dashboard with guidance messages.

Calendar sync failure with external calendar

Manual sync option available, warning about potential conflicts, and fallback to manual calendar management

Contractor account suspended by one agency

Remove suspended agency from context options, maintain access to other agencies, and clear notification of suspension

Contractor delete agency ( studio)

Show "Manage your business on Pixally" again

The user switches agency while the brand filter is active

The system clears the brand filter and shows all data for the newly selected agency

The previous period had $0 income, but the current period has income

The display shows "+100%" with green color, the tooltip explains "No previous income to compare", and the growth calculation handles division by zero gracefully

## **7\. Test Cases**

*   **Link**: [**Pixally Test cases**](https://docs.google.com/spreadsheets/d/1RNM15mQt_Ax15liD7LeQZTvi_N01Hax4yZXSNIcN2dI/edit?gid=97704170#gid=97704170)

## **8\. Acceptance Criteria**

*   **Global Dashboard Scope –** Dashboard aggregates data across all agencies but allows full event actions only in the current workspace and shows other-agency events as view-only until the workspace is switched.
*   **Header Greeting –** Displays “Welcome \[FirstName\]” for first login, “Welcome Back, \[FirstName\]” for returning users, and truncates names longer than 15 characters with “…”.
*   **Brand Dropdown –** Shows brand dropdown only when assigned to multiple brands, with “All Brands” selected by default, and lists all assigned brands.
*   **Empty State –** When no events exist, all KPIs show 0, events tabs show empty messages, earnings chart shows $0.00 and 0% comparison, payments list shows no records, DNB calendar shows only unavailable days, agreements list and tasks list show empty states, and “Create Task” opens the task drawer.
*   **Multi-Tenant Access –** Dashboard stays global for multi-agency contractors, defaults to the last-used agency, shows non-current agency data as read-only, and allows full actions only after workspace switch via profile menu.
*   **Brand Switching –** Brand filters appear only if multiple brands exist with “All Brands” default, and data filters update instantly when switching brands.
*   **Projects Completed KPI –** Counts events whose date passed and where deliverables are uploaded, and the contractor is fully paid.
*   **Upcoming Events KPI –** Counts all events scheduled for today or a future date.
*   **Year Earnings KPI –** Displays total paid income for the current year only across all agencies and resets to $0 at every new calendar year.
*   **Upcoming Earnings KPI –** Sums remaining unpaid contractor fees (full fee minus paid amount) across all future or partially paid events.
*   **Events Table –** Shows top 5 events for Upcoming, Post Event, and Completed tabs based on event-tab rules, supports “View All” to open the Events module, and requires workspace switch to access full details of other-agency events.
*   **Total Income Chart –** Displays paid income based on “This Month/Last Month/This Year/Last Year” filter, with hover values, dynamic X/Y axes, growth calculation rules, and right-side Pending/Upcoming/Paid status bar breakdown.
*   **Do Not Book Calendar –** Shows a monthly view with availability states, supports month navigation and scrollable year picker, resets to current month on returning, and auto-updates availability when the agency removes events.
*   **Payments Widget –** Lists up to 15 newest Stripe-synced payments with sortable Date/Amount, shows Upcoming/Pending/Paid/Failed badges, displays correct payment dates and amounts, and “View Invoice” opens invoice or shows “--” when unavailable.
*   **Service Agreements –** Displays all unsigned agreements with event name/color and sent time, allows signing via “Sign Now,” removes signed agreements from the list, and sorts oldest first.
*   **Events by Type –** Shows a doughnut chart of event counts by type with hover tooltips, a center total counter, and a legend listing event types with colors.
*   **Task Management Widget –** Shows contractor tasks sorted with overdue first, supports task status filters (To Do/In Progres

s/Completed), offers dynamic kebab actions, allows deleting only self-created tasks, supports checkbox completion, and expands via “Show More (+X)” with collapsible “Show Less”.

**9\. Dependencies**

**Module/System**

**Dependency Type**

**Impact if Unavailable**

Authentication System

Infrastructure

Cannot access the dashboard, no user context or session management

Multi-Tenant Database

Infrastructure

Cannot separate agency data, complete system failure, security breach risk

Agency Portal

Data dependency

Cannot get the data from the agency portal for all the events

## **10\. References**

*   Figma File: [**With data Dashboard**](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=7948-184648&t=wvCV3qWfYOJH4PEi-0)
*   Figma File: [**Without data Dashboard**](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=15120-77621&t=wvCV3qWfYOJH4PEi-0)

✅ 3. Event listing

# **Events Management System**

## **1\. Module Overview**

# **Module Name:** Events Management System (Contractor Portals)

# **Purpose:** Enable contractors to view and manage their assigned events across all agencies, from upcoming events to completed events, with cross-brand access control and comprehensive event tracking capabilities

*   **Business Goal:** Provide contractors with a centralized interface to track all assigned events, manage deliverables, submit invoices, and maintain clear visibility into event status and requirements across multiple brands

# **2\. User Roles & Permissions**

# **Role**

# **Description**

# **Key Permissions**

# **Portal Access**

# Contractor

# Contractors assigned to events

# View assigned events to them only, view Project details

# Contractor Portal, Navigation menu

## **3\. User Flow**

### **Contractor Portal Navigation Structure:**

# **Navigation:** Contractor Portal Side Menu Navigation > Event Modules

## **4\. Functional Logic**

**4.1 Events Module**

*   Contractors can view only those events that have been assigned to them by the agency. If no events are assigned, an empty state will be displayed
*   The event listing is **global**, meaning it displays all events across every agency to which the contractor is assigned. However, the contractor can view detailed information for events only within the agency corresponding to the **current workspace**. Events from other agency workspaces will be **view-only**. To access the full details of an event belonging to a different agency, the contractor must switch to that agency’s workspace. Refer - [**Click Here**](#q3d4jtdlwegx)
*   The module displays three status-based tabs: Upcoming, Post-Event, and Completed
*   By default, the Upcoming tab is displayed

### **4.2 Empty State Display**

*   If the contractor has not been assigned any event by the agency:
    *   An empty state will be displayed across all tabs.
    *   Primary message for all the tabs: **“You have no events yet.”**
    *   Secondary message (Only display in the Upcoming tab): **“Wait for the agency owner to assign an event to you.”**

**4.2 Event Listing Status Logic**

*   **Events are classified into Upcoming, Post Event, and Completed**
*   **Upcoming**
    *   Events will be displayed under the Upcoming tab when their event date is today or any future date (i.e., the event has not yet occurred).
*   **Post-Event**
    *   Events will be displayed under the Post-Event tab when the event date has passed (the day after the event date) and any of the following conditions are met:
        *   The deliverables have not been uploaded by the contractor
        *   The invoice has not been uploaded by the contractor, or
        *   The fee has not yet been fully received by the contractor from the agency.

*   **Completed**
    *   It displays the count of all completed events. Completed events are those for which the event date has passed, all deliverables have been uploaded by the contractor, and the agency has fully paid the contractor's fee assigned to that event.
    *   Events will be displayed under the Completed tab when the event date has passed (the day after the event date) and all of the following conditions are met:
        *   The deliverables have been uploaded by the contractor
        *   The invoice has been uploaded by the contractor
        *   The full payment has been received by the contractor from the agency for that event.

**4.3 Event List Display Logic**

*   **Default Sorting:** Events in all the tabs are sorted by event date (ascending) by default.
*   Events automatically transition between tabs based on date and event completion criteria.
*   **Column Sorting**: Event Date, Project, Brand, and Service Area columns support ascending and descending sort functionality

**4.4 Search Functionality**

*   The search bar allows contractors to search across multiple event attributes:
    *   Project name
    *   Event type
    *   Brand name
    *   Service area name
*   Search results filter the event list in real-time as the contractor types. If no matches are found, the system displays: "**No matching events found.**"

**4.5 Filter Functionality**

*   The contractor can access the filter by clicking the filter button in the header section.
*   The filter panel provides multiple filtering options to help contractors narrow down event lists. **Filter** **options are listed below**:
*   **Reset All Filters**: A circular refresh icon in the top-right corner clears all applied filters immediately without confirmation
*   **Event Type**: The Event Type filter dynamically displays all event types to which the contractor has been assigned by all the agencies
*   **Date Range Filter**:
    *   **Start Date**: Filters events occurring on or after the selected date
    *   **End Date**: Filters events occurring on or before the selected date
    *   In the date range filter, once a Start Date is selected, all dates before the selected start date will be disabled in the End Date field. Similarly, if an End Date is selected first, all dates after the selected end date will be disabled in the Start Date field.
*   **Brand Filter**: A single-select dropdown that displays only the brands assigned to the contractor by all agencies. Selecting a brand filters the events to show only those associated with the selected brand
    *   The **Brand** and **Service Area** filters are interdependent. If the contractor selects a brand, only the service areas associated with that brand will be displayed in the Service Area filter, and vice versa
*   **Tags Filter**: Multi-select dropdown allowing contractors to filter by multiple event tags simultaneously. The tag list is dynamically populated from event tags that are associated with the contractor.
*   **Service Area Filter**: A single-select dropdown that displays only the service areas assigned to the contractor by all the agencies. Selecting a service area filters the events to show only those in the selected location.
*   **Venue Filter**: A single-select dropdown that displays the venues of the events assigned to the contractor. If the contractor is assigned to multiple events with different venues, all those venues will appear in the dropdown. If any assigned events do not have a specified venue, a “TBD” option will be displayed in the dropdown to filter the events with no venue.
*   **Service Type Filter**: A multi-select checkbox group that displays only the service types for which the contractor has been invited.
    *   For example, if the contractor is invited as a Photographer only, then only the Photography option will be displayed. If the contractor is invited as a Photographer, Videographer, and Content Creator, all three options will appear.

#### **4.5.1 Filter Behavior (After Application)**

*   When one or more filters are applied, the selected values appear as **filter tags** above the contractor listing table.
*   Each filter tag includes a **cancel (X)** icon that allows users to remove that specific filter.
*   On removing an individual filter, the event list updates instantly based on the remaining active filters.
*   A **Clear All Filters** button is displayed next to the tags to remove all filters at once.
*   Clicking '**Clear All Filters**' will clear all selected filters and refresh the event list to display all events assigned to the contractor.

### **4.6 Status Icon Display Logic**

*   Status icons are displayed only in the **Upcoming** and **Post Event** tabs
*   **Upcoming Tab**: **Service Agreement** Icon:
    *   If the contractor has signed the service agreement, it will display the **filled** icon
    *   If the service agreement has not yet been signed by the contractor, the icon will remain empty.
*   **Post-Event Tab:**
    *   In the **Post-Event** tab, three icons are displayed — **Invoice Upload**, **Deliverables Upload**, and **Payment Received**.
        *   **Invoice Upload** - If the contractor has uploaded an invoice, the icon will appear filled; otherwise, it will remain empty.
        *   **Deliverables Upload** - If the contractor has uploaded the deliverables, the icon will appear filled; otherwise, it will remain empty.
        *   **Payment Received** - If the contractor has received partial payment from the agency for the contractor fee (i.e., not fully paid, but some amount has been paid), the Payment Received icon will appear **partially filled**. If the contractor has been fully paid the contractor fee, the icon will appear filled. If the contractor is not paid, it will remain empty.

**4.6.1 Impacted Modules for status icons**

*   **Agency-Side Views:**
    *   Calendar List View — Status icons displayed alongside each event entry
    *   Event Details > Contractors Tab — Status icons shown for each assigned contractor
    *   Project Listing — Invoice icon visible in the project list view
    *   Event Listing — Status icons displayed for each event row
*   **Contractor Portal Views:**
    *   Event Listing — Status icons displayed for contractor's assigned events
    *   Event Details > Contractor's Tab — Status icons reflecting contractor's own submission and payment status

**4.7 Cross-Brand Pop-Up Logic**

*   When a contractor clicks the **"View Details"** button for an event that belongs to a **different brand’s studio workspace** than the one they currently have selected:
    *   A confirmation pop-up appears, asking the contractor to confirm the studio switch.
    *   Two action buttons are provided in the pop-up: **"Cancel"** and **"Yes, Switch"**.
*   On clicking **"Cancel"**:
    *   The pop-up closes, and the contractor remains in the current brand context.
*   On clicking **"Yes, Switch"**:
    *   The contractor will be switched to the studio workspace associated with the selected event.
    *   The contractor will then be redirected to the event details page for that event.
    *   The new studio workspace selection will persist throughout the session until it is changed again.

**5\. Field Details & Validations**

### **5.1 Upcoming Events Tab**

# **Field Name**

# **Display Format**

# **Validation Rules**

# Event Date

# "Sat, October 5, 2024"

# Display the event date

If not assigned, display TBD

# Event Type

# "PHOTOGRAPHY"

# Display the event type

# Project and Event Name

# "Jadon & Monika"

"REHEARSAL DINNER"

# Display the project and event name as set by the agency

# Users

# User Profile Image

# \- Display only the contractor and agency users associated with the event

\- Display the first 3 user profiles, and if more than 3, it will display +X

# Brand Assignment

# "Emma Taylor"

# Display the associated brand of the event

# Brand Logo

# Secondary Logo

# Display the event’s associated brand secondary logo

# Service Area

# "Los Angeles, California, USA"

# Display the service area of the event

# Service agreement

# Icon

# Display a filled icon if the contractor signs the agreement; otherwise, display an empty icon

# Actions

# "View Details"

# Redirect the contractor to the event details page if the same studio event, otherwise display the studio switch pop-up

# Refer - [**Click Here**](#q3d4jtdlwegx)

### **5.2 Post-Event Tab**

# **Field Name**

# **Type**

# **Validation Rules**

# Event Date

# **Refer** \- [**Click Here**](#u8uuxmnwh4u5)

# Project Name & Event Type

# Users

# Brand

# Brand Logo

# View Details

# Invoice Upload

# **Refer -** [**Click Here**](#rndlgw36wh1k)

# Deliverables Upload

# Payment Received

### **5.3 Completed Tab**

# **Field Name**

# **Type**

# **Validation Rules**

# Event Date

# **Refer -** [**Click Here**](#u8uuxmnwh4u5)

# Project & Event Name

# Users

# Brand

# Brand Logo

# Service Area

# Actions

### **5.4 Filter Fields**

**Field Name**

**Field Type**

**Validation Rules**

Reset All Filters

Button

**Refer** \- [**Click Here**](#w1389kpk7qb6)

Event Type

Dropdown

Start Date

Date Picker

End Date

Date Picker

Brands

Single-Select Dropdown

Tags

Multi-Select Dropdown

Service Area

Single-Select Dropdown

Venue

Single-Select Dropdown

Service Types

Multi-Select Checkbox

## **6\. Error Message Handling**

# **Field/Action**

# **Validation Scenario**

# **Error Message**

# Search Results

# No matches found

# "No matching events found."

# General System

# Connection timeout

# "Something went wrong."

# Server error

# "Something went wrong."

## **7\. Edge Cases**

# **Scenario**

# **Expected Behavior**

# Event date changes from future to past

# Automatically move from Upcoming to Post-Event

# Event date changes from future to past

# Automatically move from Upcoming to Post-Event if payment is incomplete

# Database connection lost during operation

# Show error message

## **8\. Test Cases**

## **Link -** [**Pixally Test cases**](https://docs.google.com/spreadsheets/d/1RNM15mQt_Ax15liD7LeQZTvi_N01Hax4yZXSNIcN2dI/edit?gid=97704170#gid=97704170)

## **9\. Acceptance Criteria**

*   Contractors can view only events assigned to them; if none exist, all tabs display the empty state message “You have no events yet.”
*   The event list is global across all agencies, but detailed event data is viewable only within the active workspace.
*   Events from other agencies appear as read-only until the contractor switches to that agency’s workspace.
*   The module contains three tabs — **Upcoming**, **Post-Event**, and **Completed** — with **Upcoming** as the default view.
    *   **Upcoming Tab:** Displays events with today’s or future dates.
    *   **Post-Event Tab:** Displays past events where deliverables, invoices, or payments are still pending.
    *   **Completed Tab:** Displays past events where all deliverables and invoices are uploaded, and payment is fully received.
*   Events auto-transition between tabs based on event date and completion criteria.
*   Events are sorted by event date (ascending) by default; columns (Event Date, Project, Brand, Service Area) support bidirectional sorting.
*   The search bar allows real-time filtering by project name, event type, brand name, or service area.
*   If no matching results are found during the search, the system displays “No matching events found.”
*   The filter panel allows multi-criteria filtering by Event Type, Date Range, Brand, Tags, Service Area, Venue, and Service Type.
*   Brand and Service Area filters are interdependent; selecting one limits options in the other accordingly.
*   Applied filters appear as tags above the event list with “X” icons for individual removal and a “Clear All Filters” option for resetting all at once.
*   Status icons appear only in the **Upcoming** and **Post-Event** tabs.
*   In **Upcoming**, the Service Agreement icon shows filled when signed and empty when unsigned.
*   In **Post-Event**, icons indicate:
    *   Invoice Upload → Filled if uploaded, empty if not.
    *   Deliverables Upload → Filled if uploaded, empty if not.
    *   Payment Received → Empty (unpaid), half-filled (partial), or filled (fully paid).
*   Clicking **“View Details”** for an event under a different agency triggers a confirmation pop-up asking to switch studios.
*   Clicking **“Yes, Switch”** changes the current workspace to the event’s agency and redirects to the event details page.
*   Clicking **“Cancel”** closes the pop-up and retains the current workspace.
*   The studio selection persists until changed again in the same session.

**10\. Dependencies**

# **Module/System**

# **Dependency Type**

# **Impact if Unavailable**

# Payment Processing System

# Integration

# Cannot track payment completion, events stuck in the Post-Event tab

# User Management System

# Data Dependency

# Cannot assign users to events, no team avatar display, and login failures

# Brand/Agency Management

# Data Dependency

# Cannot enforce cross-brand access control, no brand switching

# Calendar/Date System

# Service Dependency

# Date-based status transitions fail, and incorrect tab filtering

# Authentication System

# Security Dependency

# Cannot validate cross-brand access; session management fails

# Notification System

# Service Dependency

# Users are not notified of status changes or payment requirements

# File Storage System

# Data Dependency

# User avatars not displayed, team assignment visuals fail, document uploads fail

# Geographic Services

# Data Dependency

# Service area validation fails, location display incomplete

# Reporting Module

# Data Consumer

# Historical reporting is missing event data from the Completed tab

# Search Index Service

# Performance Dependency

# Global search functionality degraded or non-functional

# Document Management

# Critical Dependency

# Agreement signing fails, timeline/guide downloads unavailable

# Audit Logging System

# Compliance Dependency

# Cannot track user actions, security events, and data changes

##

## **11\. References**

### **Figma Link -** [**Click Here**](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=13461-125366&t=qI39dRBohSA1mlSj-0)

### 

☑️ Event Details

# Event Details Screen - Contractor Portal

## **1\. Module Overview**

Attribute

Description

Module Name

Event Details Screen (Contractor Portal)

Purpose

Provide contractors with comprehensive visibility into their assigned event details, including service requirements, agreements, deliverables management, and invoice submission capabilities within a centralized interface

Business Goal

Enable contractors to access all event-specific information, manage service agreements, track deliverables, submit invoices, and maintain clear visibility into event requirements and documentation across their assigned events and agencies

## **2\. User Roles & Permissions**

Role

Description

Key Permissions

Portal Access

Contractor

Contractors assigned to specific events by agencies

View assigned event details only, download timeline and shooting guides, sign service agreements, view auto-captured events, complete questionnaires, upload invoices, and upload deliverables

Contractor Portal, Event Details Screen

## **3\. User Flow**

### Navigation Path

Contractors can access the Event Details Screen through three entry points:

*   Contractor Portal Side Menu → Events Module → Event Listing → View Details button
*   Contractor Portal → Dashboard → Event Card → Click event
*   Contractor Portal → Calendar Module → Event → Click event

### Step-by-Step Flow

1.  Step 1: Contractor clicks on an event from Event Listing, Dashboard, or Calendar Module
2.  Step 2: System validates if the event belongs to the current workspace agency
    *   If Yes: Directly opens Event Details Screen
    *   If No: Displays cross-brand workspace switch pop-up
3.  Step 3: Event Details Screen loads with project header, event cards, and Details tab selected by default
4.  Step 4: Contractor can navigate between the Details, Contractors, Finances, Files/Documents, and Notes tabs
5.  Step 5: Contractor can navigate between the Services sections for different services if assigned to multiple services in the event
6.  Step 6: Contractor can perform actions: download documents, sign agreements, view captured event status, complete questionnaires, upload invoices, and upload deliverables

## 4\. Functional Logic

### 4.1 Event Access & Workspace Validation

*   Contractors can only view event details for events to which they have been assigned by the agency
*   The contractor must be in the specific agency workspace that corresponds to the event's associated agency to view full event details

Cross-Workspace Access Control:

*   When a contractor attempts to access an event that belongs to a different agency workspace than their currently selected workspace, a confirmation pop-up appears asking to switch workspaces. Refer - [Click Here](https://claude.ai/chat/f25a671f-03a4-4147-be6f-c75f506b1bcc?tab=t.nqli9p8m68iv#bookmark=id.e64cmqeopr9y)

Access Entry Points:

*   Event Listing Module: Via "View Details" button
*   Dashboard: Via the event card, click on the events
*   Calendar Module: Via event click

### 4.2 Project Header Display Logic

The project header is displayed at the top of the Event Details Screen and includes the following elements:

Brand Primary Logo:

*   Displays the primary logo of the brand associated with the event's project

Project Banner Image:

*   Displays the header banner image as set by the agency for the project
*   If no banner is set, displays a default placeholder image

Project Status Badge:

*   Positioned in the top-right corner of the header
*   Displays the current status of the project as set by the agency (e.g., Active, Completed, Archived)

Project Name:

*   Displays the project name as set by the agency below the project status badge

Event Date Display Logic:

Below the project name, the event date is displayed with the following conditions:

*   If the contractor is assigned to only ONE event in the project: Display the single event date
*   If the contractor is assigned to MULTIPLE events in the same project: Display the date range showing the first event date and the last event date

Primary Service Area:

*   Displayed on the left side, below the project banner, with a location pin icon
*   Shows the primary service area associated with the event

### 4.3 Event Card Display Logic

Event cards are displayed below the project header and show only those events within the project to which the contractor is assigned.

Event Card Visibility Rules:

*   If a project has multiple events, but the contractor is assigned to only one event: Display only that one event card
*   If the contractor is assigned to multiple events in the same project: Display all assigned event cards

Event Card Positioning:

*   Event cards are ordered chronologically based on the event date, with the nearest upcoming event positioned first

Event Card Content:

*   Each event card displays: Event Name, Event Date, Event Stage Badge (as set by agency), and Assigned Users (first 3 profiles, +X for additional)

Event Card Selection Logic:

*   If only ONE event is assigned: That event card is auto-selected, and the Details tab is displayed
*   If MULTIPLE events are assigned: The event with the nearest upcoming event date is auto-selected by default
*   Contractors can manually click on any other event card to view its details
*   When an event card is selected, all tab content updates to show information specific to that selected event

### 4.4 Tab Navigation Structure

*   The Event Details Screen contains five main tabs: Details Tab (default selected), Contractors Tab, Finances Tab, Files/Documents Tab, and Notes Tab
*   Details Tab Auto-Selection: When the Event Details Screen loads, the Details tab is automatically selected and displays information for the auto-selected event
*   Tab Content Dynamic Update: When a contractor clicks on a different event card, all tab content dynamically updates to reflect the selected event's information

### 4.5 Services Section Display Logic

The Services section is displayed within the Details tab and shows all services for which the contractor is assigned to the selected event.

Service Type Display:

*   Service Name Header: Displays the service type name (e.g., "Photography", "Videography", "Content Creator")
*   If the contractor is assigned to multiple service types for the same event, each service is displayed in a separate section

Download SNAPSHOT Button:

*   On clicking, downloads a PDF snapshot summary of the event details
*   Snapshot displays the major details about the event:
    *   Brand's Primary logo
    *   Project Name
    *   Service area
    *   Event Details Section (Event Name, Event Date, Primary Venue, Brand Name)
    *   Service Name
    *   Timeline & Shooting Guide Download Button
    *   Contractor role, Coverage hours, Minimum amount of photos, Amount (Contractor Fee)
    *   Additional Fields (if applicable)
    *   Notes
    *   Contacts (Client's details): Client Full Name, Role, Email, Phone Number
    *   Contractors: Contractor Name, Specialization, Role, Email, Phone Number

Service-Specific Action Buttons:

*   Timeline Download Button: Provides a link within the PDF; on click, downloads the file to the user's local system
*   Shooting Guide Download Button: Displayed only if the agency has uploaded a shooting guide in brand settings; on click, downloads the file to the user's local system

### 4.6 Service Details Display

Below the service name header, the following service details are displayed in a grid layout:

*   Role Assignment: Displays role name with icon of the contractor as assigned by the agency (e.g., "Lead Shooter", "Second Shooter", "Assistant", "Drone Operator")
*   Coverage Hours: Displays number of hours of coverage as set by the agency (e.g., "8 hours")
*   Minimum Amount of Photos: Displayed ONLY for Photography service type; shows the minimum number of photos required as set by the agency
*   Service Amount: Displays contractor fee amount for the service assigned (e.g., "$400.00")

### 4.7 Service Note Display

*   Service Note Section: Displays the service note text as entered by the agency in the agency portal for the specific service in the event
*   If the agency has not added a service note, this section will not be displayed

### 4.8 Service Agreement Display & Signing Logic

The Service Agreement section displays the agreement document and signing status with different states based on the agreement's signing status by the contractor.

Agreement Display States:

State 1: Agreement Not Signed (Before Expiry)

When the service agreement has been sent but not yet signed, and the current date is before expiry:

*   Displays: Agreement name, event name, date sent, and "Sign Agreement" button
*   On clicking "Sign Agreement": Opens the service agreement document for the contractor to sign

State 2: Agreement Expired (Not Signed After Expiry Date)

When an agreement has an expiry date and remains unsigned, and the current date has passed the expiry date:

*   Displays: Agreement name, below agreement name displays "Expired on \[Date\]", event name, date on which the agreement was sent by the agency, and "View" button
*   On clicking "View": Opens the service agreement document
*   Note: Even if expired and unsigned, the contractor can still view event details and upload deliverables

State 3: Agreement Signed

When the contractor has successfully signed the service agreement:

*   Displays: Agreement name, event reference, date on which the agreement was sent by the agency, "Signed" badge with checkmark, and "View" button
*   On clicking "View": Opens the signed agreement document in read-only mode

### 4.9 Capture Event Section Logic

The Capture Event section displays the event information and automatically marks the event as captured when the event date/time is reached. There is no manual "Mark as Captured" button.

Event Information Display:

*   Displays the event name and event date in a single line format
*   This information is shown at all times (before and after the event date)

Automatic Capture Logic:

The system automatically marks the event as captured based on the following rules:

Event Type

Auto-Capture Trigger Time

Single-day event

11:00 AM on the event date

Multi-day event

11:00 AM on the event end date

Display States:

State 1: Before Event Date (Pre-Capture)

*   Displays: Event name and event date only
*   No action button is shown
*   The section serves as an informational display

State 2: After Auto-Capture (Post-Capture)

When the system time reaches 11:00 AM on the event date (or event end date for multi-day events):

*   The section automatically updates to show:
    *   Success message: "Event was captured successfully!" displayed in a green banner with a checkmark icon
    *   "Complete Questionnaire" button appears in green/primary color next to the success message

Complete Questionnaire Button Logic:

*   The "Complete Questionnaire" button is displayed only after the event has been auto-captured (11:00 AM on event date/end date)
*   On click: Opens the questionnaire associated with the event
*   If the agency has not sent any questionnaire, the button is not displayed
*   The button always links to the most recently sent questionnaire by the agency
*   Button text remains "Complete Questionnaire" regardless of whether the contractor has already completed it
*   Questionnaires are NOT mandatory for uploading deliverables

Post-Event Questionnaire Auto-Send Logic:

*   If the auto-toggle setting is enabled in the Questionnaire Module, the questionnaire is automatically sent at 12:00 PM (noon) on the event date (or event end date for multi-day events)
*   This occurs 1 hour after the auto-capture trigger (11:00 AM)
*   The agency can also send questionnaires manually at any time (before or after event date)
*   When sent manually, the latest questionnaire always replaces the previous one on the "Complete Questionnaire" button
*   All sent questionnaires (auto and manual) can be viewed in the Files/Documents tab with their created date and time

Event Progress Sidebar Update:

*   When the auto-capture triggers, the "Capture Event" step in the Event Progress sidebar automatically marks as complete
*   The "Post-Event Questionnaire" step updates based on questionnaire status

### 4.10 Upload Invoice Section Logic

The Upload Invoice section allows contractors to upload invoice documents at any time (before or after the event date).

Upload Functionality:

*   Contractors can upload invoices at any time, even before the event date
*   Multiple invoices can be uploaded for the same event

Upload Interface:

*   Displays a drag-and-drop upload area with a cloud upload icon
*   Text: "Drop or upload file here" with "+ Upload New Invoice" button

File Validation Rules:

*   Maximum file size: 15 MB per invoice
*   Allowed file format: PDF only

Uploaded Invoice Display:

When the invoice is successfully uploaded:

*   Displays: PDF document icon, invoice file name, event reference, upload date & time
*   Kebab menu icon: Provides options to Preview, Download PDF, or Delete the invoice

Invoice Upload Impact on Other Modules:

When an invoice is uploaded, the following updates occur automatically:

*   Agency Side - Project Details → Activity Tab: Invoice upload activity is logged
*   Agency Side - Contractors Tab: Invoice icon is displayed as filled
*   Contractor Side - Event Listing: Invoice upload icon is filled for the event in the Post-Event tab
*   Agency Side - Finances Module → Contractors Invoices → Unpaid Section: Invoice appears
*   Agency Side - Contractors Module → Contractor Profile: Invoice icon is filled for the event

### 4.11 Upload Deliverables Section Logic

The Upload Deliverables section allows contractors to submit event deliverables using three different delivery methods after the event date has passed.

Deliverables Upload Availability:

*   The Upload Deliverables section is displayed only after the event date has passed
*   Before the event date: This section is not visible

Delivery Method Selection:

*   Contractors can choose from three delivery methods, presented as tabs: Digital Delivery (default), Hard Drive, Other
*   Contractors can use multiple delivery methods for the same event (e.g., upload digital links AND send a hard drive)

#### 4.11.1 Digital Delivery Method

When the "Digital Delivery" tab is selected:

*   Contractors can add links to the deliverables
*   Maximum allowed links: 5 links total per event
*   Link validation: Links must be in a valid URL format
*   Each entered link is displayed as a separate row with the full URL visible
*   Each link row includes edit and delete icons
*   "+ Add Additional Link" button allows adding up to 5 links total
*   Once 5 links are added, the add button is disabled
*   Links can be edited or deleted at any time before final submission

#### 4.11.2 Hard Drive Delivery Method

When the "Hard Drive" tab is selected:

*   Tracking Number Input: Text input for entering the courier tracking number
*   Shipping Service Input: Text input for entering shipping/courier service name
*   Shipping Address Display: Displays the brand's business address as set by the agency in the agency portal (read-only)

#### 4.11.3 Other Delivery Method

When the "Other" tab is selected:

*   Note Input Field: Multi-line text area for entering delivery method details
*   Validation: Maximum 250 characters
*   Examples: "Gave it to Lead Shooter", "Hand-delivered to agency office"

#### 4.11.4 Deliverables Display In Project Details

When the contractor uploads the deliverables using any method, they will be displayed in the Agency Portal → Project Details → Event Details → Raw Media tab. Refer - [Click Here](https://docs.google.com/document/d/1JRbhA6wMQ6BtUWKlw63paM1s_sgaDy6PrjQHLw1suLk/edit?tab=t.4gonnhcom6re#bookmark=id.kplcbdd74n6d)

## 5\. Field Details & Validations

### 5.1 Capture Event Section

Field Name

Display Format

Validation Rules

Event Name

Text label

Read-only, displays event name as set by agency

Event Date

Date format (e.g., "Wed, Dec 19, 2025")

Read-only, displays event date or date range for multi-day events

Success Banner

Green banner with checkmark

Displayed only after auto-capture triggers at 11:00 AM

Complete Questionnaire Button

Primary/green button

Displayed only if questionnaire has been sent by agency; links to most recent questionnaire

### 5.2 Upload Invoice Section

Field Name

Display Format

Validation Rules

Upload Area

Drag-drop zone with cloud icon

Always visible, accepts PDF up to 15 MB

Upload New Invoice

Text button

Always enabled, allows multiple uploads

Invoice File & Event Name

Text with PDF icon

Displays the uploaded file & event name

Upload Date & Time

"Day Mon Year" and "HH:MM AM/PM"

Displays the invoice uploaded date and time

Kebab Menu

Kebab Options

Options: Preview, Download PDF, Delete

### 5.3 Upload Deliverables Section - Digital Delivery

Field Name

Display Format

Validation Rules

Link Input Field

Text input with checkbox icon

Required valid URL format, max 5 links total

Link Display

Full URL text with edit/delete icons

After the link input, each link is shown as a separate row

Add Additional Link Button

Text button

Enabled until 5 links are added, then disabled

### 5.4 Upload Deliverables Section - Hard Drive

Field Name

Display Format

Validation Rules

Tracking Number

Text input

Maximum 250 characters

Shipping Service

Text input

Maximum 250 characters

Shipping Address

Read-only text block

Displays the brand's business address, view only

### 5.5 Upload Deliverables Section - Other

Field Name

Display Format

Validation Rules

Delivery Method Note

Multi-line text area

Maximum 250 characters

## 6\. Error Message Handling

Field/Action

Validation Scenario

Error Message

Invoice Upload

File size exceeds 15 MB

"File size cannot exceed 15 MB limit."

Invoice Upload

File format is not PDF

"Only PDF files are allowed."

Digital Delivery Links

More than 5 links attempted

"Maximum 5 links allowed."

Digital Delivery Links

Invalid URL format

"Please enter a valid URL."

Hard Drive → Tracking Number

Tracking number exceeds 250 characters

"Tracking number cannot exceed 250 characters."

Hard Drive → Shipping Service

Shipping service exceeds 250 characters

"Shipping service name cannot exceed 250 characters."

Other Delivery Method

Note exceeds 250 characters

"Note cannot exceed 250 characters."

Timeline, Shooting Guide Download

Network error during download

"Something went wrong."

General System

Connection timeout

"Something went wrong."

## 7\. Edge Cases

Scenario

Expected Behavior

Contractor assigned to multiple events with the same date

Auto-select the first event in alphabetical order by event name

Event date changes after the event was auto-captured

Event remains marked as captured; no automatic status reversal

The agency deletes the uploaded timeline after the contractor views the event

The Timeline button is no longer displayed on the next page load

Contractor uploads invoice before event date

The invoice is accepted and displayed; all related modules update immediately

Agency updates service agreement after partial signing

Display notification about updated agreement; require re-signing

Contractor uploads 5 digital delivery links, then switches to Hard Drive

Both delivery methods are saved independently; can use multiple methods

The event date passes but contractor hasn't completed questionnaire

Deliverables section still displays; can upload without completing questionnaire

Contractor switches workspace while on Event Details Screen

Page reloads with event from newly selected workspace (if accessible)

Database connection lost during invoice upload

Display error: "Failed to upload invoice. Please check your connection."

Multiple contractors upload different invoices simultaneously

All invoices are accepted and displayed with the respective uploader information

Agency removes contractor from event while viewing details

Display message "You no longer have access to this event" and redirect

Event date is "TBD" (no specific date set)

Auto-capture cannot trigger; contractor must wait for agency to set a date; Upload Deliverables section is not displayed

Contractor completes questionnaire but doesn't upload deliverables

Questionnaire responses saved; no dependency on deliverables upload

The service agreement expires during the signing session

Display expiry notification; prevent signing; show "View" button only

Contractor uploads deliverables before completing questionnaires

Deliverables upload succeeds; questionnaires remain optional

Agency sends questionnaire manually before event date

Allowed; "Complete Questionnaire" button appears only after auto-capture (11:00 AM on event date)

Agency sends multiple questionnaires manually

Latest questionnaire replaces previous on the "Complete Questionnaire" button; all sent questionnaires visible in Files/Documents tab

Auto-toggle for questionnaire turned ON after event date has passed

Auto-send logic only applies to future events; does not retroactively send for past events

Multi-day event: when does auto-capture trigger?

Auto-capture triggers at 11:00 AM on the event END date

Multi-day event: when is questionnaire auto-sent?

Questionnaire auto-sent at 12:00 PM noon on the event END date (if auto-toggle is ON)

## 8\. Acceptance Criteria

*   Contractors can only access event details for events explicitly assigned to them by the agency
*   Contractors must be in the correct agency workspace to view full event details; accessing from a different workspace triggers a confirmation pop-up
*   Contractors can access the Event Details Screen from the Event Listing, Dashboard, and Calendar Module
*   Cross-workspace pop-up displays agency name and provides "Cancel" and "Yes, Switch" options
*   Clicking "Yes, Switch" changes the workspace and opens event details; "Cancel" keeps the current workspace
*   Project header displays brand's primary logo, project banner, status badge, project name, event date(s), and primary service area
*   Event date displays as a single date if one event is assigned, or a date range if multiple events are assigned
*   The Download SNAPSHOT button generates and downloads a PDF with event details
*   Event cards display only events assigned to the contractor within the project
*   Event cards show event name, date, stage badge, and assigned users (first 3, then +X indicator)
*   Event cards are ordered chronologically by event date (nearest upcoming first)
*   If one event is assigned, the event is auto-selected and the Details tab is displayed
*   If multiple events are assigned, the nearest upcoming event is auto-selected by default
*   Clicking an event card updates all tab content to show the selected event's information
*   Details tab is auto-selected on page load
*   The Services section displays the service type name (Photography, Videography, Content Creator)
*   The Timeline button displays only if the agency uploaded a timeline; clicking downloads the timeline file
*   The Shooting Guide button displays only if the agency has uploaded a guide in brand settings; clicking downloads the guide file
*   Service details display Role, Coverage hours, Min Amount of Photos (Photography only), and Service Amount
*   The Service Note section displays only if the agency added a note; hidden if no note exists
*   Service Agreement displays with three states: Unsigned (with Sign button), Expired (with View button), Signed (with View button and Signed badge)
*   Agreement displays document icon, name, event reference, date sent, and appropriate action button
*   Expired agreements still allow contractors to view event details and upload deliverables
*   Capture Event section displays event name and date at all times (before and after event date)
*   No manual "Mark as Captured" button exists; capture is fully automatic
*   Event is automatically marked as captured at 11:00 AM on the event date (or event end date for multi-day events)
*   After auto-capture, success message "Event was captured successfully!" displays with "Complete Questionnaire" button
*   "Complete Questionnaire" button appears only after auto-capture and only if agency has sent a questionnaire
*   "Complete Questionnaire" button always links to the most recently sent questionnaire
*   Button text remains "Complete Questionnaire" regardless of completion status
*   If auto-toggle is ON, questionnaire is auto-sent at 12:00 PM noon on event date (or event end date for multi-day events)
*   Agen

cy can send questionnaires manually at any time; latest always replaces previous on the button
*   All sent questionnaires are visible in Files/Documents tab with created date and time
*   Event Progress sidebar "Capture Event" step auto-completes when auto-capture triggers
*   Questionnaires are not mandatory for uploading deliverables
*   The Upload Invoice section is always visible and allows uploads at any time (before or after the event)
*   Contractors can upload multiple invoices for the same event
*   Invoice uploads accept only PDF format with maximum 15 MB file size
*   Uploaded invoices display with file name, event reference, upload date/time, and kebab menu
*   Invoice uploads automatically update the Agency Activity Tab, Event Listing icons, Finances module, and Contractor Profile
*   The Upload Deliverables section displays only after the event date has passed
*   Deliverables can be uploaded via three methods: Digital Delivery, Hard Drive, or Other
*   Contractors can use multiple delivery methods simultaneously for the same event
*   Digital Delivery allows maximum of 5 links with valid URL format
*   Digital Delivery links can be edited or deleted at any time
*   Hard Drive method requires Tracking Number (max 250 chars) and Shipping Service (max 250 chars)
*   Hard Drive displays the brand's business address as read-only shipping address
*   Other method accepts notes up to 250 characters
*   All error messages display appropriately for file size, format, character limits, and URL validation
*   Cross-workspace access control applies from all entry points (Event Listing, Dashboard, Calendar)
*   Workspace selection persists throughout the session until manually changed
*   Edge cases handled: multiple events same date, date changes post-capture, deleted documents, simultaneous uploads, TBD events, manual questionnaire sending

## 9\. Dependencies

Module/System

Dependency Type

Impact if Unavailable

User Management System

Data Dependency

Cannot validate contractor assignment to events, no access control, and login failures

Brand/Agency Management

Data Dependency

Cannot enforce cross-workspace access control, no brand logo/address display, workspace switching fails

Project Management System

Data Dependency

Cannot load project information, header banner missing, event details unavailable

Document Management System

Critical Dependency

Timeline and shooting guide downloads fail, service agreements cannot be signed, and invoice/deliverables uploads fail

Authentication System

Security Dependency

Cannot validate contractor identity and permissions; cross-workspace validation fails

File Storage System

Data Dependency

Document uploads/downloads fail, logo and banner images not displayed

Questionnaire Module

Feature Dependency

Complete Questionnaire button not displayed, questionnaire responses not saved, auto-send logic unavailable

Finances Module

Data Consumer

Invoices not reflected in the Contractor Invoices section, payment tracking is incomplete

System Clock/Scheduler

Critical Dependency

Auto-capture timing fails, questionnaire auto-send fails

## 10\. References

*   Figma Design: [Click Here](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=13461-159143&t=qI39dRBohSA1mlSj-0)
*   Questionnaire Module FRD: Refer for auto-toggle settings and questionnaire configuration
*   Agency Portal - Project Details FRD: [Click Here](https://docs.google.com/document/d/1JRbhA6wMQ6BtUWKlw63paM1s_sgaDy6PrjQHLw1suLk/edit?tab=t.4gonnhcom6re#bookmark=id.kplcbdd74n6d)

☑️ Contractors Tab

# **Contractors Tab**

# **1\. Module Overview**

*   **Module Name:** Contractors Tab (Event Details Screen - Contractor Portal)
*   **Purpose:** Provide contractors with visibility into all assigned contractors for each service within an event, displaying role assignments, contractor details, and personal progress indicators (agreement signing, invoice submission, deliverables upload, and payment status) for the logged-in contractor
*   **Business Goal:** Enable contractors to understand the complete team structure for an event, identify other contractors they will be working with across different services, and track their own service-specific progress through visual status indicators

## **2\. User Roles & Permissions**

**Role**

**Description**

**Key Permissions**

Contractor

Contractors assigned to specific events by agencies

View all service tabs within the event, view assigned contractor details for each service (role, name, avatar, specialization), view own detailed progress card with status icons, and view distance to event venue

## **3\. User Flow**

**Navigation Path:** Contractor Portal > Event Details Screen > Contractors Tab

**Step-by-Step Flow:**

**Step 1:** Contractor accesses Event Details Screen from Event Listing, Dashboard, or Calendar Module

**Step 2:** Contractor clicks on the "Contractors" tab from the tab navigation (Details, Contractors, Finances, Files)

**Step 3:** System loads the Contractors tab with service tabs displayed horizontally

**Step 4:** The System auto-selects the service tab to which the logged-in contractor is assigned

**Step 5:** The Selected service tab displays all role cards for that service, showing assigned contractors and unassigned roles

**Step 6:** The Contractor can navigate between service tabs to view contractor assignments for other services in the event

**Step 7:** The Contractor can view their own detailed card with progress icons when viewing the service they are assigned to

## **4\. Functional Logic**

### **4.1 Service Tab Display Logic**

*   **Service Tabs Visibility:**
    *   The Contractors tab displays service tabs for ALL services configured for the event by the agency
    *   Service tabs are displayed regardless of whether the logged-in contractor is assigned to that specific service
    *   This allows contractors to view the complete team structure across all services for the event they are assigned to
*   **Service Tab Types:**
    *   Photography
    *   Videography
    *   Content Creation
*   **Service Tab Display Rules:**
    *   If the event has only one service configured, only that service tab is displayed
    *   If the event has multiple services configured (e.g., Photography and Videography), all configured service tabs are displayed
    *   Example: If an event has Photography and Videography services but not Content Creation, only Photography and Videography tabs appear
*   **Service Tab Auto-Selection:**
    *   When the Contractors tab loads, the system automatically selects the service tab to which the logged-in contractor is assigned
    *   Example: If the logged-in contractor is assigned to the Photography service, the Photography tab is displayed by default.
*   **Service Tab Manual Navigation:**
    *   Contractors can click on any service tab to view contractor assignments for that service
    *   Clicking a different service tab updates the content area to display role cards for the selected service
    *   The selected tab visual indicator moves to reflect the current selection

### **4.2 Role Card Display Logic**

*   **Contractor Cards Container:**
    *   Below the service tabs, a card container area displays all role cards for the selected service
    *   Each role card represents a contractor role as assigned by the agency for that service
*   **Role Card Visibility Rules:**
    *   All roles configured by the agency for the selected service are displayed as individual cards
    *   If a role has an assigned contractor, the card displays the contractor's information
    *   If a role has no assigned contractor, the card displays a "Unassigned" placeholder
    *   Example: If the Photography service has Lead Shooter, Second Shooter, and Drone Operator roles configured, three role cards are displayed
    *   Role cards are ordered based on role hierarchy or the order set by the agency (Lead shooter < Second shooter < Assistant < Drone Operator)

### **4.3 Other Contractors Card**

*   The contractor can only see other contractors who are assigned to the same event as the contractor is assigned and it will show roles, Avatars, Full Names, and Service specializations.
*   No status icons, financial information, or distance information are displayed (agreement, invoice, deliverables, payment)
*   **Card Header Section:**
    *   **Role Name Badge:** Displays the role name and role icon assigned to the contractor (e.g., "Second shooter")
*   **Contractor Information Display:**
*   **Profile Avatar:**
    *   Displays the contractor profile photo If no photo is uploaded, it displays the default initials
*   **Full Name:** Displays contractor's full name below the avatar
*   **Service Specialization:** Displays the contractor's specialization below the name
    *   Example: "Photographer", "Videographer", "Content Creator"

###

### **4.4 Logged-In Contractor Card Display (Self View)**

**Card Header Section:**

*   **Role Name Badge:** Displays the role name assigned to the logged-in contractor (e.g., "Lead Shooter")
*   **Role Icon:** Icon indicator matching the role type
*   **"You" Tag:** A distinct "You" badge or tag is displayed next to the role name
    *   Tag is visually prominent (e.g., blue badge with white text)
    *   Clearly identifies this card as the logged-in contractor's own assignment
    *   Format: "Lead Shooter" with "You" badge adjacent

**Contractor Information Display:**

*   **Profile Avatar:** Circular profile image of the logged-in contractor
    *   Displays the contractor's own profile photo
    *   If no photo is uploaded, it displays the default avatar or initials (i.e., John Doe - JD)
*   **Full Name:** Displays contractor's full name below the avatar
*   **Service Specialization:** Displays the contractor's specialization below the avatar
    *   Example: "Photographer"
    *   Displayed in smaller, lighter text (name may be omitted since "You" tag identifies the user)

**Status Icons Section:**

*   Four status icons are displayed in a horizontal row below the specialization
*   Icons provide visual progress tracking for the contractor's service obligations
*   Icon States: Empty (not completed), Filled (completed), Partially Filled (in progress - for payment only)

**Icon 1 - Service Agreement Signed:**

*   **Icon Type:** Document or contract icon with checkmark
*   **Empty State:** The Service agreement has not been signed by the contractor
*   **Filled State:** Service agreement has been successfully signed
*   **Logic:** Icon fills when the contractor signs their service agreement for this event

**Icon 2 - Invoice Uploaded:**

*   **Icon Type:** Invoice or receipt document icon
*   **Empty State:** No invoice has been uploaded for this event
*   **Filled State:** At least one invoice PDF has been uploaded
*   **Logic:** Icon fills when contractor uploads their first invoice (additional invoices don't change state)

**Icon 3 - Deliverables Submitted:**

*   **Icon Type:** Upload or delivery package icon
*   **Empty State:** No deliverables have been submitted
*   **Filled State:** At least one deliverable has been submitted via any method (Digital Delivery, Hard Drive, or Other)
*   **Logic:** Icon fills when contractor submits deliverables using any of the three delivery methods

**Icon 4 - Payment Received:**

*   **Icon Type:** Currency or payment icon
*   **Empty State:** No payment has been received from the agency (Amount Paid = $0)
*   **Partially Filled State:** Some payment has been received but not the full contractor fee (Amount Paid > $0 but < Event Price)
*   **Fully Filled State:** Full contractor fee has been received (Amount Paid = Event Price)
*   **Logic:**
    *   Empty: No payments recorded
    *   Partially Filled: Any amount greater than $0 but less than total fee
    *   Fully Filled: Total amount equals or exceeds contractor fee

**Financial Information Display:**

*   **Event Price Label:** "Event Price" text label
*   **Event Price Value:** Displays contractor fee for the service assignment
    *   Format: "$X,XXX.XX" (e.g., "$1,200.00")
    *   This is the total amount the contractor is owed for the service
*   **Amount Paid Label:** "Amount Paid" text label
*   **Amount Paid Value:** Displays total payments received to date from the agency
    *   Format: "$XXX.XX" (e.g., "$800.00")
    *   Updates as the agency makes payments
    *   Shows "$0.00" if no payments have been made

**Distance to Event Venue Display:**

*   **Distance Label:** "Xm. to location" or "X miles to location"
*   **Distance Value:** Calculated distance from contractor's registered address to event venue
    *   Format: "12m. to location" or "12 miles to location"
*   **Location Display:** Event venue city and country
    *   Format: "City, Country" (e.g., "Boston, USA")
*   **Distance Calculation Logic:**
    *   Source: Contractor's registered business address (from contractor profile)
    *   Destination: Event venue address (as set by agency)
    *   Unit: Miles (or kilometers based on regional settings)
    *   If contractor has not set a registered address: Display "N/A" or "Address not set"
    *   If event venue is not set: Display "Venue TBD"

**Card Interaction:**

*   The logged-in contractor's card is view-only
*   No click actions are available
*   Information updates automatically when status changes occur (e.g., agreement signed, payment received)

### **4.5 Unassigned Role Card Display**

**Card Header Section:**

*   **Role Name Badge:** Displays the role name as configured by the agency (e.g., "Drone Operator")
*   **Role Icon:** Icon indicator matching the role type (e.g., star or role-specific icon)
*   Badge includes colored indicator (e.g., "+" symbol or distinct color to indicate vacancy)

**Placeholder Content:**

*   **Avatar Area:** Displays a placeholder icon (e.g., question mark "?" inside a circle)
*   **Unassigned Text:** Below the placeholder, displays "Unassigned" text
    *   Text is displayed in gray or muted color
    *   No additional information is shown (no specialization, no icons, no financial data)

**Purpose:**

*   Indicates that the agency has configured this role for the service but has not yet assigned a contractor
*   Provides transparency into the complete team structure and any staffing gaps
*   Contractors can see if additional team members are expected to be assigned

### **4.6 Cross-Service Viewing**

**Viewing Other Service Tabs:**

*   When a contractor clicks on a service tab they are NOT assigned to:
    *   Service tab becomes selected (visual indicator updates)
    *   Content area updates to show role cards for that service
    *   All assigned contractors for that service are displayed with their basic information (role, name, avatar, specialization)
    *   No "You" tag appears since the logged-in contractor is not assigned to that service
    *   All cards display as "Other Contractor" cards (minimal information)
    *   Unassigned roles are displayed with placeholder cards

**Example Scenario:**

*   Logged-in contractor is assigned to Photography as Lead Shooter
*   Event also has Videography service with two roles configured
*   Contractor clicks on Videography tab:
    *   Displays Videography contractor cards
    *   Shows other contractors' basic information
    *   No detailed progress icons or financial data visible
    *   Contractor understands Videography team structure

### **4.7 Data Synchronization**

**Real-Time Updates:**

*   Status icons on the logged-in contractor's card update automatically when:
    *   Service agreement is signed (Agreement icon fills)
    *   Invoice is uploaded (Invoice icon fills)
    *   Deliverables are submitted (Deliverables icon fills)
    *   Payment is received from agency (Payment icon updates to partial or full)

**Cross-Module Data Sources:**

*   **Service Agreement Status:** Retrieved from Service Agreement module
*   **Invoice Upload Status:** Retrieved from Upload Invoice section
*   **Deliverables Submission Status:** Retrieved from Upload Deliverables section
*   **Payment Status:** Retrieved from Finances module (agency-side payment records)
*   **Event Price:** Retrieved from service assignment as configured by agency
*   **Distance Calculation:** Retrieved from contractor profile address and event venue address

## **5\. Field Details & Validations**

### **5.1 Service Tabs**

**Field Name**

**Display Format**

**Validation Rules**

Service Tab Name

Text button (e.g., "Photography")

Only event-configured services displayed

Tab Selection Indicator

Underline, bold, or background highlight

One tab selected at a time

Auto-Selected Tab

Service contractor is assigned to

Defaults to assigned service on load

### **5.2 Role Badge**

**Field Name**

**Display Format**

**Validation Rules**

Role Name

Text with background badge (e.g., "Lead Shooter ★")

As configured by agency

Role Icon

Small icon next to role name

Matches role type

"You" Tag

Badge with "You" text and user icon

Displayed only for logged-in contractor's card

### **5.3 Contractor Information (Other Contractors)**

**Field Name**

**Display Format**

**Validation Rules**

Profile Avatar

Circular image

Default placeholder if no image uploaded

Full Name

"First Name Last Name"

Retrieved from contractor profile

Service Specialization

Text below name (e.g., "Photographer")

Retrieved from contractor profile

### **5.4 Contractor Information (Self - Logged-In Contractor)**

**Field Name**

**Display Format**

**Validation Rules**

Profile Avatar

Circular image

Default placeholder if no image is uploaded

Service Specialization

Text below avatar (e.g., "Photographer")

Retrieved from contractor profile

Agreement Icon

Document icon (Empty/Filled)

Fills when the agreement is signed

Invoice Icon

Invoice icon (Empty/Filled)

Fills when at least one invoice is uploaded

Deliverables Icon

Upload icon (Empty/Filled)

Fills when any deliverable is submitted

Payment Icon

Currency icon (Empty/Partial/Full)

Empty: $0, Partial: >$0 <full, Full: =full amount

Event Price

"$X,XXX.XX"

Contractor fee as set by the agency

Amount Paid

"$XXX.XX"

Total payments received to date

Distance

"Xm. to location."

Calculated from contractor's address to the venue

Location

"City, Country" (e.g., "Boston, USA")

Event venue location

### **5.5 Unassigned Role Card**

**Field Name**

**Display Format**

**Validation Rules**

Role Name Badge

Text with badge (e.g., "Drone Operator +")

As configured by the agency

Placeholder Icon

Question mark "?" in circle

Always displayed for unassigned roles

Unassigned Text

"Unassigned" in gray text

Always displayed for unassigned roles

## **6\. Error Message Handling**

**Field/Action**

**Validation Scenario**

**Error Message**

Service Tab Load

No services configured for event

"No services configured for this event."

Service Tab Load

Service data retrieval fails

"Unable to load service information. Please try again."

Contractor Data Load

Failed to retrieve contractor information

"Unable to load contractor details. Please refresh the page."

Distance Calculation

Contractor address not set

Display "N/A" instead of distance

Distance Calculation

Event venue not set

Display "Venue TBD" instead of the location

Distance Calculation

Calculation service unavailable

Display "Distance unavailable."

Payment Status

Payment data retrieval fails

Display empty icon as fallback

Profile Avatar

Image fails to load

Display default avatar placeholder

General System

Network connection lost

"Connection lost. Please check your internet connection."

## **7\. Edge Cases**

**Scenario**

**Expected Behavior**

The event has only one service configured

Only one service tab is displayed; the tab is auto-selected

All roles in a service are unassigned

All cards display as "Unassigned" placeholders

Contractor's registered address is not set

Distance field displays "N/A" or "Address not set."

The event venue address is not set

Location displays "Venue TBD."

Contractor receives overpayment (Amount Paid > Event Price)

Payment icon displays as fully filled; Amount Paid shows the actual amount received

Agency removes contractor from event while viewing tab

Display message "You no longer have access to this event" and redirect

Agency adds new role to service after contractor loads page

New role appears on the next page refresh

The agency removes a role from service after the contractor loads the page

Role card no longer displays on next page refresh

Multiple contractors have the same name

Each displays their unique profile avatar and role differentiation

The contractor profile photo is a very large file

System resizes/compresses for display in the avatar circle

Service has more than 10 roles configured

All role cards display; layout adjusts to accommodate (grid wrapping)

Payment status updates while the contractor is viewing the page

Icon updates automatically via real-time sync

Contractor signs agreement while on the Contractors tab

The agreement icon fills immediately upon successful signing

## **8\. Test Cases**

Link - \[To be added\]

## **9\. Acceptance Criteria**

**Service Tab Display:**

*   Service tabs display all services configured for the event by the agency
*   Service tabs are visible regardless of contractor's assignment status
*   Only event-configured services appear as tabs (non-configured services are hidden)
*   Service tab auto-selects the service to which the logged-in contractor is assigned on page load

**Service Tab Navigation:**

*   Clicking on a service tab updates the content area to show that service's contractor cards
*   Tab selection indicator (underline, highlight) moves to reflect current selection
*   Contractors can freely navigate between all service tabs

**Role Card Display:**

*   All roles configured by the agency for the selected service display as individual cards
*   Role cards show the role name badge with an icon
*   Assigned contractor cards display contractor information
*   Unassigned roles display a placeholder card with a "?" icon and "Unassigned" text

**Other Contractor Cards:**

*   Display role name badge, profile avatar, full name, and service specialization only
*   No status icons are displayed
*   No financial information is displayed
*   No distance information is displayed
*   Cards are view-only with no click actions

**Logged-In Contractor Card (Self View):**

*   Displays "You" tag badge prominently next to role name
*   Shows profile avatar and service specialization
*   Displays four status icons: Agreement, Invoice, Deliverables, Payment
*   The agreement icon fills when the service agreement is signed
*   The invoice icon fills when at least one invoice is uploaded
*   Deliverables icon fills when any deliverable is submitted (Digital, Hard Drive, or Other)
*   The payment icon shows empty (no payment), partially filled (some payment), or fully filled (full payment)
*   Displays Event Price (contractor fee) and Amount Paid (payments received to date)
*   Shows the distance from the contractor's registered address to the event venue
*   Displays event venue, city and country
*   The card is view-only with no click actions

**Distance Calculation:**

*   Distance calculated from the contractor's registered business address to the event venue
*   Displays in miles (or regional unit)
*   Shows "N/A" if the contractor address is not set
*   Shows "Venue TBD" if the event venue is not configured

**Data Accuracy:**

*   Status icons reflect real-time data from respective modules
*   Financial information matches the agency-configured contractor fee
*   Amount Paid updates as the agency processes payments
*   All contractor information was retrieved from verified profile data

**Cross-Service Viewing:**

*   Contractors can view other service tabs to see the team structure
*   Other services display all assigned contractors with basic information
*   Unassigned roles in other services display placeholder cards
*   Privacy is maintained by showing only professional information for other contractors

## **10\. Dependencies**

**Module/System**

**Dependency Type**

**Impact if Unavailable**

User Management System

Data Dependency

Cannot validate contractor identity, unable to determine which card gets "You" tag

Contractor Profile System

Data Dependency

Cannot retrieve contractor names, avatars, specializations, or registered addresses

Event Service Configuration

Data Dependency

Cannot determine which service tabs to display or which roles exist

Service Agreement Module

Status Dependency

Cannot determine agreement signing status; icon remains in empty state

Invoice Upload System

Status Dependency

Cannot determine invoice upload status; icon remains in empty state

Deliverables Submission System

Status Dependency

Cannot determine deliverables submission status; icon remains in empty state

Finances/Payment Module

Status Dependency

Cannot retrieve payment data; payment icon remains empty, Amount Paid shows $0

Geolocation/Distance Service

Feature Dependency

Distance calculation fails; displays "Distance unavailable."

File Storage System

Data Dependency

Profile avatars fail to load; display default placeholder

Event Venue Data

Data Dependency

Location information unavailable; displays "Venue TBD."

**11\. References**

Link - [click here](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=10517-38484&t=P4kOYrtfKXAaYrmP-0)

☑️ Finances Tab

# **Finances Tab - Event Details Screen (Contractor Portal)**

## **1\. Module Overview**

*   **Module Name:** Finances Tab (Event Details Screen - Contractor Portal)
*   **Purpose:** Provide contractors with comprehensive financial visibility for their event assignments, including total event fee, pending payments, received payments, invoice creation capabilities, and complete payment history tracking
*   **Business Goal:** Enable contractors to manage their event-related finances efficiently, track payment status from agencies, create and submit invoices, and maintain clear visibility into all financial transactions associated with their event assignments

## **2\. User Roles & Permissions**

**Role**

**Description**

**Key Permissions**

Contractor

Contractors assigned to specific events by agencies

View total event price (contractor fee), view pending and received payment amounts, create new invoices, view invoice and payment history, and preview and download invoices

## **3\. User Flow**

**Navigation Path:** Contractor Portal > Event Details Screen > Finances Tab

**Step-by-Step Flow:**

**Step 1:** Contractor accesses Event Details Screen from Event Listing, Dashboard, or Calendar Module

**Step 2:** Contractor clicks on the "Finances" tab from the tab navigation (Details, Contractors, Finances, Files)

**Step 3:** System loads the Finances tab, displaying the Payments section header

**Step 4:** Payment summary card displays Total Event Price, Pending Amount, and Payments Received

**Step 5:** The Contractor can click the "Create Invoice" button to open the invoice creation pop-up

**Step 6:** The Invoice and payment history table displays all invoices (created and uploaded) with status, dates, amounts, and actions

**Step 7:** The Contractor can use the action menu to preview or download an individual invoice

## **4\. Functional Logic**

### **4.1 Finances Tab Overview**

**Tab Header:**

*   Tab is labeled "Finances" in the tab navigation bar
*   When selected, the tab is visually highlighted (underline or bold indicator)
*   Tab content displays below the tab navigation area

**Section Header:**

*   Main section heading displays "Payments" at the top of the tab content
*   Heading is displayed in bold, larger font size
*   Provides context that this section focuses on payment-related information

### **4.2 Payment Summary Card**

**Card Layout:**

*   The payment summary is displayed within a bordered card container
*   The card has a slight shadow or border to distinguish it from the background
*   All financial summary information is contained within this card

**Total Event Price Display:**

*   **Label:** "Total Event Price" displayed as a section heading within the card
*   **Value:** amount displayed below the label (e.g., "$14,200")
*   **Data Source:** Contractor fee for the event service as set by the agency during contractor assignment
*   **Logic:** Retrieves the contractor's assigned fee for their specific service and role in the event
*   **Example:** If the contractor is assigned as Lead Shooter for Photography service at $1,200, displays "$1,200"

**Pending Amount Display:**

*   **Label:** "Pending Amount" displayed on the left side
*   **Value:** Dollar amount displayed on the right side of the same row
    *   Format: "X,XXX"or"X,XXX" or " X,XXX"or"X,XXX.XX" (e.g., "$7,100")
*   **Calculation Logic:**
    *   Pending Amount = Total Event Price - Payments Received
    *   Example: $14,200 (Total) - $11,800 (Received) = $2,400 (Pending)
*   **Dynamic Update:** Updates automatically when the agency makes payments
*   **Zero State:** If fully paid, displays "$0" or "$0.00."

**Payments Received Display:**

*   **Label:** "Payments Received" displayed on the left side
*   **Value:** Amount displayed on the right side of the same row (e.g., "$11,800")
*   **Data Source:** Sum of all payments marked as "Received" by the agency
*   **Calculation Logic:** Aggregates all payment amounts where the status is "Received."
*   **Dynamic Update:** Updates in real-time when the agency processes and marks payments as paid
*   **Zero State:** If no payments received, displays "$0.00"

### **4.3 Create Invoice Button**

**Button Display:**

*   **Button Text:** "Create Invoice"
*   **Button Style:** Primary action button with yellow/orange brand color, full width within the card
*   **Button Position:** Below the Payments Received row, prominently positioned
*   **Button State:** Always enabled, allowing contractors to create invoices at any time

**Button Click Action:**

*   Opens a pop-up modal for invoice creation
*   Invoice creation functionality is planned for the next phase
*   Pop-up will contain invoice creation form fields (to be defined in future phase)
*   A contractor can create multiple invoices for the same event
*   No validation restricts total invoice amounts against the Total Event Price

**Post-Creation Behavior:**

*   After successful invoice creation, the new invoice appears in the invoice table below
*   The invoice is assigned "Issued" status
*   Payment summary amounts remain unchanged until the agency marks the invoice as paid

###

### **4.4 Invoice and Payment History Table**

**Table Position:**

*   Displayed below the Payment Summary Card
*   Full width of the Finances tab content area
*   Separated from the summary card by spacing or a divider

**Table Purpose:**

*   Displays the complete history of all invoices associated with the event
*   Includes invoices created via the "Create Invoice" button
*   Includes invoices uploaded as PDFs from the Details tab
*   Provides payment tracking and invoice management

**Table Column Structure:**

Column 1 - Status:

*   **Header:** "Status"
*   **Display:** Color-coded status badge
*   **Possible Values:**
    *   **"Issued"** - Orange/yellow badge indicating invoice created, but payment not yet received
    *   **"Received"** - Green badge indicating payment has been received from the agency
*   **Badge Styling:** Rounded badge with contrasting text color for visibility

Column 2 - Payment Date:

*   **Header:** "Payment Date"
*   **Logic Based on Status:**
    *   **For "Received" status:** Displays the date and time when the payment was marked as paid by the agency
    *   **For "Issued" status:** Displays "--" (double dash) indicating no payment date yet
*   **Data Source:** Timestamp recorded when the agency marks the invoice as paid in their portal

Column 3 - Due Date:

*   **Header:** "Due Date"
*   **Display Format:** "Mon DD, YYYY" (e.g., "Jan 23, 2025")
*   **Data Source:**
    *   For created invoices: Due date set during invoice creation
    *   For uploaded invoices: Due date entered by contractor during upload in the Details tab
*   **Logic:** Displays the expected payment deadline as specified by the contractor

Column 4 - Amount:

*   **Header:** "Amount"
*   **Data Source:**
    *   For created invoices: Amount specified during invoice creation
    *   For uploaded invoices: Amount manually entered by contractor during upload
*   **No Validation:** Amount can be any value; no restriction based on Total Event Price or Pending Amount

Column 5 - Action:

*   **Header:** "Action"
*   **Display:** Kebab menu for each row
*   **Click Action:** Opens dropdown menu with action options

**Action Menu Options:**

Preview Option:

*   **Menu Item:** "Preview"
*   **Action:** Opens the invoice document in a preview modal or viewer
*   **For Created Invoices:** Displays system-generated invoice format
*   **For Uploaded Invoices:** Displays the uploaded PDF in the viewer

Download Option:

*   **Menu Item:** "Download"
*   **Action:** Downloads the invoice file to the contractor's local system
*   **File Format:** PDF format
*   **File Naming:** Invoice file name or system-generated name with event/date reference

### **4.5 Table Data Display Logic**

**Data Population:**

*   The table automatically populates with all invoices associated with the selected event
*   Includes both system-created invoices (via Create Invoice) and uploaded invoices (via Details tab)
*   All invoices display in a unified format regardless of creation method

**Table Sorting:**

*   Each column header (except Status & Action) includes a sort arrow
*   Clicking the column header sorts the table by that column
*   Default sort: Most recent first (by Payment Date or Due Date)
*   Sort order toggles between ascending and descending on repeated clicks

**Empty State:**

*   If no invoices exist for the event, the table displays an empty state message
*   Message: "No invoices found" or "No invoices created yet."
*   The Create Invoice button remains available above the empty table

**Table Scrolling:**

*   If multiple invoices exist, the table supports vertical scrolling
*   Table headers remain fixed during scroll for reference
*   Pagination may apply if the invoice count exceeds the display limit

### **4.6 Invoice Upload Integration (From Details Tab)**

**Uploaded Invoice Display:**

*   Invoices uploaded via the "Upload Invoice" section in the Details tab automatically appear in the Finances table
*   Integration is seamless - no manual sync required
*   Uploaded invoices display with same column structure as created invoices

**Uploaded Invoice Data Mapping:**

*   **Status:** Initially set to "Issued" upon upload
*   **Payment Date:** Displays "--" until the agency marks it as paid
*   **Due Date:** Displays date entered by contractor during upload process
*   **Amount:** Displays the amount manually entered by the contractor during upload
*   **Action:** Same preview and download options available

**Status Update Flow:**

*   When the agency views the uploaded invoice and processes the payment
*   The agency marks the invoice as paid in their portal
*   Status changes from "Issued" to "Received"
*   Payment Date populates with the timestamp of the payment marking
*   Payments amount received in the summary card increases accordingly
*   Pending Amount decreases accordingly

### **4.7 Real-Time Data Synchronization**

**Automatic Updates:**

*   Payment summary card updates automatically when:
    *   The agency processes a payment and marks the invoice as paid
    *   Payments Received increase by the payment amount
    *   Pending Amount decreases by the payment amount
    *   Invoice status changes from "Issued" to "Received"
    *   The Payment Date populates for the paid invoice

**Cross-Module Sync:**

*   Finances tab data syncs with:
    *   Details tab - Upload Invoice section
    *   Agency Portal - Finances Module > Contractor Invoices
    *   Agency Portal - Payment processing system
    *   Contractor Portal - Dashboard payment widgets (if applicable)

**No Page Refresh Required:**

*   Updates reflect in real-time or near real-time
*   Contractor sees the current payment status without a manual refresh
*   Status badges update immediately upon agency action

### **4.8 Financial Calculations**

**Pending Amount Calculation:**

Pending Amount = Total Event Price - Payments Received

*   Always reflects the accurate outstanding balance
*   Updates dynamically with each payment received
*   Cannot be negative (if overpayment occurs, displays $0 for pending)

**Payments Received Calculation:**

Payments Received = Sum of all invoice amounts with "Received" status

*   Aggregates all completed payments
*   Independent of individual invoice amounts
*   Reflects actual payments processed by the agency

**Invoice Amount Independence:**

*   Individual invoice amounts are independent of the Total Event Price
*   Contractors can create multiple invoices of varying amounts
*   The total of all invoices can exceed the Total Event Price
*   The system does not enforce balance matching

## **5\. Field Details & Validations**

### **5.1 Payment Summary Card**

**Field Name**

**Validation Rules**

Total Event Price Label

Static label, always displayed

Total Event Price Value

Retrieved from agency assignment, read-only

Pending Amount Label

Static label, always displayed

Pending Amount Value

Calculated: Total - Received, minimum $0

Payments Received Label

Static label, always displayed

Payments Received Value

Sum of received payments, minimum $0

Create Invoice Button

Always enabled, opens pop-up on click

### **5.2 Invoice Table Headers**

**Field Name**

**Validation Rules**

Status Header

Sortable column

Payment Date Header

Due Date Header

Amount Header

Action Header

Non-sortable column

###

###

### **5.3 Invoice Table Row Data**

**Field Name**

**Display Format**

**Validation Rules**

Status Badge

"Issued" (orange) or "Received" (green)

Only two possible values

Payment Date

"Mon DD, YYYY | HH:MM AM/PM" or "--"

Date/time for Received, "--" for Issued

Due Date

"Mon DD, YYYY"

Date set by contractor during creation/upload

Amount

"$XXX.XX"

Numeric value, no negative amounts

Action Menu

Three-dot icon (⋮)

Opens dropdown with Preview and Download options

### **5.4 Action Menu Options**

**Field Name**

**Display Format**

**Validation Rules**

Preview

Text menu item

Opens invoice in viewer/modal

Download

Text menu item

Downloads PDF to the local system

## **6\. Error Message Handling**

**Field/Action**

**Validation Scenario**

**Error Message**

Payment Summary Load

Failed to retrieve contractor fee data

"Unable to load payment information. Please try again."

Payment Summary Load

Failed to calculate pending/received amounts

"Unable to calculate payment summary. Please refresh the page."

Create Invoice Button

Pop-up fails to open

"Unable to open invoice creation. Please try again."

Invoice Table Load

Failed to retrieve invoice history

"Unable to load invoice history. Please refresh the page."

Preview Action

The invoice document fails to load

"Unable to preview invoice. Please try again."

Download Action

Download fails

"Unable to download invoice. Please check your connection."

Table Sorting

Sort operation fails

"Unable to sort data. Please try again."

Real-Time Sync

Payment update sync fails

"Payment information may be outdated. Please refresh."

General System

Network connection lost

"Connection lost. Please check your internet connection."

## **7\. Edge Cases**

**Scenario**

**Expected Behavior**

Total Event Price is $0 (free service)

Display "$0" for Total Event Price; Pending Amount shows "$0"; Payments Received shows "$0"

The agency pays more than the Total Event Price (overpayment)

Pending Amount displays "$0"; Payments Received shows the actual total amount received

No invoices exist for the event

Table displays empty state: "No invoices created yet"; Create Invoice button remains functional

Contractor creates invoice exceeding Pending Amount

The invoice is created without validation; no restriction on invoice amounts

Multiple invoices created for the same event

All invoices displayed in a table, each with individual status tracking

The agency marks the invoice as paid while the contractor is viewing the page

Status updates to "Received"; Payment Date populates; summary card amounts update automatically

Invoice uploaded from the Details tab

Appears in the Finances table with "Issued" status; integrated seamlessly

Very long invoice history (50+ invoices)

Table implements pagination or infinite scroll; performance is maintained

Contractor fee changes after initial assignment

Total Event Price updates to reflect the new amount; recalculates the pending amount

The agency reverses/cancels a payment

Status reverts to "Issued"; Payment Date shows "--"; summary amounts recalculate

Due Date is in the past for "Issued" invoice

Displays due date as-is; no automatic overdue status (only "Issued" or "Received")

Currency format differences

All amounts display in consistent currency format (USD assumed)

Contractor creates invoice before event date

Invoice creation allowed; no date restrictions

Agency removes contractor from event

Display message "You no longer have access to this event" and redirect

## **8\. Test Cases**

*   Link

## **9\. Acceptance Criteria**

**Finances Tab Display:**

*   The Finances tab is accessible from tab navigation (Details, Contractors, Finances, Files)
*   Tab selection indicator highlights the Finances tab when selected
*   Section header "Payments" displays at the top of the tab content

**Payment Summary Card:**

*   Total Event Price displays the contractor fee for the assigned service and role
*   The Total Event Price amount is prominent with a large, bold font
*   Pending Amount displays calculated balance (Total - Received)
*   Payments Received displays the sum of all received payments
*   All amounts display in consistent currency format ($X, XXX.XX)
*   Summary card updates automatically when the agency processes payments

**Create Invoice Button:**

*   "Create Invoice" button displays prominently within the payment summary card
*   The button is always enabled regardless of the payment status
*   Clicking the button opens the invoice creation pop-up (functionality in the next phase)
*   Contractors can create multiple invoices without restriction
*   No validation prevents invoice amounts from exceeding the Total Event Price

**Invoice and Payment History Table:**

*   The table below displays the payment summary card
*   Table includes columns: Status, Payment Date, Due Date, Amount, Action
*   All columns (except Action) are sortable with sort arrows
*   The table displays both created invoices and uploaded invoices from the Details tab

**Status Column:**

*   Displays a color-coded badge for each invoice
*   "Issued" status displays in an orange/yellow badge (unpaid)
*   "Received" status displays in green badge (paid)

**Payment Date Column:**

*   For "Received" status: Displays date and time of payment (Mon DD, YYYY | HH:MM AM/PM)
*   For "Issued" status: Displays "--" (double dash) indicating no payment yet
*   Date/time recorded when the agency marks the invoice as paid

**Due Date Column:**

*   Displays invoice due date as set by contractor (Mon DD, YYYY)
*   Due date sourced from invoice creation or upload process
*   No automatic overdue status calculation

**Amount Column:**

*   Displays invoice amount in currency format ($XXX.XX)
*   Amount manually entered by the contractor during creation or upload
*   No validation against Total Event Price or Pending Amount

**Action Menu:**

*   Three-dot menu icon (⋮) displays for each invoice row
*   Clicking the icon opens a dropdown with options
*   "Preview" option opens the invoice document in the viewer
*   "Download" option downloads the invoice PDF to the local system

**Data Integration:**

*   Invoices uploaded from the Details tab appear automatically in the Finances table
*   Status updates reflect agency actions in real-time
*   Payment amounts sync with agency payment processing
*   No manual refresh required for updates

**Financial Calculations:**

*   Pending Amount = Total Event Price - Payments Received
*   Payments Received = Sum of all invoices with "Received" status
*   Calculations update automatically with each payment
*   Minimum values are $0 (no negative amounts displayed)

## **10\. Dependencies**

**Module/System**

**Dependency Type**

**Impact if Unavailable**

Event Service Configuration

Data Dependency

Cannot retrieve Total Event Price (contractor fee); summary card incomplete

Invoice Creation System

Feature Dependency

The Create Invoice button opens an empty pop-up; invoice creation fails

Invoice Upload System (Details Tab)

Data Dependency

Uploaded invoices are not integrated into the Finances table

Agency Payment Processing

Data Dependency

Invoice statuses remain "Issued"; Payment Date never populates; Payments Received stays $0

File Storage System

Data Dependency

Invoice preview and download fail; documents are inaccessible

Real-Time Sync Service

Feature Dependency

Payment updates delayed; manual refresh required

Database Connection

Critical Dependency

All financial data unavailable; page fails to load

Authentication System

Security Dependency

Cannot verify contractor identity; unauthorized access possible

## **11\. References**

*   **Figma Link -** [**Click Here**](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=12036-63810&t=0ByRl7J146jJn5dx-0)

☑️ Files/Documents Tab

# **Files/Documents Tab - Event Details Screen (Contractor Portal)**

## **1\. Module Overview**

*   **Module Name:** Files/Documents Tab (Event Details Screen - Contractor Portal)
*   **Purpose:** Provide contractors with centralized access to all event-related documents, including agency-uploaded documents (service agreements, questionnaires, surveys), contractor-uploaded invoices, and personal file uploads, with capabilities to view, download, and manage documents
*   **Business Goal:** Enable contractors to access all necessary event documentation in one location, track document status, upload supporting files for agency collaboration, and maintain organized document management for their event assignments

## **2\. User Roles & Permissions**

**Role**

**Description**

**Key Permissions**

Contractor

Contractors assigned to specific events by agencies

View all event-related documents (agency-uploaded and self-uploaded), upload new files, download documents, preview documents, remove self-uploaded files, and unpaid invoices

## **3\. User Flow**

**Navigation Path:** Contractor Portal > Event Details Screen > Files/Documents Tab

**Step-by-Step Flow:**

**Step 1:** Contractor accesses Event Details Screen from Event Listing, Dashboard, or Calendar Module

**Step 2:** Contractor clicks on the "Files/Documents" tab from the tab navigation

**Step 3:** System loads the Files/Documents tab with "Documents" section header and "+" upload button

**Step 4:** Two sub-tabs are displayed: "Documents & Forms" (default selected) and "Uploaded Files"

**Step 5:** The Documents & Forms tab displays a table with all agency documents and contractor invoices

**Step 6:** The Contractor can click the "+" button to upload new files, which appear in the Uploaded Files tab

**Step 7:** The Contractor can use the action menu to preview, download, or remove documents based on permissions

**Step 8:** The Contractor can switch between sub-tabs to view different document categories

## **4\. Functional Logic**

### **4.1 Empty State Logic:**

### If no agency documents and no contractor invoice or document exist for the event:

### Display empty state message: "No data found."

### **4.2 Section Header Elements**

**Documents Heading:**

*   Displays "Documents" as the main section title
*   "+" button allows contractors to upload new files
*   "Latest" dropdown sorts all documents by Created date in descending order (newest first) and an “Oldest” option that sorts documents by Created Date in ascending order (oldest first).

### **4.3 Sub-Tab Structure**

**Documents & Forms Tab (Default):**

*   Automatically selected when the Files/Documents tab loads
*   Displays all agency-uploaded documents and contractor-uploaded invoices

**Uploaded Files Tab:**

*   Displays files uploaded by the contractor & the agency via the manually "+" button

###

### **4.4 File Upload Functionality (+ Button)**

**Upload Pop-up:**

*   Clicking the "+" button opens a pop-up for file upload
*   Contractor can select files from their local system with the validations. **Refer** \- [**Click here**](#daqyvrtiw8i3)

**Post-Upload Impact:**

*   Successfully uploaded files appear in the "Uploaded Files" sub-tab in the Files/Documents Tab in the contractor portal
*   Files automatically sync to the **Agency Portal:**
    *   Event Details > Files/Documents Tab > Uploaded Files section
    *   Project Details > Activity Tab (logged as activity)

### **4.5 Documents & Forms Table Logic**

**Table Columns:**

*   **Name:** Document icon, document name, and event name (sub-text)
*   **Type:** Document category (Contract, Invoice, Survey, Questionnaire, Doc)
*   **Created:** Date (DD Mon YYYY) and time (HH:MM AM/PM) when the document was uploaded

**"New" Badge Logic:**

*   "New" badge displays next to document name
*   The badge appears for documents uploaded within the last 24 hours
*   Automatically disappears after a 24-hour period

**Document Sources:**

*   Agency-uploaded documents: Service agreements, questionnaires
*   Contractor-uploaded invoices: Invoices submitted, Any other documents uploaded using the + button

### **4.6 Uploaded Files Table Logic**

**Table Columns:**

*   **Name:** File icon and original file name
*   **Type:** File extension (PDF, Doc, XLS, XLSX)
*   **Created:** Date and time when the contractor uploaded the file

**"New" Badge Logic:**

*   Same as Documents & Forms - displays for files uploaded within the last 24 hours

### **4.7 Action Menu Logic**

**Available for All Documents/Files:**

*   **Preview:** Opens document in read-only mode
*   **Download:** Downloads file to contractor's local system

**Remove Option - Conditional Logic:**

*   **For Contractor-Uploaded Invoices:**
    *   Displayed only if invoice status is NOT "Paid" or "Received."
    *   Hidden once the agency marks the invoice as paid
    *   Allows the contractor to remove incorrectly uploaded invoices
*   **For Agency-Uploaded Documents:**
    *   NOT displayed - contractors cannot remove agency uploaded documents
*   **For Contractor-Uploaded Files (via + button):**
    *   Always displayed
    *   Contractor can remove their own uploaded files at any time
    *   Removal syncs to the Agency Portal (file removed from agency view as well)

**Remove Confirmation:**

*   Confirmation prompt displays before deletion: "Are you sure you want to remove this document?"

### **4.8 Sort Functionality (Latest Dropdown)**

**Default Behavior:**

*   Sorts documents by Created date in descending order (newest first)
*   Applies to currently selected sub-tab (Documents & Forms or Uploaded Files)
*   Sort preference is maintained while the user remains on the tab

##

##

## **5\. Field Details & Validations**

### **5.1 File Upload Validation**

**Field Name**

**Validation Rules**

Allowed File Types

PDF, DOC, DOCX, XLS, XLSX only

Maximum File Size

15 MB per file

File Name

Original file name preserved

### **5.2 Documents & Forms Table**

**Field Name**

**Display Format**

**Validation Rules**

Name

Document icon + Name + Event name (sub-text)

"New" badge if created within 24 hours

Type

Contract, Invoice, Survey, Questionnaire, Doc

Based on the document category

Created

DD Mon YYYY + HH:MM AM/PM

Date and time on separate lines

Action Menu

Three-dot icon (⋮)

Preview, Download, Remove (conditional)

### **5.3 Uploaded Files Table**

**Field Name**

**Display Format**

**Validation Rules**

Name

File icon + File name

"New" badge if uploaded within 24 hours

Type

PDF, Doc, XLS

File extension/type

Created

DD Mon YYYY + HH:MM AM/PM

Date and time on separate lines

Action Kebab Menu

Kebab menu

Preview, Download, Remove

## **6\. Error Message Handling**

**Field/Action**

**Validation Scenario**

**Error Message**

File Upload

File size exceeds 15 MB

"File size cannot exceed 15 MB limit."

File Upload

File format not supported

"Only PDF, DOC, XLS, and XLSX files are allowed."

File Upload

Upload fails due to a network error

"Unable to upload file. Please check your connection and try again."

Document Load

Failed to retrieve document list

"Unable to load documents. Please refresh the page."

Preview Action

Document preview fails to load

"Unable to preview document. Please try again."

Download Action

Download fails

"Something went wrong."

Remove Action

The remove operation fails

"Unable to remove document. Please try again."

General System

Network connection lost

"Something went wrong."

## **7\. Edge Cases**

**Scenario**

**Expected Behavior**

No documents exist in Documents & Forms

Display empty state: "No documents available for this event."

No files exist in Uploaded Files

Display empty state: "No files uploaded yet. Click + to upload files."

The agency removes the document while the contractor is viewing

Document disappears from the list on the next refresh

Contractor uploads a file with the same name as the existing file

Both files were displayed, differentiated by the Created timestamp

The contractor tries to remove the paid invoice

"Remove" option not displayed in action menu

The agency adds a document while the contractor is on the tab

Document appears on the next page, refresh or real-time sync

File upload interrupted mid-way

Error message displayed; file not added to the list

Very long file name

File name truncated with ellipsis; full name shown on hover/preview

Multiple files are uploaded simultaneously

All files processed with individual timestamps

Contractor removes file

File removed from the contractor and agency portal views

Agency updates/replaces document

New version appears with updated Created timestamp and "New" badge

## **8\. Test Cases**

*   **Link -**

## **9\. Acceptance Criteria**

*   The Files/Documents tab is accessible from the main tab navigation
*   Two sub-tabs display: "Documents & Forms" (default) and "Uploaded Files."
*   "+" button opens file upload pop-up accepting PDF, DOC, DOCX, XLS, XLSX files up to 15 MB
*   Uploaded files appear in the "Uploaded Files" sub-tab and sync to the Agency Portal
*   The Documents & Forms table displays agency documents (service agreements, questionnaires, surveys) and contractor invoices
*   Table columns include: Name (with icon and "New" badge for <24 hours), Type, Created (date and time)
*   "New" badge automatically disappears after a 24-hour period
*   The action menu provides Preview and Download options for all documents
*   Remove the option available for contractor-uploaded files and unpaid invoices only
*   Agency-uploaded documents cannot be removed by the contractor
*   Paid invoices cannot be removed by the contractor
*   "Latest" dropdown sorts documents by Created date (newest first)
*   File uploads sync to Agency Portal: Event Details Files/Documents, Project Activity Tab, Project Files/Documents

## **10\. Dependencies**

**Module/System**

**Dependency Type**

**Impact if Unavailable**

Document Storage System

Critical Dependency

Cannot load, upload, preview, or download documents

Agency Document Management

Data Dependency

Agency-uploaded documents are not visible

Invoice Upload System (Details Tab)

Data Dependency

Invoices not appearing in the Documents & Forms table

File Upload Service

Feature Dependency

"+" button upload functionality fails

Real-Time Sync Service

Feature Dependency

Uploads are not reflecting in the Agency Portal

Preview/Viewer Service

Feature Dependency

Document preview fails

Authentication System

Security Dependency

Cannot verify contractor permissions

## **11\. References**

*   **Figma Link** \- [**Click Here**](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=9089-177575&t=0ByRl7J146jJn5dx-0)

☑️ Notes Tab

# **Notes Tab - Event Details Screen (Contractor Portal)**

## **1\. Module Overview**

**Module Name:** Notes Tab (Event Details Screen - Contractor Portal)

**Purpose:** Enable contractors to view, create, and manage public and private notes associated with their assigned events

**Business Goal:** Provide contractors with a centralized note-taking system for event-related documentation while maintaining visibility controls between contractor private notes and public notes shared with the agency

**Reference Document:** For complete Notes Module functionality, refer to [**Click Here**](https://docs.google.com/document/d/1JRbhA6wMQ6BtUWKlw63paM1s_sgaDy6PrjQHLw1suLk/edit?tab=t.xrj9jtmpldgv#bookmark=id.uolu37ze2m36)

## **2\. User Roles & Permissions**

**Role**

**Description**

**Key Permissions**

Contractor

Contractors assigned to specific events by agencies

View public notes shared by agency, create public notes (visible to agency only), create private notes (visible to self only), edit and delete self-created notes

## **3\. User Flow**

**Navigation Path:** Contractor Portal > Event Details Screen > Notes Tab

**Step-by-Step Flow:**

**Step 1:** Contractor accesses Event Details Screen from Event Listing, Dashboard, or Calendar Module

**Step 2:** Contractor clicks on the "Notes" tab from the tab navigation

**Step 3:** System loads Notes tab displaying Private Notes and Public Notes sections

**Step 4:** If no notes exist in a section, empty state message is displayed for that section

**Step 5:** Contractor can create new notes using "Private +" or "Public +" buttons

**Step 6:** Contractor can view, edit, or delete their own notes via kebab menu or note view pop-up

## **4\. Functional Logic**

### **4.1 Notes Section Display**

*   Notes tab displays two separate sections: Private Notes and Public Notes
*   Each section displays notes specific to its visibility type
*   Sections are independent - empty state displays individually per section

**Empty State Logic:**

*   If no private notes exist, the Private Notes section displays an empty state: "No private notes yet."
*   If no public notes exist, the Public Notes section displays an empty state: "No public notes yet."
*   Both sections can show an empty state simultaneously if no notes exist in either category
*   "Create Note" button available in the empty state to add the first note

**Note Card Display:**

*   Each note card shows: Event title, Kebab menu (for self-created notes), Headline (truncated), Content preview (truncated), User avatars, Creation timestamp
*   Ordering: Newest first; recently edited notes move to top
*   Pagination: Initial 4 notes displayed, then "Show More (+X notes)" in groups of 10

### **4.2 Create Note - Contractor Specific Logic**

**Event Field Behavior:**

*   The event is always fixed (pre-selected and read-only) based on the currently selected event in the Event Details Screen
*   The contractor cannot change the event assignment when creating notes from Event Details

**Visibility Options:**

*   **Private Note:** Visible only to the contractor (creator)
*   **Public Note:** Automatically visible to the agency only (no audience selection required)

**Public Note - No Audience Checkboxes:**

*   Unlike agency users, contractors do not see the Clients, Contractors, or Team Members checkboxes
*   Public notes created by contractors are automatically shared with the agency
*   No additional audience selection required or available

**Required Fields:**

*   Event: Pre-selected, read-only
*   Visibility: Private Note or Public Note (must select one)
*   Headline: Required, no character limit
*   Note Content: Optional, supports rich text formatting and image upload

### **4.3 Edit Note - Contractor Specific Logic**

**Editable Fields:**

*   Headline: Can modify note title
*   Content: Can modify note text and media
*   Visibility: Can switch between Private and Public

**Non-Editable Fields:**

*   Event: Always fixed, cannot be changed

**Visibility Change Behavior:**

*   **Private to Public:** Note becomes visible to the agency automatically (no audience selection)
*   **Public to Private:** Note is hidden from the agency and moved to the contractor's Private Notes section

### **4.4 Delete Note**

**Access Control:**

*   Only the note creator can delete their own notes
*   Delete option available via the kebab menu or the note view pop-up

**Delete Results:**

*   **Private Note:** Removed only for the contractor (creator)
*   **Public Note:** Removed from contractor's view and agency's view
*   Confirmation dialog required before permanent removal

### **4.5 View Note**

**Note Pop-up Display:**

*   Note Title (headline)
*   Public/Private indicator
*   Event name with color badge
*   Visible To:
    *   Private Notes: Shows creator avatar ("You")
    *   Public Notes: Shows agency visibility
*   Created On: Date and time
*   Created By: User avatar and name
*   Edited On: Last modification date (if edited)
*   Full note content with rich text formatting

**Action Buttons:**

*   Edit: Opens edit note pop-up (self-created notes only)
*   Delete: Opens delete confirmation (self-created notes only)

## **5\. Error Message Handling**

**Field/Action**

**Validation Scenario**

**Error Message**

Choose Visibility

Not selected

"Please select the visibility option."

Headline

Empty submission

"Please enter a headline."

Image Upload

File exceeds 15 MB

"File size cannot exceed 15 MB limit."

Image Upload

Invalid format

"Only valid image formats (.jpg, .jpeg, .png, .webp, .svg) are allowed."

General

Save/Update/Delete error

"Something went wrong."

## **6\. Success Message Handling**

**Action**

**Success Message**

Note created

"Note has been created successfully."

Note updated

"Note has been updated successfully."

Note deleted

"Note has been deleted successfully."

## **7\. Edge Cases**

**Scenario**

**Expected Behavior**

No private notes and no public notes exist

Both sections display individual empty states

Agency deletes public note while contractor viewing

Note disappears on page refresh or API call

Contractor changes note from Private to Public

Note moves from Private section to Public section; becomes visible to agency

Contractor changes note from Public to Private

Note moves from Public section to Private section; hidden from agency

Search returns no results

Display "No notes found" message

## **8\. Acceptance Criteria**

*   Notes tab displays Private Notes and Public Notes sections separately
*   Empty state displays individually per section if no notes exist in that category
*   Contractor can create private notes (visible to self only) and public notes (visible to agency)
*   Event field is always pre-selected and read-only (fixed to current event)
*   Public notes do not require audience selection - automatically shared with agency
*   Only note creators can edit or delete their own notes
*   Visibility changes between Private and Public update note placement accordingly
*   Success toasts display after create, update, or delete actions
*   Note cards show event title, headline, content preview, user avatars, and timestamp
*   Notes ordered by newest first; edited notes move to top

##

##

## **9\. Dependencies**

**Module/System**

**Dependency Type**

**Impact if Unavailable**

Notes Management System

Critical Dependency

Cannot create, view, edit, or delete notes

Rich Text Editor Component

UI Dependency

Cannot format note content

CRM Library Module

Integration Dependency

Cannot select or upload images

Authentication System

Security Dependency

Cannot determine user permissions

## **10\. References**

*   **Figma Link:** [**Click Here**](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=9089-180006&t=qI39dRBohSA1mlSj-0)

☑️ Payments module

# **Payments Module - Contractor Portal**

## **1\. Module Overview**

*   **Module Name:** Payments Module (Contractor Portal)
*   **Purpose:** Provide contractors with a centralized, global view of all their payment-related information across all agencies they work with, including invoice management, payment status tracking, and payment history
*   **Business Goal:** Enable contractors to efficiently track their earnings, manage invoices across multiple agency relationships, monitor payment statuses, and maintain clear financial records for all their event assignments

## **2\. User Roles & Permissions**

**Role**

**Description**

**Key Permissions**

Contractor

Contractors assigned to events across multiple agencies

View all payments from all agencies in one table, upload invoices, view uploaded invoices, track payment status (Upcoming, Pending, Paid, Void)

## **3\. User Flow**

**Navigation Path:** Contractor Portal > Left Sidebar > Payments

**Step-by-Step Flow:**

**Step 1:** Contractor clicks on "Payments" from the left sidebar navigation menu

**Step 2:** System loads the Payments module, displaying all payments across all agencies in a table format

**Step 3:** The Contractor can view payment status, project details, due dates, amounts paid, and payment methods for each invoice

**Step 4:** The Contractor can click the "Upload Invoice" button to create and upload new invoices

**Step 5:** The Contractor can click the "View Invoice" action to preview the uploaded invoice PDF

**Step 6:** The Contractor can sort columns to organize payment data as needed

**Step 7:** For invoices with "Unpaid" or "Overdue" status, the Contractor can click the "Void" button in the Actions column to open the Mark as Void confirmation pop-up.

**Step 8:** The Contractor enters a Void Reason, optionally clicks "View Invoice" in the pop-up to review the invoice, and confirms by clicking "Mark as Void."

## **4\. Functional Logic**

### **4.1 Empty State (No Payments)**

*   If the contractor has no invoices/payments, display an empty state message
*   Message: "No payments found."
*   "Upload Invoice" button remains available only if at least one event is assigned to the contractor

### **4.2 Payments Module Overview**

**Global Payment View:**

*   The Payments module displays all payment information across ALL agencies the contractor works with
*   Not workspace-dependent - contractor sees consolidated view regardless of currently selected workspace
*   The **“Upload Invoice”** button allows the contractor to upload new invoices. It will only fetch projects from the selected agency workspace. The contractor needs to switch their workspace to upload invoices for another agency.

### **4.3 Payments Table Structure**

**Payment Status:** This column displays the current payment status for the events with which the contractor is associated, and the System automatically calculates the status based on the event date and the agency payment action

*   **Status Values and Display Logic:**
    *   **“Paid” status:** It will display when the Agency has marked the invoice as paid
    *   **“Pending” status:** It will display when the event date has passed, AND payment has not yet been made by the agency
    *   **“Upcoming” status:** It will display when the event date is in the future, AND payment has not yet been made
    *   **"Void" status:** Displays when the contractor has marked the invoice as void. A voided invoice is no longer active and cannot be paid or reactivated.

**Project Name:** It will display the Project name associated with the event (e.g., "Jadon & Monika Wedding") in which the contractor is assigned

**Due Date:** It will display the Due date entered by the contractor during invoice upload

**Amount:** It will display the actual amount of the invoice for the event

**Payment Method:** Payment method selected/entered by agency when processing payment (e.g., "Bank Transfer" )

**Actions:** Display: "View Invoice" text button/link on click, opens the uploaded invoice PDF in a preview pop-up modal

Also display a "Void" button for invoices with "Unpaid" or "Overdue" status, which opens the Mark as Void confirmation pop-up.

**4.4 View Invoice**

*   Clicking "View Invoice" opens a modal with a PDF preview
*   Displays the invoice PDF uploaded by the contractor
*   Read-only view of the invoice document
*   Close button to return to the Payments table

### **4.5 – Mark as Void Functionality**

**Void Button Visibility:** Shown only for "Unpaid" or "Overdue" invoices. Hidden for "Paid" and already "Void" invoices.

**Mark as Void Pop-up Modal contains:**

*   **Title:** "Mark as Void"
*   **Confirmation message:** "You are about to mark this invoice as void. Do you want to continue?"
*   **Invoice summary:** Project Name + Issued Date
*   **"View Invoice" link:** Opens the PDF preview modal inline — contractor can review before confirming
*   **Amount Invoiced:** Displays the invoice amount (e.g. $1,500.00)
*   **Void Reason (Required):** Text area with placeholder "Add void note here" — must be filled before confirming
*   **Cancel button:** Closes pop-up, no changes made
*   **"Mark as Void" button:** Confirms action — invoice status updates to "Void," Void button removed from that row, success message shown

### **4.6 Upload Invoice Functionality**

*   In the contractor portal, the contractor can upload invoices from multiple locations within the portal.
*   **Payments module > Upload Invoice**
    *   When the contractor uploads an invoice from the Payments module, the “Choose Project” dropdown in the Upload Invoice pop-up will display only the projects in the current workspace where the contractor is logged in. If the contractor wants to upload an invoice for another agency workspace, they must switch workspaces from their contractor profile.
*   **Event details > finances > create invoices**
*   **Event details > details tab > Upload Invoice**
*   **Field details:** [**Click Here**](#adc8wmx7p9vm)

### **4.7 Upload Invoice - Cross-Module Impact**

**Contractor Portal Updates:** When the contractor uploads an invoice, it will have an impact on the following modules

*   **Payments Module:** A New invoice row has been added to the table with "Upcoming" or "Pending" status
*   **Event Details > Files/Documents Tab:** Invoice appears in Documents & Forms section
*   **Event Details > Finances Tab:** Invoice appears in the invoice table with "Issued" status
*   **Event Details > Details Tab > Services Section:** Invoice status icon updates

### **4.8 Warning Message Content**

*   **The system does NOT restrict invoice uploads that exceed the contractor fee**
*   **When contractor tries to upload an invoice where the amount exceeds the contracted fee for the event, a warning modal is displayed**
*   **Warning is displayed as an informational alert only, allowing the contractor to proceed with submission**

**Warning Modal:**

**⚠ Invoice Amount Exceeds Contracted Fee**

**The amount you entered (\[invoiceAmount\]) exceeds the contracted fee for this event (\[invoiceAmount\]) exceeds the contracted fee for this event ( \[invoiceAmount\])exceedsthecontractedfeeforthisevent(\[contractorFee\]). The discrepancy of $\[discrepancyAmount\] will be flagged for review by the agency.**

**Actions:**

*   **Cancel – Returns the contractor to the upload form to modify the invoice details**
*   **Submit Anyway – Proceeds with the invoice submission despite the discrepancy; the invoice will be flagged for agency review**

**Agency Portal Updates:**

**Note:** If the contractor uploads an invoice with a due amount greater than the total Event price (contractor fee) for the case, a message will appear in the agency portal stating that the contractor has uploaded an invoice with an amount exceeding the contractor fee for that particular event.

**⚠ Invoice Amount Exceeds Contractor Fee**

**Contractor has submitted an invoice for $\[invoiceAmount\], which exceeds the contracted event fee of $\[contractorFee\] by $\[discrepancyAmount\].**

**_Please review the invoice details and discrepancy before processing payment._**

*   **Finances > Contractor Invoices:** Invoice appears in the unpaid/pending section
*   **Project Details > Activity Tab:** Invoice upload activity logged
*   **Project Details > Files/Documents Tab:** Invoice appears in documents list
*   **Project Details > Finances Tab:** Invoice appears for processing

## **5\. Field Details & Validations**

### **5.1 Upload Invoice Form Fields**

**Field Name**

**Field Type**

**Required**

**Validation Rules**

Choose Project

Dropdown

Yes

Must select from available projects where the contractor is assigned. It will only fetch projects from the selected agency workspace.

Choose Event

Dropdown

Yes

Must select from events in the chosen project where the contractor is assigned; Dependent on the Choose Project selection

Amount Due

Number Input

Yes

Maximum 7 digits; Only positive numbers (0-9); No negative values; Whole numbers only

Due Date

Date Picker

Yes

Cannot be before the current date; Format: MM-DD-YYYY

Upload Invoice

File Upload

Yes

PDF format only (\*.pdf); Maximum file size: 15 MB

Cancel

Button

NA

Closes the pop-up without any actions

Confirm

Button

NA

All required fields must be completed

On Success:

*   *   Invoice uploaded and saved
    *   Pop-up closes
    *   A new invoice row appears in the Payments table

### **5.2 Payments Table Display Fields**

**Field Name**

**Display Format**

**Data Source**

**Display Logic**

Payment Status

Badge with color coding

Calculated from the event date and the agency payment status

**Paid** (green): Agency marked as paid

**Pending** (orange): Event passed, unpaid

**Upcoming** (gray): Future event, unpaid

Void(Grey): To make payment Void.

Refer - [Click Here](#s7hd8gcp1t75)

\- Column Not sortable

Project Name

Text

Event's associated project

Displays project name; Long names truncated with ellipsis

\- Sortable Column

Due Date

MM/DD/YY HH:MM AM/PM

Contractor input during upload

Display the invoice due date. The date format will be dynamic and based on the user’s global settings.

\- Sortable Column

Amount Paid

Currency format

Agency payment record

Shows the actual amount for the invoice

\- Sortable Column

Payment Method

Text

Agency selection during payment

Examples: "Bank Transfer"

\- Sortable Column

Actions

Link/Button

System generated

"View Invoice" opens PDF preview modal

Void

Button

Opens Void pop-up

visible for Unpaid/Overdue invoices only

## **6\. Error Message Handling**

**Field/Action**

**Validation Scenario**

**Error Message**

Choose Project

Not selected

"Please select a project."

Choose Event

Not selected

"Please select an event."

Amount Due

Empty

"Please enter the amount due."

Amount Due

Exceeds 7 digits

"Amount cannot exceed 7 digits."

Amount Due

Exceeds the total contractor fee amount

“The entered amount is greater than the total contractor fee for the event.”

Due Date

Not selected

"Please select a due date."

Due Date

Date before the current date

"Due date cannot be in the past."

Upload Invoice

No file selected

"Please upload an invoice."

Upload Invoice

File format not PDF

"Only PDF files are allowed."

Upload Invoice

File exceeds 15 MB

"File size cannot exceed 15 MB."

General

Upload/save operation fails

"Something went wrong."

Void Reason

Left empty when submitting void

“Please enter a void reason.”

## **7\. Success Message Handling**

**Action**

**Success Message**

Invoice uploaded successfully

"Invoice has been uploaded successfully."

Invoice marked as void

"Invoice has been marked as void successfully."

## **8\. Edge Cases**

**Scenario**

**Expected Behavior**

Contractor works with no agencies

Empty state displayed: "No payments found."

Contractor assigned to multiple events in the same project

All assigned events appear in the Choose Event dropdown

Event date passes while invoice is Upcoming

Status automatically changes to "Pending"

The agency pays a partial amount

Amount Paid shows partial amount; status may remain Pending until fully paid

The agency deletes the project while the invoice exists

The invoice may show the project name as unavailable or be removed

Contractor uploads multiple invoices for the same event

All invoices are displayed as separate rows in the table

Very long project name

Text truncated with ellipsis (...)

The agency hasn't selected a payment method yet

The Payment Method column shows "—" or blank

The due date is today

The invoice shows "Upcoming" status (the current date is not past)

Contractor is in the process of uploading invoice

Empty Icon; remains empty until upload completes

Agency initiates payment but fails

Icon remains empty until payment is confirmed

Contractor uploads invoice for past event

Status shows "Pending" since the event date has passed

Contractor submits void without entering a reason

Validation error shown; void not processed

Invoice already marked as Void

"Void" button not shown in Actions column

## **9\. Acceptance Criteria**

*   The Payments module is accessible from the left sidebar navigation
*   Table displays all payments from all agencies (global view, not workspace-specific)
*   Table columns: Payment Status, Project Name, Due Date, Amount Paid, Payment Method, Actions
*   Payment Status shows color-coded badges: Paid (green), Pending (orange), Upcoming (gray)
*   Status logic: Paid = agency marked paid; Pending = event passed, unpaid; Upcoming = event future, unpaid
*   Amount Paid shows the actual payment amount for Paid invoices
*   All columns (except Actions) are sortable
*   "View Invoice" action opens PDF preview in pop-up modal
*   "Upload Invoice" button opens the upload pop-up
*   The Choose Project dropdown shows only projects where the contractor is assigned
*   The Choose Event dropdown shows only events within the selected project where the contractor is assigned
*   Amount Due field accepts a maximum of 7 digits, positive numbers only
*   Due Date cannot be before the current date
*   Only PDF files allowed, maximum 15 MB
*   A successful upload creates an invoice across all relevant modules (Contractor Portal and Agency Portal)
*   Invoice appears in: Payments table, Event Details Files/Documents, Event Details Finances, and corresponding Agency Portal modules
*   "Void" button appears in Actions column only for Unpaid/Overdue invoices
*   Clicking "Void" opens Mark as Void pop-up with project name, issued date, amount invoiced, View Invoice link, and Void Reason field
*   "View Invoice" link inside the pop-up opens the invoice PDF preview
*   Void Reason is a required field; submission blocked if empty
*   On confirmation, invoice status updates to "Void" and the Void button is removed for that row
*   "Void" status is displayed as a color-coded badge in the Payment Status column

## **10\. Dependencies**

**Module/System**

**Dependency Type**

**Impact if Unavailable**

Project/Event Management

Data Dependency

Cannot populate the Choose Project and Choose Event dropdowns

File Storage System

Critical Dependency

Cannot upload or view invoice PDFs

Agency Payment System

Data Dependency

Cannot retrieve payment status, amount paid, or payment method

Cross-Module Sync Service

Integration Dependency

Uploaded invoices are not reflected in other modules

Authentication System

Security Dependency

Cannot verify contractor identity across agencies

Calendar/Date Service

Feature Dependency

The due date picker is non-functional

## **11\. References**

*   Link **\-** [**Click Here**](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=13461-170343&t=Domgr1X3sDK9PNue-0)

✅ W-9 Forms

# **Functional Requirements Document (FRD) - Tax Forms Module**

## **1\. Module Overview**

*   **Module Name:** Tax Forms Management
*   **Purpose:** Enable contractors to upload, manage, and maintain tax documentation based on their location (US W-9 forms or international tax forms)
*   **Business Goal:** Ensure tax compliance for contractors while providing location-specific tax form management with automated annual reminders

## **2\. User Roles & Permissions**

**Role**

**Description**

**Key Permissions**

US Contractor

Contractor based in the United States

Upload/view/delete W-9 forms, download W-9 template

Non-US Contractor

Contractor based outside the United States

Upload/view/delete tax forms, change the default location

Agency Team Member

An Agency Team Member can download the W-9 of the individual contractor form from the Contractor’s Profile

Download from the Download Button in the Contractor Profile

## **3\. User Flow**

### **Critical Path (US Contractor):**

1.  Contractor navigates to "Taxes" from the main navigation menu
2.  System displays "Upload W-9 Form (Only for US)" section with upload area and W-9 template
3.  Contractor downloads W-9 template, fills it out
4.  Contractor uploads completed W-9 form via the upload section
5.  The system stores the document
6.  Contractor can view, download, or delete the uploaded form via the kebab menu

###

### **Critical Path (Non-US Contractor):**

1.  Contractor navigates to "Taxes" from the main navigation menu
2.  System displays "Upload Tax Form (Only for Non-U.S. Citizens)" section
3.  The location of the contractor will be selected by default in the “Select your country” field. The contractor can further change the location if they want
4.  Contractor uploads tax documentation
5.  System validates and stores the document
6.  Contractor can view, download, or delete the uploaded form via the kebab menu

**Agency Team Member:  
  
**An Agency Team Member can download the W-9 of the individual contractor form from the Contractor’s Profile

## **4\. Functional Logic**

*   **Location-based visibility:** System determines contractor location and shows appropriate sections (W-9 for US, international form for non-US). The location of all Contractors will be fetched by default; the contractor can further change it from the value in the drop-down as they want
*   **Template access:** The W-9 template is only visible and downloadable for US-based contractors
*   **Document management:** Uploaded documents can be viewed, downloaded, and deleted through the kebab menu actions
*   **Annual reminder system:** Automated email sent every January 1st to all contractors requesting tax form updates
*   **Agency downloading the W-9 form:** The agency team member can download the W-9 form from the Profile detail of the contractors
*   **File validation:** System validates file type, size, and format before accepting uploads
*   **Version control:** New uploads replace previous versions with timestamp tracking
*   **Reminder:** In case of any new onboarded contractor, do not upload any W-9 form for them; they will receive an email to add a W-9 form.

##

## **5\. Field Details & Validations**

**Field Name**

**Type**

**Required**

**Validation Rules**

Country Selection

Dropdown

Yes (Non-US only)

The country will be by default fathed from the contractors’ location  
  
The Contractor can further change the country location if needed

Tax Document Upload

File Upload

Yes

PDF format only; Max size 15MB

Download Template Form

CTA

Conditional

This is only for the US Users.

## **6\. Success Message Handling**

**Validation Scenario**

**Success Message**

W-9 form uploaded successfully

"Tax form has been uploaded successfully."

Tax form uploaded successfully

"Tax form has been uploaded successfully."

Document deleted successfully

"Tax document has been deleted successfully."

Document Downloaded by Agency Team Member

“Tax Document has been downloaded successfully.”

## **7\. Error Message Handling**

**Field**

**Validation Scenario**

**Error Message**

File Upload

No file selected

"Please select a file to upload."

File Upload

Invalid file format

"Please upload a valid file format."

File Upload

File size exceeds limit

"File size cannot exceed 15MB"

Country Selection

No country selected

"Please select your country."

General

Upload failure

"Failed to upload document. Please try again."

General

Network error

"Unable to connect. Please check your internet connection."

## **8\. Edge Cases**

**Scenario**

**Expected Behavior**

Contractor location changes from the US to a non-US location

Hide W-9 section, show international form section, retain existing documents

Multiple file uploads attempted

Only accept the latest upload, replace the previous version

Template download fails

Show error message, provide alternative download link

Upload during system maintenance

Queue upload for processing, notify user of delay

## **9\. Test Cases :**

## **10\. Acceptance Criteria**

*   **Location detection:** System correctly identifies contractor location and displays appropriate tax form sections
*   **Template functionality:** US contractors can download the W-9 template successfully
*   **Upload capability:** Contractors can upload tax documents in supported formats of PDF up to 15MB
*   **Document management:** Contractors can view, download, and delete their uploaded tax documents
*   **Annual reminders:** The System automatically sends tax form update reminders every January 1st
*   **Error handling:** Appropriate error messages displayed for all validation scenarios
*   **Navigation integration:** The Taxes module is accessible from the main navigation menu in the contractor portal

##

## **11\. Dependencies**

**Module/System**

**Dependency Type**

**Impact if Unavailable**

User Authentication

Authentication dependency

Cannot identify contractor location and permissions

Email Service

Service dependency

Annual reminder emails cannot be sent

File Storage System

Storage dependency

Cannot store or retrieve uploaded documents

## **12\. References**

*   **Figma Link:** [**Figma Design Link**](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=7948-185686&t=1uwMCREmu6HRopYA-0)

✅ Tasks Module

# **Tasks Module - Contractor Portal**

## **1\. Module Overview**

*   **Module Name:** Tasks Module (Contractor Portal)
*   **Purpose:** Enable contractors to view, create, and manage tasks assigned by agencies as well as self-created personal tasks, with the ability to track task progress through different statuses (To-Do, In-Progress, Completed)
*   **Business Goal:** Provide contractors with a centralized task management system to organize their work, track assignments from multiple agencies, and maintain productivity through clear visibility of pending and completed tasks

## **2\. User Roles & Permissions**

**Role**

**Description**

**Key Permissions**

Contractor

Contractors working with multiple agencies

View all tasks (agency-assigned and self-created), create new tasks for self, edit all task fields, change task status, delete self-created tasks only, search and filter tasks

## **3\. User Flow**

Flow Chart- [Click Here](https://drive.google.com/file/d/1eb5m39IUNoFdqwv3uzusxRJgkS_CfJWr/view?usp=drive_link)

## **4\. Functional Logic**

### **4.1 Global Task Module Behavior**

*   The Task module operates as a **global workspace**, showing tasks across all agencies the contractor is associated with.
*   It displays **all tasks assigned by any agency**, grouped under their respective status tabs (e.g., _To-Do_, _In-Progress_, _Completed_), regardless of the currently selected workspace.

*   For **agency-assigned tasks**, the contractor can modify the task (including updating the task status) **only when the task belongs to the currently selected agency workspace**.
*   If the contractor attempts to edit a task that was assigned by a **different agency** than the one currently selected in the workspace, the system displays a **Wrong Brand** pop-up.
*   The pop-up instructs the contractor to **switch to the correct agency workspace** in order to edit that task.
*   Until the contractor switches the workspace, the task remains **read-only** in the current agency view.
*   The module also includes **self-created tasks**, allowing contractors to manage both agency-assigned and personal tasks from a single interface.

### **4.2 Initial Empty State - No Tasks**

### When the contractor **has no assigned tasks from any agency** and has **not created any personal tasks**, the system displays a global empty state message: **“No tasks yet!”** along with a CTA to create a new task.

### If tasks exist in the system but the **selected status contains zero tasks**, the module displays a contextual empty state message specific to that tab.

### Example: If the contractor has tasks in _To-Do_ or _Completed_ but none in _In-Progress_, the system displays **“No tasks in In-Progress.”**

### This behavior applies consistently across all status tabs

*   Whenever any status tab (_To-Do_, _In-Progress_, _Completed_) has zero tasks, the system shows the respective empty state message for that status.

### **4.3 Task Management Listing**

*   The **Task Management module** includes two primary tabs for task listing: **To Do** and **Completed**.
*   "To-Do" tab is selected by default.

### **4.3.1 To-Do Tab**

*   Displays all tasks with statuses **“To Do”** and **“In Progress.”**
*   Both the **To Do** and **In Progress** sections include an **expand/collapse** option accessible through their respective section headers.
*   **To Do:** Represents active tasks that are yet to be started or completed.
*   **In Progress:** Represents tasks that have been started but are not yet marked as completed.
*   The list view displays **“Due Today”** and **“Overdue”** tags against tasks that meet the respective criteria.
*   **Due Today Tag:**
    *   Tasks with a due date matching the current date (today’s date) are displayed with a **“Due Today”** tag.
    *   The tag disappears once the task is marked as **completed**.
    *   If the task remains incomplete after the due date, it automatically changes to an **“Overdue”** tag on the next day.
*   **Overdue Tag:**
    *   A task becomes **Overdue** when its due date has passed, and it is still not completed.
    *   The **Overdue** tag appears from the day after the assigned due date.
    *   When a task first becomes overdue, an **email reminder** is sent to both the task reporter and the contractor.
    *   If the **same user** is both the reporter and the assignee, only **one email notification** is sent.
    *   The tag disappears as soon as the task is marked as **completed**.
*   **Table Columns (To-Do and In-Progress): Refer -** [**Click Here**](#u5yxtqa5wt7t)

### **4.3.2 Completed Tab**

*   Displays tasks whose status has been updated to **“Completed.”**
*   Once a task is marked as completed, it automatically moves out of the **To Do** or **In Progress** sections and appears under the **Completed** tab.
*   **Table Columns (Completed): Refer -** [**Click Here**](#n6dbjqcuwixw)

**4.4 Create New Task**

*   The contractors can manually create a new task from the **Task Management** module by clicking the **“New Task”** button.
*   On click, a **Create Task drawer** opens from the right side, displaying the fields for task creation. Please refer- [**Click Here**](#pzrf038t1lm7)
*   Tasks created from the Contractor Portal are **standalone personal tasks**. Contractors **cannot link these tasks** to any agency’s brand, project, or event.
*   Task assignment is restricted in the Contractor Portal. Contractors **cannot assign tasks to other users**.
*   For all manually created tasks:
    *   The **contractor becomes the default and only assignee**.
    *   The **contractor is also the reporter**.

### **4.5 Edit Task**

*   Contractors can edit an existing task by clicking **“Edit”** from the **Actions kebab menu** in the task table.
*   Selecting Edit opens the **Task Edit drawer**, which is the same interface used during task creation, but with **pre-filled values**.
*   For **agency-assigned tasks**, the contractor can modify the task (including updating the task status) **only when the task belongs to the currently selected agency workspace**.
*   All fields in the panel are automatically populated with the current task data.
*   The **Task Title** is editable inline.
*   The following fields remain **editable** for all tasks, including those assigned by agencies:
    *   Task Title
    *   Status
    *   Priority
    *   Due Date
    *   Description
*   The **Reporter** field remains **read-only** and always reflects the original creator of the task.
*   The **Assignee** field also remains **read-only**, as contractors cannot reassign tasks to others.

**Save Changes**

*   When the contractor clicks **“Save”**, the task is saved with the modified values.
*   The drawer panel closes automatically after a successful update.
*   If the task’s status is changed, the task automatically moves to the corresponding status section (e.g., from To-Do to In-Progress or Completed).
*   For **agency-assigned tasks**, all updates are **synced to the Agency Portal**.

### **4.6 Delete Task**

*   The contractor can **only delete self-created tasks**.
*   The contractor **cannot delete tasks assigned by any agency**. For agency-assigned tasks, the Delete option is **hidden**.
*   Only the **respective agency** has permission to delete tasks they have assigned to the contractor.
*   When a contractor tries to delete a task they created, selecting Delete triggers a confirmation message: “Are you sure you want to delete this task?”
    *   Upon confirmation, the task is permanently removed from the Tasks module and the Contractor Dashboard → Task Management section.

### **4.7 Status Change Logic**

*   The contractor can change the task status at different places within the system:
    *   The contractor can update a task’s status **directly from the status dropdown** in the table row.
    *   The contractor can update a task’s status by **opening the task in the Edit drawer**, where the status field is also editable.
    *   The contractor can update a task’s status **from the Dashboard**.
*   For **agency-assigned tasks**, the contractor can change the task status **only when the task belongs to the currently selected agency workspace**.

**4.7.1 Status Change Impact**

*   **To-Do → In-Progress:** Task moves from the _To-Do_ section to the _In-Progress_ section.
*   **To-Do → Completed:** Task moves from the _To-Do_ section to the _Completed_ tab.
*   **In-Progress → To-Do:** Task moves from the _In-Progress_ section back to the _To-Do_ section.
*   **In-Progress → Completed:** Task moves from the _In-Progress_ section to the _Completed_ tab.
*   **Completed → To-Do:** Task moves from the _Completed_ tab to the _To-Do_ section.
*   **Completed → In-Progress:** Task moves from the _Completed_ tab to the _In-Progress_ section.

**4.7.2 Completed Date Logic**

*   When the status is changed to **Completed**, the system records the **current date** as the Completed Date.
*   If the status is changed **away from Completed**, the Completed Date is **cleared**.
*   If the task is marked **Completed again**, a **new Completed Date** is recorded.

**4.7.3 Cross-Portal Sync**

*   For **agency-assigned tasks**, all status updates performed by the contractor are **synced to the Agency Portal**.

### **4.8 Search Functionality**

*   The Task module includes a search input field with a search icon and the placeholder text: **“Search by task title.”**

**4.8.1 Search Scope**

*   **To-Do Tab:** The search filters tasks in both the _To-Do_ and _In-Progress_ sections.
*   **Completed Tab:** The search filters tasks only within the _Completed_ section.
*   Search is always **restricted to the currently selected tab**

**4.8.2 Search Behavior**

*   Tasks are filtered **in real time** as the contractor types in the search field.
*   The search matches any task title that **contains** the entered text (_partial match supported_).
*   The search is **case-insensitive**.

### **4.9 Filter Functionality**

*   A **Filter** icon button is displayed next to the search bar.
*   When clicked, a **Filter drawer panel** opens from the right side, allowing the contractor to apply one or more filters.
*   **Filter Options: Refer -** [**Click Here**](#9e3hktdltzxq)
*   Filters are applied **immediately upon selection**, and the task list updates in real time.
*   All selected filters appear as **chips/tags** above the task table.
*   Each filter chip includes an **(X)** icon that allows the contractor to remove the individual filter.
*   A **“Clear All Filters”** button is available to remove all applied filters at once and reset the task list.

**4.9.1 Filter Chip Display**

*   Each filter chip clearly displays the **filter type and selected value**, such as “Priority: High” or “Due Date: Overdue.”
*   Removing a chip instantly updates the task list to reflect the remaining active filters.
*   Clicking **Clear All Filters** removes all filter chips together and restores the unfiltered task list.

### **4.11 Cross-Module Display**

**Contractor Dashboard Integration:**

*   Tasks display in Contractor Dashboard > Task Management section
*   Shows pending tasks for quick access
*   Status changes from the dashboard are also reflected in the Tasks module

**Agency Portal Sync:**

*   Agency-assigned tasks: All changes by the contractor sync to the Agency Portal
*   Status updates, priority changes, and due date modifications are visible to the agency
*   The agency can track the contractor's progress on assigned tasks

### **4.12 Tasks Email & Notifications**

*   System-generated emails and in-app notifications keep users informed about task activities and status changes.
*   Email notifications will be sent in the following scenarios:
    *   When the task due date has passed, and the task is still in To-Do or In Progress status
    *   When the task is deleted by the reporter for agency agency-assigned task
    *   When the task status is changed to Completed
    *   When the task due date is updated

## **5\. Field Details & Validations**

### **5.1 Create/Edit Task Form**

**Field Name**

**Required**

**Validation Rules**

Task Title

Yes

Maximum 200 characters

Status

Yes

Must select one: To Do, In-Progress, Completed

Reporter

Read-only

Auto-populated with logged-in contractor

Assignee

Read-only

Auto-populated with logged-in contractor

Priority

Yes

Must select one: Low, Medium, High

Created

Read-only

Auto-populated with the current date

Due Date

Yes

Must be a current date or a future date

Description

No

Optional text field

### **5.4 Task Table Columns (To-Do and In-Progress Sections)**

### **Column Name**

### **Display Format**

### **Details**

### Task

### Task title + Priority icon

### **Priority Icons:**

### \- Low: Blue downward icon

### \- Medium: Orange/yellow double chevron icon

### \- High: Red upward icon

### \- Sortable column

### Project

### Project name + Event name (or "--")

### **For agency-assigned tasks:** Project name with event name below (with color dot)

### **For self-created tasks:** "--" (double dash)

### \- Sortable column

### Brand

### Avatar + Name (or "--")

### **For agency-assigned tasks:** Brand owner avatar and name

### **For self-created tasks:** "--" (double dash)

### \- Sortable column

### Due Date

### Month DD, YYYY

### **Format:** "November 8, 2025"

### **Special Badges:**

### \- Due Today: Orange text when due date is current date

### \- Overdue: Red badge when due date has passed

### \- Normal: Standard date display for future dates

### Reporter

### User avatar

### **For self-created tasks:** Contractor's own avatar

### **For agency-assigned tasks:** The Agency user's avatar who assigned the task

### Status

### Dropdown (interactive)

### **Dropdown Options:** To-Do, In-Progress, Completed

### **Status Colors:**

### \- To-Do: Gray/default

### \- In-Progress: Orange/yellow

### \- Completed: Green

### **Functionality:** Contractor can change status directly from the dropdown

### Actions

### kebab menu

### **Options:**

### \- Edit: Opens task edit panel (available for all tasks)

### \- Delete: Removes task (available only for self-created tasks; disabled/hidden for agency-assigned tasks)

###

###

### **5.5 Task Table Columns (Completed Section)**

### **Column Name**

### **Display Format**

### **Details**

### **Note:** The following columns are the same as the To-Do and In-Progress sections: Task, Project, Brand, Reporter, Status, Actions

### Completed Date

### Month DD, YYYY

### **Format:** "November 4, 2025"

### **Logic:** Displays the date when the task status was changed to "Completed."

### **Note:** Replaces the "Due Date" column from the To-Do tab

### **5.6 Filter Fields**

## **Filter Name**

## **Field Type**

## **Options/Values**

## **Validations**

## Brand Filter

## Dropdown

## Only brands associated with events assigned to the contractor

## \- Placeholder: "Select Brand"

## \- No validation required

\- Single select

##

## Priority Filter

## Checkbox list

## \- Low

## \- Medium

## \- High

## \- Multiple options can be selected

## \- No validation required

\- Single or Multi-select

##

## Due Date Filter

## Checkbox list

## \- Due Today

## \- Due This Week

## \- Overdue

## \- Multiple options can be selected

## \- No validation required

## \- Single or Multi-select

## **6\. Error Message Handling**

**Field/Action**

**Validation Scenario**

**Error Message**

Task Title

Empty submission

"Please enter a task title."

Task Title

Exceeds 200 characters

"Task title cannot exceed 200 characters."

Due Date

Not selected

"Please select a due date."

Due Date

Past date selected

Past dates are disabled in the calendar

Priority

Not selected

"Please select a priority."

General

Save/Update fails

"Something went wrong."

Search

No results found

Display empty state in sections

## **7\. Success Message Handling**

**Action**

**Success Message**

Task created

"Task has been created successfully."

Task updated

"Task has been updated successfully."

Task deleted

"Task has been deleted successfully."

## **8\. Edge Cases**

**Scenario**

**Expected Behavior**

No tasks in the To-Do section

"No data found" message displayed in the To-Do section

No tasks in the In-Progress section

"No data found" message displayed in the In-Progress section

No tasks in the Completed tab

"No data found" message displayed in the Completed section

Both To-Do and In-Progress are empty

Both sections display "No data found" independently

Task status changed to Completed

Task moves to Completed tab; Completed Date recorded

Completed task status changed back to To-Do

Task moves back to the To-Do section; Completed Date cleared

Search with no matches

Empty state displayed in relevant sections

Filter returns no results

Empty state displayed with active filters shown as chips

The agency deletes the task while the contractor is viewing

Task disappears on next refresh

The contractor tries to delete the agency-assigned task

Delete option disabled/hidden

The task due date is today

"Due Today" badge displayed in orange

The task due date has passed

"Overdue" badge displayed in red

Multiple filters applied

All filter chips displayed; results match all selected criteria

Contractor edits agency-assigned task

Changes sync to the Agency Portal

Very long task title

Text truncated with ellipses in a table

The same task title exists

Both tasks displayed (no uniqueness validation)

## **9\. Acceptance Criteria**

*   **Global Task Module Behavior –** The system must display all tasks across all agencies globally and allow the contractor to edit agency-assigned tasks only when viewing the correct agency workspace, otherwise showing a Wrong Brand pop-up and locking the task in read-only mode.
*   **Initial Empty State –** When no tasks exist at all, the system must show a global empty message with CTA; when a specific tab has no tasks, the system must show the contextual empty state message for that tab.
*   **To-Do Tab Display –** The system must show both To-Do and In-Progress tasks with expandable sections, correct Due Today / Overdue tagging, and overdue email notifications sent once when a task crosses its due date.
*   **Completed Tab Display –** The system must move tasks to the Completed tab immediately upon status change and display them using the completed-task table configuration.
*   **Create New Task –** Clicking New Task must open the creation drawer and create a standalone personal task with the contractor as both Reporter and Assignee, without any brand/project/event linkage.
*   **Edit Task –** The system must allow editing of title, status, priority, due date, and description for personal and agency tasks (but only within the correct workspace), keeping Reporter and Assignee read-only and syncing updates back to the Agency Portal.
*   **Delete Task –** The system must allow contractors to delete only self-created tasks, showing a confirmation pop-up and permanently removing them from the Tasks module and Dashboard upon confirmation.
*   **Status Change Logic –** The system must allow changing status from table, drawer, or Dashboard and automatically move tasks between To-Do, In-Progress, and Completed sections based on the selected status.
*   **Completed Date Logic –** The system must record the current date when a task is marked Completed, clear it when reverted, and regenerate a new date when re-completed.
*   **Cross-Portal Sync –** For agency-assigned tasks, all contractor updates (status, priority, due date, description) must instantly sync to the Agency Portal.
*   **Search Functionality –** The system must filter tasks by title within the active tab in real time, searching To-Do + In-Progress together but only Completed in the Completed tab.
*   **Filter Functionality –** Applying filters must instantly update the task list, show each active filter as a chip with remove action, and support “Clear All Filters” to reset the list.
*   **Filter Chip Display –** Each filter chip must clearly show filter type and value, remove instantly on (X) click, and update the list dynamically.
*   **Cross-Module Display –** Task updates must reflect in both Contractor Dashboard Task widget and Agency Portal task views, with real-time status syncing.
*   **Email & Notification Logic –** The system must send emails and in-app notifications to the contractor and reporter as per defined triggers (assignment, status changes, overdue, deletion, due-date changes, assignee changes).

## **10\. Dependencies**

**Module/System**

**Dependency Type**

**Impact if Unavailable**

User Authentication

Security Dependency

Cannot identify the contractor for the Reporter/Assignee fields

Project/Event Management

Data Dependency

Cannot display project and event information for agency-assigned tasks

Brand Management

Data Dependency

Cannot display brand information; Brand filter is non-functional

Agency Tasks Module

Integration Dependency

Agency-assigned tasks not received; changes not synced back

Contractor Dashboard

Integration Dependency

Tasks not displayed in the Dashboard Task Management section

Calendar/Date Service

Feature Dependency

The Due Date picker is non-functional

##

## **11\. References**

*   **Link** \- [**Click Here**](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=13461-169172&t=Zeng5V4IZu3iF7VZ-0)

✅ Account Settings > General Tab

# **Account Settings - General Tab (Contractor Portal)**

## **1\. Module Overview**

*   **Module Name:** Account Settings - General Tab (Contractor Portal)
*   **Purpose:** Enable contractors to manage their personal information, professional details, profile photo, and password settings in a centralized location
*   **Business Goal:** Provide contractors with control over their account details while ensuring data consistency across all agencies they work with, as changes made in Account Settings reflect globally across the Pixally platform

## **2\. User Roles & Permissions**

**Role**

**Description**

**Key Permissions**

Contractor

Contractors working with multiple agencies

Update profile photo, edit personal information (name, email, phone), edit professional information (website/portfolio), change password

## **3\. User Flow**

**Navigation Path:** Contractor Portal > Profile Menu > Account Settings > General Tab

**Step-by-Step Flow:**

**Step 1:** Contractor clicks on profile menu in top-right corner

**Step 2:** Contractor selects "Account Settings" from the profile menu

**Step 3:** Account Settings page loads with multiple tabs: General, Location & Travel, Working Days, Additional, Gear, Finances

**Step 4:** The General tab is selected by default, displaying profile photo, personal information, professional information, and the change password sections

**Step 5:** The Contractor can upload/update their profile photo by clicking on the circular update photo button

**Step 6:** Contractor can modify personal information fields (first name, last name, email, phone)

**Step 7:** If the email is changed, the contractor must verify the new email by entering the confirmation code

**Step 8:** Contractor can update professional information (website/portfolio link)

**Step 9:** The Contractor can change the password by entering the old password, the new password, and repeating the new password

**Step 10:** Contractor clicks the common "Save changes" button to save all modifications

**Step 11:** The System validates all fields and either displays validation errors (if applicable) or saves changes successfully

## **4\. Functional Logic**

### **4.1 Global Settings Behavior**

**4.1.1 Cross-Agency Impact:**

*   Account Settings in the Contractor Portal is global across all agencies
*   Any updates made in Account Settings reflect in all agencies where the contractor is associated with
*   Changes sync to both Contractor Portal and Agency Portal views
*   Profile photo, name, email, phone, and professional details update across all agencies

### **4.2 Profile Picture**

*   **Default Picture Display:** The System displays a default pic with initials (i.e., John Doe - JD) when no profile photo is uploaded
*   **Upload/Update Profile Photo:** Client can upload or update a profile photo by clicking on the “+ Update Photo”, and it opens the user's local file system to upload the profile photo. For validations - [**Click Here**](#rz46wbuniv5a)
*   **Profile Photo Sync:** When the profile photo is updated, it automatically displays in the agency portal modules defined below
    *   Contractor Management list (Active & Setup Required Tab) and detailed profile view
    *   Project/Event listing > users
    *   Global Search
    *   Dashboard > Event Management
    *   Project details
        *   Event tab
        *   Activity tab
        *   Files/Document tab
        *   Notes tab > Public notes
        *   Email center
    *   Task Module
    *   Finance Module

### **4.3 Personal Information Section**

*   **Section Header:** "Personal Information"
*   **Pre-filled Behavior:** All personal information fields will be pre-populated with existing contractor details as added by the agency during invitation and when the contractor has filled them during onboarding, i.e., first name, last name, email address, phone number
*   **Email Verification Flow:**
    *   When the contractor updates their email address, the system sends a verification code to the new email. The verification code is valid for 10 minutes
    *   "Confirm the new email" field appears below the email field
    *   The contractor must enter the verification code to confirm the email change
    *   Email update only completes after successful verification
    *   If the same email is entered as the current, no verification is triggered
    *   Impact of email change: All future email communications will be sent to the contractor’s updated email address
*   **Impact on Agency System:** When the contractor updates personal information, it automatically updates the contractor’s details in the Contractor Management of the agency portal and in the following modules
    *   Contractor Management list (Active & Setup Required Tab) and detailed profile view
    *   Project/Event listing > users
    *   Project details
        *   Event tab
        *   Activity tab
        *   Files/Document tab
        *   Notes tab > Public notes
        *   Email center
    *   Task Module
    *   Finance Module

### **4.4 Professional Information Section**

*   **Section Header:** "Professional Information"
*   **Pre-filled Behavior:** Website/portfolio field pre-populated if previously provided
*   The user can add, update, or remove the website URL link

### **4.5 Change Password Section**

*   **Section Header:** "Change Password"
*   In the Change Password section, three input fields will be displayed: one for entering the old password, one for entering the new password, and one for repeating the new password.
*   **Password Validation Display:**
    *   Validation messages are shown progressively as the user types (one at a time) to guide the user through each requirement
    *   Users must enter their old password to change to a new password
    *   The old password must match the contractor’s current password, the new password must be different from the old password, and the new password and the “repeat new password” fields must match.
    *   New passwords must meet all specified requirements (as defined in the validation table)
    *   If the password is changed, the user will not be logged out and will remain in the system
    *   After a password change, if the user tries to log in using the old password, it will display the error message, and the user will not be able to log in
    *   New password – The contractor will be able to log in using the new password after successfully changing the password
    *   Field Details. Refer - [**Click Here**](#fiiyp57c6wo)

### **4.6 Save Changes Button**

*   **Button Display:** Each section will have a separate "Save changes" button
*   **Save Flow:**
    *   User clicks "Save changes."
    *   System validates all modified fields
    *   If validation fails: Display inline error messages under respective fields
    *   If validation passes:
        *   Save all changes to the database
        *   Sync changes across all agencies
        *   Display a success message

### **4.7 Cancel Button**

*   **Cancel Behavior:** Resets fields to their original values, without making changes

### **4.8 Date & Time Preferences**

*   The date format dropdown offers multiple options including DD/MM/YYYY, MM/DD/YYYY, and YYYY-MM-DD formats.
*   The selected date format applies immediately to all date displays throughout the contractor's interface.
*   The day of the week is automatically included with the selected date format by default (e.g., "Sat, 25/12/2023"). There is no option to disable this setting.
*   The time format setting provides two options: 12 hour (AM/PM) format and 24 hour format.
*   Date and time preferences are contractor-specific and do not affect how other users see timestamps in shared contexts.
*   The system stores dates and times internally in ISO format regardless of display preferences to ensure consistency.
*   Contractors can revert to default settings using the "Reset Changes" button or confirm their selections with "Save changes".
*   Timezone detection occurs automatically based on the contractor's browser settings or IP address location.

### **4.9 Date Formatting Guide**

*   The Date Formatting Guide can be accessed by clicking the "Date Formatting Guide" link located in the top-right corner of the Date & Time Preferences section.
*   The guide displays examples of how dates appear with different format selections.
*   Format options include multiple standards like DD/MM/YYYY, MM/DD/YYYY, and YYYY-MM-DD to accommodate regional preferences.
*   The guide shows real-time previews of how dates will display with the current settings applied.
*   This section is informational only and actual date format changes occur in the Date & Time Preferences settings per user.
*   The guide helps users understand the impact of their format choices before making changes.

## **5\. Field Details & Validations**

### **5.1 Personal Information**

**Field Name**

**Required**

**Validation Rules**

Profile Photo

File Upload

JPEG/JPG format, Max 15 MB, Only from the local system

First Name

Yes

Maximum 50 characters

Last Name

Yes

Maximum 50 characters

Email Address

Yes

Valid email format; Must be unique across the Pixally platform

Confirm New Email

Yes (when email changed)

Must match verification code sent to new email

Phone Number

No

Valid phone number format; Country code selector with US (+1) as default; Uniqueness not required

### **5.2 Professional Information**

**Field Name**

**Required**

**Validation Rules**

Website or Link to Portfolio

No

Valid URL format

### **5.3 Change Password**

**Field Name**

**Required**

**Validation Rules**

Old Password

Yes (when changing password)

Must match current account password

New Password

Yes (when changing password)

Min 6 - Max 20 chars, 1 uppercase, 1 lowercase, 1 number, 1 special char, no spaces; Cannot be the same as the old password

Repeat New Password

Yes (when changing password)

Must exactly match the New Password field

Eye Icon

Toggle

Eye toggle on click, it will hide/display the password

## **6\. Error Message Handling**

**Field**

**Validation Scenario**

**Error Message**

Profile Photo

Invalid file format

"Please upload a valid JPEG or JPG image."

Profile Photo

File exceeds 15 MB

"Image size cannot exceed 15 MB."

First Name

Empty

"Please enter your first name."

First Name

Exceeds 50 characters

"First name cannot exceed 50 characters."

Last Name

Empty

"Please enter your last name."

Last Name

Exceeds 50 characters

"Last name cannot exceed 50 characters."

Email Address

Empty

"Please enter your email address."

Email Address

Invalid format

"Please enter a valid email address."

Email Address

Already exists in the system

"This email is already registered."

Confirm New Email

Empty

"Please enter the verification code."

Confirm New Email

Invalid code

"Invalid verification code. Please try again."

Phone Number

Invalid format

"Please enter a valid phone number."

Website URL

Invalid format

"Please enter a valid URL."

Old Password

Empty submission

"Please enter your current password."

Old Password

Incorrect password

"Current password is incorrect."

New Password

Empty submission

"Please enter a new password."

New Password

Length < 6 characters

"Password must be at least 6 characters."

New Password

Length > 20 characters

"Password cannot exceed 20 characters."

New Password

Missing uppercase

"Password must contain at least one uppercase letter."

New Password

Missing lowercase

"Password must contain at least one lowercase letter."

New Password

Missing number

"Password must contain at least one number."

New Password

Missing special character

"Password must contain at least one special character."

New Password

Contains spaces

"Password cannot contain spaces."

Repeat New Password

Passwords don't match

"Passwords do not match."

General

Save operation fails

"Something went wrong."

## **7\. Success Message Handling**

**Action**

**Success Message**

Profile photo uploaded/updated

"Profile photo updated successfully."

Personal information updated successfully

"Your account information has been updated successfully."

Password changed successfully

"Your password has been changed successfully."

##

## **8\. Edge Cases**

**Scenario**

**Expected Behavior**

Contractor uploads logo instead of personal photo

System accepts image; guidance text reminds "Please upload a photo of yourself, not a logo."

Contractor enters the same email as the current one

No verification flow triggered; email remains unchanged

Phone number already exists in the system

Allowed - phone number uniqueness not enforced

Contractor tries to save with validation errors

Form displays inline errors; no data saved

Password meets all requirements except one

Progressive error message shows the next missing requirement

Network error during save

Display "Something went wrong. Please try again."

Contractor cancels after making changes

All fields reset to their original saved values

Profile photo upload fails

Display "Failed to upload photo. Please try again."

## **9\. Acceptance Criteria**

*   The default avatar shows initials with a fixed background color when no photo is uploaded
*   Profile photo accepts .jpeg, .jpg formats up to 15 MB
*   First name and last name are required, with max 50 characters each
*   Email must be a valid format and unique across Pixally
*   Changing email triggers verification code flow; the new email is saved only after verification
*   Phone number is optional with country code selector (US default); uniqueness not enforced
*   Website/portfolio link is optional; must be a valid URL format if provided
*   The old password must match the current account password
*   New password requires: Min 6, Max 20, 1 uppercase, 1 lowercase, 1 number, 1 special char, no spaces
*   Progressive password error messages show the next missing requirement
*   The new password cannot match the old password
*   Repeat password must exactly match the new password
*   A successful password change logs the user out
*   The common "Save changes" button saves all sections
*   The cancel button resets all fields to their original values
*   All changes sync globally across all agencies

## **10\. Dependencies**

**Module/System**

**Dependency Type**

**Impact if Unavailable**

User Authentication

Security Dependency

Cannot verify old password; cannot enforce re-login after password change

Email Service

Integration Dependency

Cannot send verification code for email change

File Storage System

Data Dependency

Cannot upload or display profile photos

Database Sync Service

Integration Dependency

Changes are not reflected across agencies

## **11\. References**

*   **Link -** [**Click Here**](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=7948-186002&t=NNg4dIg7UjP9pcET-0)

✅ Location & Travel

# **Account Settings — Location & Travel Tab (Contractor Portal) — FRD**

**Change summary (this version):** Adds the **address-change confirmation pop-up** shown to the contractor when they save a changed **street address** (**Update Anyway** saves + triggers the agency email; **Cancel** or **×** discards — nothing saved). The pop-up lists **every** agency the contractor works with, each with its current-event count and events. Only a **Google Places street change** counts as an address change (drives the pop-up, the agency-side history/timestamp, and the agency email); Apartment #/ZIP-only edits do not. Reinforces that address changes affect **new/future assignments only** (existing assignments frozen regardless of date; past/completed unaffected), that **distance recalculates but the travel fee never changes automatically**, and that an **email** is sent to the associated agency/agencies.

**Note:** Pop-up copy is **final** per the approved design (§4.2.6). The agency email fires on **Update Anyway** and goes to all agencies the contractor is associated with; its content is managed separately (§4.2.5).

**Related FRD:** Contractor Profile Module (Agency Portal) — agency-side Address display, last-changed timestamp, and previous-address history.

## **1\. Module Overview**

*   **Module Name:** Account Settings - Location & Travel Tab (Contractor Portal)
*   **Purpose:** Enable contractors to manage their home address and travel preferences for each brand they work with, ensuring accurate distance calculations for travel-fee determinations and providing control over travel-willingness settings.
*   **Business Goal:**
    *   Provide contractors the ability to update their home address, used to calculate distance between the event venue and the contractor's location for travel-fee purposes.
    *   Allow contractors to set agency-specific travel preferences based on agency-defined parameters.
    *   Ensure data consistency across all agencies, as home-address changes reflect globally across the Pixally platform.

## **2\. User Roles & Permissions**

**Role**

**Description**

**Key Permissions**

Contractor

Contractors working with multiple agencies and brands

Update home address (address line, apartment number, ZIP code, city); modify travel preferences for each brand independently

## **3\. User Flow**

**Navigation Path:** Contractor Portal > Profile Menu > Account Settings > Location & Travel Tab

**Step-by-Step Flow:**

1.  Contractor clicks the profile menu (top-right).
2.  Contractor selects "Account Settings."
3.  Account Settings loads with tabs: General, Location & Travel, Working Days, Additional, Gear, Finances.
4.  Contractor clicks the "Location & Travel" tab.
5.  The tab displays two sections: **Home Address** (pre-filled with onboarding data) and **Travel Preferences** (all brands, pre-filled with onboarding data).
6.  Initially, Cancel and Save Changes buttons are hidden in the Home Address section.
7.  Contractor clicks the Address Line field to modify their home address.
8.  As the contractor types, Google API displays location suggestions.
9.  Contractor selects an address from Google API suggestions.
10.  System auto-populates: Address Line, Apartment Number (if available), ZIP Code (if available), Country, State, City (if available).
11.  If Apartment Number or ZIP Code isn't provided by Google API, inline errors appear below the respective fields.
12.  Contractor manually enters the missing Apartment Number and ZIP Code.
13.  Once a different address is selected from Google API, Cancel and Save Changes buttons appear for the Home Address section.
14.  Contractor clicks "Save changes."
15.  **If the street address changed (via Google selection), the system displays the Address-Change Confirmation pop-up (§4.2.6),** which lists all the agencies the contractor works with. On **Update Anyway**, the change is saved and applied across all agencies; on **Cancel**, the change is discarded and nothing is saved.
16.  System validates required fields and either displays validation errors or saves successfully.
17.  In Travel Preferences, the contractor views brand-wise settings (most recently assigned brand first).
18.  For each brand, the contractor can modify two dropdowns (travel without fees / travel with fees).
19.  Modifying any travel preference dropdown reveals Cancel and Save Changes for that section.
20.  Contractor clicks "Save changes" in Travel Preferences.
21.  System saves the updated travel preferences for all modified brands.
22.  System displays a success message.
23.  Clicking Cancel in either section resets fields to their original values without changes.

## **4\. Functional Logic**

### **4.1 Global Behavior**

*   The **Home Address** is a **global setting** shared across all agencies the contractor is associated with. Any update reflects immediately across every agency and brand connected to the contractor.
*   The Home Address is the contractor's **primary location reference**, used to calculate the distance between the contractor's home and the event venue for **travel eligibility and travel-fee calculations**.
*   **Travel Preferences** are **brand-specific** and can vary per brand. Under the same agency, defaults initially match across brands, but the contractor can customize per brand without impacting other brands or global settings.
*   **Agency-side visibility (cross-reference):** the current Home Address, a **last-changed timestamp**, and a **hover history of the last two previous addresses** are displayed on the **agency side** (Contractor Profile → Info tab). This history/timestamp is **not** shown to the contractor in this tab. Full display specification is in the **Contractor Profile Module FRD, §4.3.1**.

### **4.2 Home Address Section**

#### **4.2.1 Initial State**

*   All Home Address fields are pre-populated with onboarding values. Fields: Address Line, Apartment Number, ZIP Code, Country, State, City.
*   Country, State, and City are **read-only** and populated from the Google API selection.

#### **4.2.2 Address Line Field — Google API Integration**

*   The Address Line field supports Google Places Autocomplete.
*   On typing, suggestions appear in a dropdown. The contractor **must select** an address from suggestions; manual entry without selecting is **not allowed**.
*   **Auto-population on selection:** Address Line (always), Apartment Number (if provided), ZIP Code (if provided), Country (always → read-only), State (always → read-only), City (if provided → read-only).
*   **Missing data handling:** if Google API doesn't return Apartment Number or ZIP Code, the field remains blank, an inline error appears, and the contractor must complete it before saving.
*   **City field behavior:** read-only after selection; if not returned, remains blank until a more specific address is selected.

#### **4.2.3 Button Display Logic**

*   Cancel and Save changes are hidden on initial load.
*   Buttons appear when: a new address is selected from Google API, or the contractor modifies Apartment Number or ZIP Code.
*   **Save Changes behavior:** validate mandatory fields; on failure show inline errors; on success save, **sync globally**, and display a success message. Saving affects only the Home Address section. (If the street address changed, the Address-Change Confirmation pop-up in §4.2.6 gates the save.)
*   **Cancel behavior:** revert all Home Address fields to last saved values; clear errors; hide Save/Cancel.

#### **4.2.4 Update Impact Across Contractor Portal**

*   After saving, the updated Home Address appears immediately in Contractor Portal → Account Settings → Location & Travel → Home Address.
*   No other contractor-portal modules are directly modified by the update; distance and travel-fee logic are triggered per the main system logic (§4.2.5).

#### **4.2.5 Home Address Update Impact**

*   The Home Address is the reference location for calculating distance between event venue and contractor, and for determining travel eligibility / travel-fee rules.
*   **When the Home Address is updated:**
    *   **Only new/future event assignments** use the new address for distance and travel-fee calculation.
    *   **Events already assigned** to the contractor retain their **previously calculated distance and travel-fee amounts**, **regardless of the event's date**. Past/completed events are likewise unaffected. No retroactive recalculation is applied.
    *   **Distance/miles recalculate** to the new address for new assignments; however, the **travel fee is never changed automatically** — any adjustment is made **manually by the agency**.
    *   An **email notification** is sent to the agency/agencies the contractor is currently associated with, informing them of the address change (email content managed separately). See the Contractor Profile Module FRD §4.3.2 for the agency-side surfacing.

#### **4.2.6 Address-Change Confirmation Pop-up (Contractor) — UPDATED**

**Trigger**

*   Displayed when the contractor **clicks Save** in the Home Address section **and the street address has changed via Google Places selection**.
*   **Not** triggered when only the Apartment Number or ZIP Code was edited (no new Google selection).

**Purpose**

*   Because the Home Address is **global**, a change propagates to **every agency the contractor works with**. The pop-up makes this reach explicit, lists every agency it will affect (flagging where the contractor currently has active events), and reminds them that travel fees for those events will **not** update automatically.

**Type & behavior** _(structure modeled on the "Warning: Pending Items" delete-contractor pop-up)_

*   **Non-blocking, warning-style** confirmation dialog with two actions:
    *   **Update Anyway:** saves the new address (proceeds with the normal Save flow, global sync, and agency email).
    *   **Cancel:** dismisses the dialog and **discards** the change — the address is **not** saved; fields revert to last saved values.
*   The pop-up appears **every time** a qualifying (street/Google) address change is saved.
*   **Email trigger:** the agency email (§4.2.5) is sent **only** when the contractor selects **Update Anyway** on a qualifying street-address change. It is **not** sent on **Cancel**, and **not** sent for Apartment #/ZIP-only edits.

**Layout & content** _(final copy, per the approved design):_

1.  **Title (with warning icon):** "Please confirm your address change".
2.  **Close (×) icon:** top-right; dismisses the pop-up and **discards** the change (equivalent to Cancel — nothing is saved).
3.  **Intro line:** "Your home address is used by every agency you work with, so this change will apply across all of them:"
4.  **Per-agency breakdown** — one group **per agency the contractor works with** (all of them):
    *   **Group header:** agency name (left) + current-event count (right) — e.g., "BRIGHT STUDIO … 2 current events". Agencies with none show "no current events" — e.g., "NOVA AGENCY … no current events".
    *   **Event rows (per event):** a project/event icon and the project name on the first line; below it, the **color-coded event-type dot** + event type + date — e.g., "Jadon & Monika Wedding" / "• Rehearsal Dinner · Dec 20, 2025". Omitted for agencies with no current events.
5.  **Warning callout (highlighted, with info icon):** "Updating your address won't automatically change your travel fee for these events. Please coordinate with each agency directly."
6.  **Buttons:** "Cancel" (discards — nothing is saved) · "Update Anyway" (saves the new address; applies across all agencies).

**Data shown**

*   **Agencies listed:** **all** agencies the contractor is currently associated with. Agencies with no current events are still listed and show a zero/none indicator.
*   **"Current events":** the contractor's **upcoming, already-assigned events** (not yet completed) with each agency — i.e., the events whose distance and travel fee are **frozen** and will **not** be re-priced by this change (§4.2.5).

**Empty / edge states**

*   **No current events with any agency:** the pop-up is still shown (the new address still applies to future assignments); every agency is still listed, each with a "no current events" indicator; the general travel-fee caution is still displayed.
*   **Single agency:** a single agency group is shown; behavior is otherwise identical.

### **4.3 Travel Preferences**

#### **4.3.1 Initial Values**

*   On first open, all Travel Preference dropdowns are pre-populated with values selected during onboarding.
*   If not modified during onboarding, the system applies the **agency's base Travel Preference settings** as defaults for all brands under that agency.

#### **4.3.2 Brand Display Logic**

*   Brands display in descending order by most recently assigned brand (most recent first).
*   A contractor may be associated with multiple brands under the same agency and brands under different agencies. Each brand appears as a **separate row** with its own dropdowns.
*   Per brand, the system displays the Brand Logo & Name and two dropdowns:
    *   "How far are you willing to travel (one way) without requiring a travel fee?"
    *   "How far are you willing to travel (one way) when a travel fee is provided?"

#### **4.3.3 Travel Without Requiring a Travel Fee**

*   Default (starting) value is the agency's **base travel distance** from Agency General Settings (e.g., base = 50 → first dropdown starts at 50 miles).
*   **Dropdown options:** 10 numeric options in **25-mile increments** from the base value, plus **"Any"** at the end (total 11).
*   **If agency base = "Any":** the contractor sees only "Any," the dropdown is **read-only**, and the value cannot be modified.
*   All brands under the same agency follow the same base value; the contractor can modify per brand. Different agencies may have different base values.

#### **4.3.4 Travel When a Travel Fee Is Provided**

*   Values depend on the first dropdown. **Starting value = (first dropdown value + 25 miles)** (e.g., 50 → 75; 100 → 125).
*   **Dropdown options:** 10 numeric options in 25-mile increments plus **"Any"** (total 11).
*   **Dynamic update:** changing the first dropdown refreshes the second dropdown's options (recalculated from the new value + 25).
*   **Special case — first dropdown = "Any":** the second dropdown auto-sets to **"Any"** and becomes **read-only**.
*   **Validation:** the second dropdown value is always ≥ the first dropdown value through its option logic.

#### **4.3.5 Button Display Logic**

*   Cancel and Save changes are hidden on first open; they appear when any brand's first or second dropdown value changes. Modifying any single brand triggers button visibility for the entire section.
*   **Save Changes:** validates that both dropdowns for every brand have a value; on success saves updated preferences per modified brand, syncs to the database, shows a success message, and hides the buttons. Saved values apply only to the specific brand.
*   **Cancel:** resets all dropdowns to last saved values and hides the buttons.

#### **4.3.6 Travel Preference Impact**

*   Updates to Travel Preferences apply **only to future project assignments**. Changes do **not** affect projects/events already assigned; previously assigned projects retain their original travel distance calculations and travel-fee pay rates (no retroactive updates).
*   **Travel Without Fee:** one-way distance (miles) the contractor will travel at no additional fee.
*   **Travel With Fee:** maximum one-way distance the contractor will travel when a fee is provided.
*   **Travel Fee Calculation Formula:** Travel Fee = round-trip distance × rate per mile.
*   **Example:** Travel without fee = 50 miles; venue 40 miles → no fee; venue 60 miles → fee applies.
*   **Future impact:** updated values are used to determine travel-fee eligibility and calculations for **new** project assignments only; already-assigned events are not recalculated.

## **5\. Field Details & Validations**

### **5.1 Home Address Fields**

**Field Name**

**Field Type**

**Required**

**Validation Rules**

**Editability**

Address Line

Text input with Google Places autocomplete

Yes

Must be selected from Google API suggestions; cannot be manually typed

Editable via Google API only

Apartment Number

Text input

Yes

Max 50 characters; always mandatory

Editable / manually fillable

ZIP Code

Text input

Yes

Valid ZIP code format

Editable / manually fillable

Country

Text

Yes

Auto-filled by Google API

Read-only after selection

State

Text

Yes

Auto-filled by Google API

Read-only after selection

City

Text

No

Auto-filled by Google API

Read-only (even if blank)

### **5.2 Address-Change Confirmation Pop-up — UPDATED**

**Field / Element**

**Type**

**Validation / Behavior**

Pop-up trigger

System

Fires on Save **only** when the street address changed via Google selection; not on Apartment #/ZIP-only edits

Title

Text (display)

Warning-style heading with warning icon: "Please confirm your address change"

Close (×) icon

Button

Top-right; dismisses and discards the change (equivalent to Cancel — nothing is saved)

Intro line

Text (display)

"Your home address is used by every agency you work with, so this change will apply across all of them:"

Per-agency group header

Text (display)

Agency name (left) + current-event count (right); one group per agency the contractor works with (all agencies); shows "no current events" if none

Event row

Text (display)

Project/event icon + project name; below it, color-coded event-type dot + event type + date, per current event

Warning callout

Info card (highlighted, info icon)

"Updating your address won't automatically change your travel fee for these events. Please coordinate with each agency directly."

Update Anyway

Button

Saves the new address; applies across all agencies; proceeds with global sync and agency email

Cancel

Button

Discards the change; nothing is saved; fields revert to last saved values

### **5.3 Travel Preferences Fields**

**Field Name**

**Field Type**

**Required**

**Validation Rules**

**Dependency**

How far are you willing to travel (one way) without requiring a travel fee?

Dropdown

Yes

Select one from available values; options based on agency settings

Agency General Settings (base value)

How far are you willing to travel (one way) when a travel fee is provided?

Dropdown

Yes

Select one from available values; starting value = (first dropdown + 25 miles)

First dropdown value

## **6\. Error Message Handling**

### **6.1 Home Address Errors**

**Field**

**Validation Scenario**

**Error Message**

Address Line

Empty submission

"Please select your address."

Apartment Number

Empty after Google API selection

"Please enter the apartment number."

Apartment Number

Empty on save

"Please enter the apartment number."

Apartment Number

Exceeds 50 characters

"Apartment number cannot exceed 50 characters."

ZIP Code

Empty after Google API selection or on save

"Please enter the ZIP code."

ZIP Code

Invalid format

"Please enter a valid ZIP code."

General

Save operation fails

"Something went wrong."

Google API

Network error during address call

"Unable to fetch address suggestions. Please try again later."

### **6.2 Travel Preferences Errors**

**Field**

**Validation Scenario**

**Error Message**

General

Save operation fails

"Something went wrong."

## **7\. Success Message Handling**

**Action**

**Success Message**

**Display Location**

Home address updated successfully

"Contractor settings updated successfully."

Top of the page (toast/banner)

Travel preferences updated successfully

"Contractor settings updated successfully."

Top of the page (toast/banner)

Note: The Address-Change Confirmation pop-up is a pre-save confirmation, not a success message. The success toast displays after the contractor selects **Update Anyway** and the save completes.

## **8\. Edge Cases**

**Scenario**

**Expected Behavior**

Google API doesn't return Apartment Number and ZIP Code

Inline errors under both fields; contractor must fill both before saving

Contractor selects the same address as currently saved

Buttons still appear; on save, success message displays even though nothing changed. (No pop-up if the street address did not change.)

Contractor modifies Home Address and Travel Preferences simultaneously

Independent Save/Cancel per section; each saved separately

Agency changes base travel preference after the contractor has set preferences

Existing preferences unchanged; dropdown options update on next edit

First dropdown changed from specific mileage to "Any"

Second dropdown auto-sets to "Any" and becomes read-only

Contractor newly added to a brand

Brand appears in Travel Preferences with default values (agency + onboarding)

Multiple brands under the same agency

All brands display with identical base settings

Contractor clicks Cancel after making changes

Fields reset to last saved values; buttons hidden; no success message

**Contractor changes the street address and clicks Save**

Address-Change Confirmation pop-up appears listing agencies with current events; **Update Anyway** saves and sends the agency email; **Cancel** discards

**Contractor edits only Apartment # or ZIP and clicks Save**

No confirmation pop-up; change saves normally; no agency email; no agency-side history entry

**Contractor clicks Cancel on the confirmation pop-up**

Address change is discarded; nothing is saved; fields revert to last saved values

**Contractor closes the pop-up via the × icon**

Same as Cancel — the change is discarded; nothing is saved

**Contractor works with multiple agencies**

Pop-up lists **every** agency the contractor works with, each with its current-event count (and events, where any); on **Update Anyway** the new address applies across all agencies

**Contractor has no current/upcoming events with any agency**

Pop-up still appears (address applies to future assignments); every agency is still listed with a "no current events" indicator; the travel-fee caution is still shown; **Update Anyway** saves

**Contractor changes address while already assigned to future-dated events**

Assigned events keep their original distance and travel fee (no recalculation); only new assignments use the new address

**Address change would place the contractor beyond a no-fee threshold for future assignments**

Distance recalculates for new assignments; no travel fee is added automatically; agency adjusts manually

## **9\. Acceptance Criteria**

*   **Global Behavior:** Home Address is global across all agencies and used for distance/travel-fee calculations; Travel Preferences remain brand-specific.
*   **Home Address Prefill / Autocomplete / Auto-populate / Edit detection / Save / Cancel:** function as specified (Google-selection required; read-only Country/State/City; Save/Cancel appear on change; global sync on save).
*   **Address-Change Pop-up (UPDATED):** On saving a **street change made via Google selection**, a warning-style pop-up is shown that (a) states the address is shared across all agencies, (b) lists **every** agency the contractor works with, each with a current-event count (and its events, where any), and (c) cautions that travel fees for those events won't update automatically and to coordinate with each agency. **Update Anyway** saves (and triggers the agency email) and applies across all agencies; **Cancel** discards (nothing saved). Shown on every qualifying change; **not** shown for Apartment #/ZIP-only edits.
*   **Change trigger consistency:** Only a Google-selection street change counts as an address change for the pop-up, the agency-side timestamp/history (Contractor Profile Module FRD), and the agency email.
*   **Home Address Impact:** Updated address applies **only to new/future assignments**; already-assigned events (any date) and past/completed events are never recalculated.
*   **Distance vs. fee:** Distance/miles recalculate to the new address for new assignments; the **travel fee never changes automatically** (manual by the agency).
*   **Agency email:** An email is sent to the associated agency/agencies on a qualifying address change (content managed separately).
*   **Travel Preferences options / dependency / "Any" behavior / impact:** function as specified; updated preferences apply only to future assignments.

## **10\. Dependencies**

**Module**

**Dependency Type**

**Impact if Unavailable**

Google Places API

External Integration

Cannot fetch address suggestions; contractor cannot update home address; Address Line becomes non-functional

Agency General Settings

Data Dependency

Cannot determine base values for travel preference dropdowns

Contractor Onboarding Module

Data Dependency

Initial home address and travel preferences cannot be pre-populated

Distance Calculation Module

Business-Logic Dependency

Distance for new assignments cannot be recalculated on address change

Email Service

Service Dependency

Address-change email to the agency cannot be sent

Database Sync Service

Integration Dependency

Home-address changes not reflected across agencies; travel preferences do not sync

Event Management (cross-agency)

Data Dependency

Cannot populate the per-agency current-event list and counts shown in the confirmation pop-up

Agency Portal (Contractor Profile)

Integration Dependency

Updated address, timestamp, and history do not reflect on the agency side

## **11\. References**

*   **Figma Link:** Click Here
*   **Related FRD:** Contractor Profile Module (Agency Portal) — agency-side Address display, last-changed timestamp, and previous-address history.

✅ Working Days

# **Account Settings - Working Days Tab (Contractor Portal)**

## **1\. Module Overview**

*   **Module Name:** Account Settings - Working Days Tab (Contractor Portal)
*   **Purpose:** Enable contractors to configure their weekly working day availability and set their booking window limit for future event assignments
*   **Business Goal:** Allow contractors to control their availability across all agencies they work with, ensuring agencies can only assign them to events on their designated working days and within their specified booking window, while maintaining flexibility to update these preferences as needed

## **2\. User Roles & Permissions**

**Role**

**Description**

**Key Permissions**

Contractor

Contractors working with multiple agencies

Set working days (Sunday-Saturday), set availability for future bookings limit, update availability settings

## **3\. User Flow**

**Navigation Path:** Contractor Portal > Profile Menu > Account Settings > Working Days Tab

**Step-by-Step Flow:**

**Step 1:** Contractor clicks on the profile menu and selects "Account Settings"

**Step 2:** Contractor clicks on the "Working Days" tab from the tab navigation

**Step 3:** System displays the Working Days section with day toggles and the Availability for Future Bookings dropdown

**Step 4:** All fields are pre-filled with values set by the contractor during onboarding

**Step 5:** The Contractor can toggle days on/off to update working day availability

**Step 6:** The Contractor can change the Availability for Future Bookings dropdown value

**Step 7:** When any change is made, the Cancel and Save changes buttons appear

**Step 8:** Contractor clicks "Save changes" to save updates

**Step 9:** System validates and displays a warning pop-up if applicable, then saves changes

## **4\. Functional Logic**

### **4.1 Global Settings Behavior**

*   Working Days settings are global across all agencies the contractor works with
*   Changes apply to all current and future agency relationships
*   Agencies cannot assign a contractor to events on non-working days
*   Settings reflect immediately in the Calendar module as striped do-not-book days

### **4.2 Working Days Section**

**Day Toggles:**

*   Seven toggle switches displayed vertically (Sunday through Saturday)
*   Each toggle has a day name label next to it
*   Toggle ON (yellow/orange): Contractor is available to work on this day and can be assigned to an event on that day
*   Toggle OFF (gray): Contractor is not available to work on this day

**Toggle Behavior:**

*   Click the toggle to switch between ON and OFF states
*   At least one day must remain ON at all times
*   When any toggle state changes from the saved value, the Cancel and Save changes buttons appear

**Pre-filled Values:**

*   All toggles display values set by the contractor during onboarding
*   Reflects the current saved working days configuration

### **4.3 Availability for Future Bookings Section**

*   Pre-filled with the value set during onboarding

**Dropdown Options:**

*   3 Months
*   6 Months
*   9 Months
*   12 Months
*   15 Months
*   18 Months
*   No limit

**Future Availability Logic**

*   Indicates the availability of contractors and how far they can be booked in advance.
*   **Rolling Window Behavior**
    *   The selected time frame (e.g., 6 months) is always counted from today’s date, not a fixed calendar range.
    *   As the current date progresses, the system automatically adds one more day at the end of the window, maintaining the selected duration (rolling availability).
    *   This ensures agencies can always book up to the chosen future period without the contractor having to update it daily.
    *   If “No Limit” is selected, then an agency can book the contractor at any time.
    *   Future availability will be throughout the system for all the agencies.
*   Unavailable days (beyond booking window) display as striped do-not-book days in Calendar

### **4.4 Save Changes Button Logic**

*   "Cancel" and "Save changes" buttons appear when any field value differs from the saved state
*   Buttons are hidden when no changes are made

**Scenario 1 - Working Day Turned Off with Existing Events:**

1.  Contractor turns off a working day (e.g., Sunday)
2.  Contractor clicks "Save changes."
3.  System checks if the contractor has any assigned events on that day across all agencies
4.  If events exist on that day, display a Warning pop-up:
    *   **Header:** "Warning!"
    *   **Message:** "You currently have jobs scheduled on \[Day Name(s)\]. You're still required to complete those \[Day Name\] jobs unless otherwise agreed with the studio owner."
    *   **Note Box:** "Please Note: Removing your working days will likely result in fewer overall bookings."
    *   **Buttons:** "Cancel" and "Update Anyway"
5.  If "Update Anyway" is clicked: Save changes, existing events remain, but no new events can be assigned on that day
6.  If "Cancel" is clicked: Close pop-up, no changes saved

**Scenario 2 - Working Day Turned Off without Existing Events:**

1.  Contractor turns off a working day
2.  The contractor clicks "Save changes."
3.  System checks and finds no events on that day
4.  Display informational pop-up:
    *   **Header:** "Warning!"
    *   **Note Box:** "Please Note: Removing your working days will likely result in fewer overall bookings."
    *   **Buttons:** "Cancel" and "Update Anyway"
5.  Proceed based on the button clicked

**Scenario 3 - Booking Window Decreased with Existing Events:**

1.  Contractor decreases booking window (e.g., from 12 months to 3 months)
2.  Contractor clicks "Save changes."
3.  System checks if the contractor has any assigned events outside the new booking window
4.  If events exist outside the new window, display a Warning pop-up:
    *   **Header:** "Warning!"
    *   **Message:** "You currently have jobs scheduled outside this new booking window. You are still required to complete those jobs unless explicitly agreed otherwise with the studio owner."
    *   **Note Box:** "Please Note: Shortening your booking window will likely result in fewer overall bookings."
    *   **Buttons:** "Cancel" and "Update Anyway"
5.  If "Update Anyway" is clicked: Save changes, existing events remain, but no new events can be assigned beyond the new window
6.  If "Cancel" is clicked: Close pop-up, no changes saved

**Scenario 4 - Booking Window Decreased (No events assigned to contractor):**

1.  The contractor decreases the booking window, and there are no events
2.  Contractor clicks "Save changes."
    1.  Display a Warning pop-up:
    2.  **Note Box**: "Please Note: Shortening your booking window will likely result in significantly fewer overall bookings."
    3.  **Buttons**: "Cancel" and "Update.”
3.  If "**Update**" is clicked:
    1.  Save all changes
    2.  No new events can be assigned to the contractor based on the updated restrictions
    3.  Display success message: "Working days and availability updated successfully."

**Scenario 5 - Both Working Days Turned Off, AND Booking Window Decreased (Combined Changes with Existing Events):**

1.  Contractor turns off one or more working days that have existing events AND decreases the booking window, and there are events outside the new booking window
2.  Contractor clicks "Save changes."
3.  System checks both conditions:
    *   If the contractor has assigned events on the turned-off day(s)
    *   If the contractor has assigned events outside the new booking window
4.  If BOTH conditions are true, display a Combined Warning pop-up:
    *   **Header**: "Warning!"
    *   **Message Line 1**: "You currently have jobs scheduled on \[Day Name(s)\]. You're still required to complete those \[Day Name\] jobs unless otherwise agreed with the studio owner."
    *   **Message Line 2**: "You also have jobs scheduled outside your new booking window. You are still required to complete those jobs unless explicitly agreed otherwise with the studio owner."
    *   **Note Box**: "Please Note: Removing your working days and shortening your booking window will likely result in significantly fewer overall bookings."
    *   **Buttons**: "Cancel" and "Update Anyway.”
5.  If "**Update Anyway**" is clicked:
    *   Save all changes
    *   All existing events remain assigned (both on turned-off days and outside the booking window)
    *   No new events can be assigned to the contractor based on the updated restrictions
    *   Display success message: "Working days and availability updated successfully."
6.  If "**Cancel**" is clicked:
    *   Close pop-up
    *   No changes saved

**Scenario 6 - Both Working Days Turned Off, AND Booking Window Decreased (No events assigned to contractor):**

1.  Contractor turns off one or more working days and has no existing events, AND decreases the booking window, and there are no events
2.  Contractor clicks "Save changes."
    1.  Display a Warning pop-up:
    2.  **Note Box**: "Please Note: Removing your working days and shortening your booking window will likely result in significantly fewer overall bookings."
    3.  **Buttons**: "Cancel" and "Update.”
3.  If "**Update**" is clicked:
    1.  Save all changes
    2.  No new events can be assigned to the contractor based on the updated restrictions
    3.  Display success message: "Working days and availability updated successfully."
4.  If "**Cancel**" is clicked:
    1.  Close pop-up
    2.  No changes saved

**Scenario 7 - Both Working Days Turned On, AND Booking Window increased (Combined Changes with Existing Events):**

1.  Contractor turns on one or more working days that have existing events AND increases the booking window, and there are events outside the new booking window
2.  Contractor clicks "Save changes."
    1.  Since the contractor is adding availability (turning working days on and increasing the booking window)
    2.  **No warning or error pop-up is displayed**
    3.  Changes are saved immediately
    4.  A success message appears: Working days and availability updated successfully."

### **4.5 Cancel Button Behavior**

*   Resets all fields to previously saved values
*   Discards all unsaved changes
*   Hides Cancel and Save changes buttons

### **4.6 Impact on Other Modules**

**4.6.1 Calendar Module:**

*   Non-working days (toggled OFF) display as striped do-not-book days
*   Days beyond the booking window display as striped do-not-book days
*   Updates are reflected immediately after saving

**4.6.2 Agency Portal Impact**

*   The contractor does not appear in Check Availability on Do Not Book Days
*   Contractor not shown in the suggested contractor lists for events on non-working days
*   Contractor not shown for events beyond their booking window

**4.6.3 Existing Event Assignments**

*   Already assigned events are NOT affected by the working days changes
*   Contractor must complete assigned events even if the day is later turned off
*   Only future event assignments are affected by settings changes

## **5\. Field Details & Validations**

### **5.1 Working Days Toggles**

**Field Name**

**Required**

**Validation Rules**

Sunday to Monday Toggle

Atleast One

At least one day must remain ON across all toggles

###

###

###

### **5.2 Availability for Future Bookings**

**Field Name**

**Required**

**Validation Rules**

Availability for Future Bookings

Yes

Must select one option from the dropdown: 3 Months, 6 Months, 9 Months, 12 Months, 15 Months, 18 Months, No limit

## **6\. Error Message Handling**

**Field/Action**

**Validation Scenario**

**Error Message**

Working Days Toggles

All days turned OFF

"Please select at least one day of availability."

Availability for Future Bookings

Not selected

"Select future days availability!"

Save Changes

Save operation fails

"Something went wrong. Please try again."

General

Network connection lost

"Something went wrong."

## **7\. Success Message Handling**

**Action**

**Success Message**

Working days updated

"Working days updated successfully."

Availability for future bookings updated

## **8\. Edge Cases**

**Scenario**

**Expected Behavior**

Contractor tries to turn off all days

Inline error: "Please select at least one day of availability." The last remaining ON toggle cannot be turned OFF

Contractor turns off the day with events from multiple agencies

The warning shows the day name; events from all agencies on that day are checked

Contractor decreases booking window, no events outside the window

Informational warning about fewer bookings displayed

Contractor increases booking window

No warning; saves immediately

Contractor makes changes, then clicks Cancel

All changes discarded; fields reset to saved values

Contractor turns off multiple days with events on some

Warning lists all day names with existing events

Event assigned on turned-off day before save

Contractor must complete the event; only future assignments are blocked

Contractor changes booking window from "No limit" to "3 Months."

Warning if events exist beyond 3 months from the current date

Network error during save

Error message displayed; changes not saved

## **9\. Acceptance Criteria**

*   **Global Settings Behavior –** System must apply working-day and booking-window settings globally across all agencies, update availability instantly in Calendar, and prevent agencies from assigning events on non-working or out-of-window days.
*   **Working Days Toggle Behavior –** System must show seven ON/OFF toggles (Sun–Sat), pre-filled from onboarding, ensure at least one day stays ON, and show Cancel/Save buttons whenever any toggle changes.
*   **Working Day ON State –** When a toggle is ON, the contractor must be treated as available and assignable for that weekday across all agencies.
*   **Working Day OFF State –** When a toggle is OFF, the system must mark that weekday as unavailable, display striped days in the Calendar, and prevent future event assignments on that day.
*   **Future Booking Window –** System must display a dropdown (3–18 months + No Limit), prefilled from onboarding, and must enforce a rolling availability window counted from today across all agencies.
*   **Future Window Impact –** Days beyond the selected booking window must display as striped, and the contractor must be excluded from assignment or check availability for events beyond that limit.
*   **Change Detection –** The System must show Cancel and Save changes buttons only when any toggle or booking window value differs from the saved data.
*   **Save Flow – Working Day OFF With Existing Events –** System must detect existing events on newly turned-off days and show a Warning pop-up requiring “Update Anyway” to continue or “Cancel” to discard.
*   **Save Flow – Working Day OFF With No Existing Events –** System must show an informational Warning pop-up and save changes only when contractor confirms “Update Anyway.”
*   **Save Flow – Booking Window Decrease With Existing Events –** System must detect events outside the new window and show a Warning pop-up requiring confirmation before saving.
*   **Save Flow – Booking Window Decrease With No Events –** System must show a Warning pop-up and save updated restrictions only if contractor confirms “Update.”
*   **Save Flow – Combined Changes With Existing Events –** If the contractor turns OFF working days _and_ reduces the booking window with events affected in both groups, the system must show a combined Warning pop-up listing both impacts and proceed only if “Update Anyway” is clicked.
*   **Save Flow – Combined Changes With No Events –** If the contractor turns OFF working days and reduces the booking window, but no events exist, the system must show a general Warning pop-up and save changes on “Update.”
*   **Save Flow – Expanding Availability (Turning ON Days or Increasing Window) –** System must save immediately without warnings and show a success message.
*   **Cancel Button Behavior –** Cancel must revert all toggles and booking-window selections to last saved values and hide action buttons.
*   **Calendar Module Impact –** Saved working-day toggles and booking-window updates must instantly reflect as striped dates; turning days ON/OFF or altering future availability must update Calendar immediately.
*   **Agency Portal Impact –** Contractors must not appear in Check Availability or suggested lists

for non-working days or dates outside the booking window.
*   **Existing Event Assignments –** Existing events must remain unaffected by changes, and contractors must still complete them even if the day is turned OFF or falls outside the new booking window.

##

## **10\. Dependencies**

**Module/System**

**Dependency Type**

**Impact if Unavailable**

User Authentication

Security Dependency

Cannot identify the contractor for to load/save settings

Event Management System

Data Dependency

Cannot check for existing events when validating changes

Calendar Module

Integration Dependency

Cannot reflect working days as striped unavailable days

Agency Portal - Availability Check

Integration Dependency

Cannot filter the contractor from unavailable days

Onboarding System

Data Dependency

Cannot retrieve initial working days values

## **11\. References**

*   **Link** \- [Click Here](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=7948-186243&t=Domgr1X3sDK9PNue-0)

✅ Additional Settings

# **Account Settings - Additional Tab (Contractor Portal)**

## **1\. Module Overview**

*   **Module Name:** Account Settings - Additional Tab (Contractor Portal)
*   **Purpose:** Enable contractors to manage their additional personal preferences, including preferred name, meal preferences, dietary restrictions, and allergy information
*   **Business Goal:** Allow contractors to maintain accurate personal preferences that can be shared with agencies and clients for event planning purposes, ensuring proper accommodation of dietary needs and personal name preferences

## **2\. User Roles & Permissions**

**Role**

**Description**

**Key Permissions**

Contractor

Contractors working with multiple agencies

Update preferred name, select meal preference, toggle and describe dietary restrictions, toggle and describe allergies

## **3\. User Flow**

**Navigation Path:** Contractor Portal > Profile Menu > Account Settings > Additional Tab

**Step-by-Step Flow:**

**Step 1:** Contractor clicks on the profile menu and selects "Account Settings"

**Step 2:** Contractor clicks on the "Additional" tab from the tab navigation

**Step 3:** System displays the Additional Settings section with all fields pre-filled from onboarding data

**Step 4:** Contractor can modify preferred name, meal preference, dietary restrictions, or allergy information

**Step 5:** When any change is made, the Cancel and Save changes buttons appear

**Step 6:** Contractor clicks "Save changes" to save updates

**Step 7:** System validates all fields and saves changes

**Step 8:** Updated information reflects in Contractor Portal settings and Agency Portal contractor profile

## **4\. Functional Logic**

### **4.1 Global Settings Behavior**

*   Additional Settings data is saved in the Contractor Portal
*   Data displays in Agency Portal > Contractor Profile > Info Tab
*   Agencies can view contractors' meal preferences and dietary information for event planning

### **4.2 Additional Settings Section**

*   All fields are pre-populated with values set by the contractor during onboarding
*   Reflects the current saved configuration

### **4.3 Preferred Name Field**

**Field Label:** "Preferred Name"

**Field Type:** Text input

**Pre-filled:** Yes, with value from onboarding

**Purpose:** Name contractor prefers to be called (may differ from legal name)

### **4.4 Meal Preference Field**

**Field Label:** "Meal Preference" with info icon (ⓘ)

**Info Icon:** Displays a tooltip on hover with additional information about meal preferences

**Field Type:** Radio button group (single select)

**Options:**

*   Chicken
*   Beef
*   Fish
*   Vegetarian
*   Vegan/Gluten-Free

**Pre-filled:** Yes, with option selected during onboarding

**Purpose:** Indicates the contractor's meal preference for events where meals are offered

### **4.5 Dietary Restrictions Toggle**

**Toggle Label:** "I have dietary restrictions."

**Field Type:** Toggle switch

**Toggle States:**

*   OFF (gray): No dietary restrictions; input field hidden
*   ON (yellow/orange): Has dietary restrictions; input field appears

**Input Field (when toggle ON):**

*   Label: "Dietary Restrictions"
*   Type: Text input
*   Pre-filled: Yes, if previously provided
*   Purpose: Describe specific dietary restrictions

### **4.6 Allergy Toggle**

**Toggle Label:** "I have an allergy."

**Field Type:** Toggle switch

**Toggle States:**

*   OFF (gray): No allergies; input field hidden
*   ON (yellow/orange): Has allergies; input field appears

**Input Field (when toggle ON):**

*   Label: "Describe your allergy"
*   Type: Text input
*   Pre-filled: Yes, if previously provided
*   Purpose: Describe specific allergies

### **4.7 Multiple Selections**

**Combined Toggles:**

*   Both "I have dietary restrictions" and "I have an allergy" can be toggled ON simultaneously
*   Each displays its own input field when ON
*   A contractor can have both dietary restrictions and allergies

###

### **4.8 Save Changes Button Logic**

**Button Display:**

*   "Cancel" and "Save changes" buttons appear only when any field value differs from the saved state
*   Buttons are hidden when no changes are made
*   "Save changes" button
*   "Cancel" button

**Save Flow:**

1.  Contractor makes changes to any field
2.  Cancel and Save changes buttons appear
3.  Contractor clicks "Save changes."
4.  System validates all fields
5.  If validation fails: Display inline error messages
6.  If validation passes: Save changes and display a success message
7.  Updated data syncs to Agency Portal > contractor module > contractor profile

### **4.9 Cancel Button Behavior**

**Cancel Action:**

*   Resets all fields to previously saved values
*   Hides Cancel and Save changes buttons
*   Discards all unsaved changes
*   Does not navigate away from the page

## **5\. Field Details & Validations**

**Field Name**

**Required**

**Validation Rules**

Preferred Name

Yes

Maximum 100 characters

Meal Preference

Yes

One option must be selected from: Chicken, Beef, Fish, Vegetarian, Vegan/Gluten-Free

I have dietary restrictions

No

Toggle ON/OFF

Dietary Restrictions (input)

Yes (when toggle ON)

Maximum 100 characters; required when toggle is ON

I have an allergy

No

Toggle ON/OFF

Describe your allergy (input)

Yes (when toggle ON)

Maximum 100 characters; required when toggle is ON

## **6\. Error Message Handling**

**Field**

**Validation Scenario**

**Error Message**

Preferred Name

Empty

"Please enter your preferred name."

Preferred Name

Exceeds 100 characters

"Preferred name must be less than 100 characters."

Dietary Restrictions

Toggle ON but input empty

"Please provide dietary restriction details."

Dietary Restrictions

Exceeds 100 characters

"Dietary restrictions must be less than 100 characters."

Describe your allergy

Toggle ON but input empty

"Please provide allergy details."

Describe your allergy

Exceeds 100 characters

"Allergy name must be less than 100 characters."

General

Save operation fails

"Something went wrong. Please try again."

##

## **7\. Success Message Handling**

**Action**

**Success Message**

Additional settings saved

"Additional settings updated successfully."

## **8\. Edge Cases**

**Scenario**

**Expected Behavior**

Contractor clears preferred name and saves

Validation error: "Please enter your preferred name."

Dietary restrictions toggle ON but input left empty

Validation error: "Please provide dietary restriction details."

Allergy toggle ON but input left empty

Validation error: "Please provide allergy details."

Both dietary restrictions and allergy toggles ON

Both input fields displayed; both must be filled

Contractor toggles OFF dietary restrictions after entering text

Input field hidden; text cleared; toggle saved as OFF

Contractor toggles OFF allergy after entering text

Input field hidden; text cleared; toggle saved as OFF

Contractor makes changes then clicks Cancel

All changes discarded; fields reset to saved values

Network error during save

Error message displayed; changes not saved

Very long text entered (100+ characters)

Character limit exceeded error displayed

## **9\. Acceptance Criteria**

**Field Display:**

*   Additional tab accessible from Account Settings
*   All fields are pre-filled with values from onboarding
*   Preferred Name displays as text input
*   Meal Preference displays as a radio button group with an info icon tooltip
*   Dietary restrictions and allergies display as toggles

**Toggle Behavior:**

*   Toggle ON reveals the input field below
*   Toggle OFF hides the input field
*   Both toggles can be ON simultaneously
*   Input required when the respective toggle is ON

**Validation:**

*   Preferred Name required with a max of 100 characters
*   Meal Preference required (one selection)
*   Dietary Restrictions input required when toggle ON, max 100 characters
*   Allergy input required when toggle ON, max 100 characters
*   Inline error messages display for validation failures

**Save and Cancel:**

*   Buttons appear only when changes made
*   Save validates and saves all changes
*   Cancel resets to previously saved values

**Cross-Portal Sync:**

*   Saved data displays in Agency Portal > Contractor Profile > Info Tab
*   Meal preferences shared with clients when meals are offered

## **10\. Dependencies**

**Module/System**

**Dependency Type**

**Impact if Unavailable**

User Authentication

Security Dependency

Cannot identify the contractor to load/save settings

Onboarding System

Data Dependency

Cannot retrieve initial additional settings values

Agency Portal - Contractor Profile

Integration Dependency

Cannot display additional settings in the contractor info tab

## **11\. References**

*   **Link -** [**click here**](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=7948-186131&t=P4kOYrtfKXAaYrmP-0)

✅ Gear Tab

# **Account Settings - Gear Tab (Contractor Portal)**

## **1\. Module Overview**

*   **Module Name:** Account Settings - Gear Tab (Contractor Portal)
*   **Purpose:** Enable contractors to manage their equipment inventory, including photography gear, videography gear, content creation equipment, drone details, and other miscellaneous gear
*   **Business Goal:** Allow contractors to maintain accurate equipment lists that can be viewed by agencies for event planning and contractor selection, ensuring agencies understand contractor capabilities and available equipment

## **2\. User Roles & Permissions**

**Role**

**Description**

**Key Permissions**

Contractor

Contractors working with multiple agencies

Update photography gear details, update videography gear details, update content creation gear details, update drone details, update other gear, upload/delete commercial drone license files

## **3\. User Flow**

**Navigation Path:** Contractor Portal > Profile Menu > Account Settings > Gear Tab

**Step-by-Step Flow:**

**Step 1:** Contractor clicks on the profile menu and selects "Account Settings"

**Step 2:** Contractor clicks on the "Gear" tab from the tab navigation

**Step 3:** The System displays Gear sections based on the contractor's invitation service type and data filled from onboarding

**Step 4:** All sections are pre-filled with values set by the contractor during onboarding

**Step 5:** The Contractor can modify any gear details in the displayed sections

**Step 6:** When changes are made to a section, the Reset Changes and Save Changes buttons for that section become enabled

**Step 7:** Contractor clicks "Save Changes" for the modified section, and the system validates and saves changes for that section

**Step 9:** Updated information is reflected in the Contractor Portal and the Agency Portal contractor profile

## **4\. Functional Logic**

### **4.1 Global Settings Behavior**

*   **Cross-Portal Display:**
    *   Gear details are saved in the Contractor Portal and reflect across all agencies, as the account settings are global. Refer - [Click Here](#xcp5hvwtk1qx)
    *   Data displays in Agency Portal > Contractor Profile > Gear Details Tab
    *   Agencies can view the contractor's equipment inventory for event planning and contractor selection

### **4.2 Section Display Logic In Gear Tab**

*   **Display Gear Details Based on Invitation Type:**
    *   **If Invited as Photographer:**
        *   Display: Photography Gear Details, Drone Details, Other Gear
        *   Requirement: Must fill either Photography Gear Details OR Drone Details (at least one required)
        *   If only Drone Drone-filled: Photography section displays, but is empty
        *   If only Photography filled: Drone section displays, but is empty
    *   **Invited as Videographer:**
        *   Display: Videography Gear Details, Drone Details, Other Gear
        *   Requirement: Must fill either Videography Gear Details OR Drone Details (at least one required)
        *   If only the Drone-filled Videography section displays, but is empty
        *   If only Videography filled: Drone section displays, but is empty
    *   **Invited** **as Content Creator:**
        *   Display: Content Creation Gear Details, Other Gear Details section
        *   Photography, Videography, and Drone sections do NOT display
    *   **Invited as Multiple Types (e.g., Photographer + Videographer):**
        *   Display all relevant sections, i.e., Photography gear details, Videography gear details, Drone Details
        *   Each section displays with a filled or empty state based on onboarding data
*   **Section Order:**

1.  Photography Gear Details
2.  Videography Gear Details
3.  Content Creation Gear Details
4.  Drone Details
5.  Other Gear

### **4.3 Photography Gear Details Section**

**Section Header:** "Photography Gear Details"

**Pre-filled Behavior:** All fields pre-populated with values from onboarding if the contractor added photography gear

**Multi-Select Dropdown Behavior:**

*   Selected values display as removable tags/chips with (×) icon
*   Click (×) to remove selection
*   Click the dropdown to add more selections

**"Other" Option Logic:**

*   When "Other" is selected from the camera type dropdown, an input field appears below
*   An input field is required when "Other" is selected
*   Removing the "Other" tag hides the input field and clears the entered text

### **4.4 Videography Gear Details Section**

**Section Header:** "Videography Gear Details"

**Pre-filled Behavior:** All fields pre-populated with values from onboarding if the contractor added videography gear

**Field Behavior:** Same as Photography Gear Details section (multi-select dropdowns, "Other" option logic. Refer - [Click Here](#o92c8iswozqq))

###

### **4.5 Content Creation Gear Details Section**

**Section Header:** "Content Creation Gear Details"

**Pre-filled Behavior:** Fields pre-populated with values from onboarding if the contractor added content creation gear

**Field Behavior:** Same multi-select dropdown and "Other" option

**4.6 Drone Details Section**

**Section Header:** "Drone Details"

**Pre-filled Behavior:** Fields pre-populated with values from onboarding if the contractor added drone details

**Display Logic:**

*   Always displayed if the contractor is invited as a Photographer or Videographer
    *   If drone details are filled in, then even if the contractor is invited as a photographer, videographer, or both, all of these sections will become optional.
*   Displays as empty if the contractor filled only Photography/Videography gear (not drone)
*   Displays with filled values if the contractor added a drone during onboarding

**Commercial License Toggle Impact:**

*   When toggle is OFF: Upload field hidden
*   When toggle is ON: Upload field appears below

**File Upload Behavior:**

*   "Upload file" button opens file browser
*   Drag-and-drop also supported
*   Can upload a maximum of 20 files total
*   Each file has a maximum 15 MB size limit

**Uploaded Files Display:**

*   Each file displays with:
    *   PDF/image icon
    *   File name
    *   File size
    *   Delete icon on the right side
*   Click the delete icon to remove the file from the upload list
*   Files are not permanently saved until the "Save Changes" button is clicked

### **4.7 Other Gear Section**

**Section Header:** "Other Gear"

**Description Text:** "Please list any other gear you own."

**Display Logic:** Always displayed for all contractors regardless of invitation type

**Pre-filled Behavior:** Text area pre-populated with a value from onboarding if the contractor added other gear

### **4.8 Reset Changes and Save Changes Buttons**

**Button Display Per Section:**

*   Each section has its own set of Reset Changes and Save Changes buttons
*   Buttons are positioned at the bottom-right of each section

**Button States:**

Initial State (No Changes):

*   Both buttons are visible but disabled
*   Cannot be clicked

After Changes Made:

*   Both buttons become enabled

**Reset Changes Action:**

*   Reverts all fields in that specific section to previously saved values
*   Includes:
    *   Dropdown selections (all tags restored)
    *   Toggle states (ON/OFF restored)
    *   Text input values (restored to saved text)
    *   Uploaded files (deleted files reappear, newly added files removed)
*   Only affects the specific section where the button is clicked, not other sections
*   Buttons return to the disabled state after reset

**Save Changes Action:**

*   Validates all required fields in that section
*   If validation fails: Display inline error messages below respective fields
*   If validation passes:
    *   Save all changes for that section (i.e., Photography)
    *   Display success message

**Agency Portal Impact**

*   Updates sync immediately to all the agencies where the contractor is working and reflect in the Agency Portal > Contractor Profile > Gear Details Tab

## **5\. Field Details & Validations**

### **5.1 Photography Gear Details**

**Field Name**

**Field Type**

**Required**

**Validation Rules**

Camera Type

Multi-select dropdown

Yes

Options: Refer - [Click Here](https://docs.google.com/document/d/1KukN8q3E8zJ13OXlMMeg_fvNGjFPxApquZg5RNMcSvA/edit?tab=t.0#bookmark=id.f2wzlj4at2u4)

At least one selection required; Includes "Other" option

Camera Type(Other)

Text input

Yes (when Other selected)

\- Maximum 100 characters

\- Required when "Other" is selected from the Camera Type dropdown

Lenses

Multi-select dropdown

No

\- Options: Refer - [Click Here](https://docs.google.com/document/d/1KukN8q3E8zJ13OXlMMeg_fvNGjFPxApquZg5RNMcSvA/edit?tab=t.0#bookmark=id.8x3a0shr3ljp)

\- Includes "Other" option

Lenses(Other)

Text input

Yes (when Other selected)

\- Maximum 100 characters

\- Required when "Other" is selected from the Lenses dropdown

I have an on-camera flash

Toggle switch

No

Toggle between ON and OFF

I have an off-camera flash

Toggle switch

No

Toggle between ON and OFF

### **5.2 Videography Gear Details**

**Field Name**

**Field Type**

**Required**

**Validation Rules**

Camera Type

Multi-select dropdown

Yes

\- Options: Refer - [Click Here](https://docs.google.com/document/d/1KukN8q3E8zJ13OXlMMeg_fvNGjFPxApquZg5RNMcSvA/edit?tab=t.0#bookmark=id.75tf3o7m1ch4)

\- At least one selection required; Includes "Other" option

Camera Type(Other)

Text input

Yes (when Other selected)

\- Maximum 100 characters

\- Required when "Other" is selected from the Camera Type dropdown

Lenses

Multi-select dropdown

No

\- Options: Refer - [Click Here](https://docs.google.com/document/d/1KukN8q3E8zJ13OXlMMeg_fvNGjFPxApquZg5RNMcSvA/edit?tab=t.0#bookmark=id.19m5vpglalx)

\- Includes "Other" option

Lenses(Other)

Text input

Yes (when Other selected)

\- Maximum 100 characters

\- Required when "Other" is selected from the Lenses dropdown

I have an on-camera flash

Toggle switch

No

Toggle between ON and OFF

I have an off-camera flash

Toggle switch

No

Toggle between ON and OFF

### **5.3 Content Creation Gear Details**

**Field Name**

**Field Type**

**Required**

**Validation Rules**

Phone

Multi-select dropdown

Yes

\- Options: Refer - [Click Here](https://docs.google.com/document/d/1KukN8q3E8zJ13OXlMMeg_fvNGjFPxApquZg5RNMcSvA/edit?tab=t.0#bookmark=id.pvmi4dsjw1jc)

\- Includes "Other" option

Phone(Other)

Text input

Yes (when Other selected)

\- Maximum 100 characters

\- Required when "Other" is selected from the Phone dropdown

### **5.4 Drone Details**

**Field Name**

**Field Type**

**Required**

**Validation Rules**

Drone Model

Multi-select dropdown

No

\- Options: Refer - [Click Here](https://docs.google.com/document/d/1KukN8q3E8zJ13OXlMMeg_fvNGjFPxApquZg5RNMcSvA/edit?tab=t.0#bookmark=id.w6grh7p454ck)

\- Includes "Other" option

Drone Model(Other)

Text input

Yes (when Other selected)

\- Maximum 100 characters

\- Required when "Other" is selected from the Drone Model dropdown

I have a Commercial License

Toggle switch

No

Toggle between ON and OFF; When ON, displays the Upload field

Upload Commercial License

File upload

Yes (when toggle ON)

\- Maximum 20 files

\- Each file max 15 MB; Allowed formats: .jpeg, .jpg, .pdf; Required when toggle is ON

###

### **5.5 Other Gear**

**Field Name**

**Field Type**

**Required**

**Validation Rules**

Other Gear Input

Text area

No

Maximum 100 characters

## **6\. Error Message Handling**

**Field**

**Validation Scenario**

**Error Message**

Camera Type (Photography)

No selection made

"Please select your camera type to proceed."

Camera Type (Videography)

No selection made

"Please select your camera type to proceed."

Camera Type(Other)

Other selected, but the input is empty

"Please specify your camera type."

Camera Type(Other)

Exceeds 100 characters

"Camera type must be less than 100 characters."

Lenses(Other)

Other selected, but the input is empty

"Please specify your lens type."

Lenses(Other)

Exceeds 100 characters

"Lens type must be less than 100 characters."

Phone(Other)

Other selected, but the input is empty

"Please specify your phone model."

Phone(Other)

Exceeds 100 characters

"Phone model must be less than 100 characters."

Drone Model(Other)

Other selected, but the input is empty

"Please specify your drone model."

Drone Model(Other)

Exceeds 100 characters

"Drone model must be less than 100 characters."

Upload Commercial License

Toggle ON, but no file uploaded

"Please upload your commercial drone license."

Upload Commercial License

File exceeds 15 MB

"File size cannot exceed 15 MB."

Upload Commercial License

Invalid file format

"Only .jpeg, .jpg, and .pdf files are allowed."

Upload Commercial License

More than 20 files uploaded

"Maximum 20 files allowed."

Other Gear

Exceeds 100 characters

"Other gear description must be less than 100 characters."

General

Save operation fails

"Something went wrong. Please try again."

## **7\. Success Message Handling**

**Action**

**Success Message**

Photography gear saved

"Gear details updated successfully."

Videography gear saved

Content creation gear saved

Drone details saved

Other gear saved

## **8\. Edge Cases**

**Scenario**

**Expected Behavior**

Contractor invited as Photographer, but filled only Drone details

The Photography section displays, but is empty; the Drone section displays with filled data

Contractor invited as Videographer, but filled only Videography details

The videography section displays filled data; the Drone section displays, but is empty

Contractor removes "Other" tag after entering text

"Other" input field hides; entered text is cleared

Contractor uploads 20 files, then tries to upload 21st

Error: "Maximum 20 files allowed."

Commercial License toggle OFF after uploading files

Upload field hides; files are cleared from selection

Contractor deletes the uploaded file, then clicks Reset Changes

Deleted file reappears in upload list

Contractor makes changes to multiple sections

Each section saves independently with its own buttons

Network error during file upload

File upload fails; error message displayed

large file selected in drone license (>15 MB)

Error: "File size cannot exceed 15 MB."

Multiple "Other" options selected across different fields

Each displays its own input field with an appropriate label

## **9\. Acceptance Criteria**

*   Gear tab accessible from Account Settings
*   Sections displayed based on contractor invitation type
*   The Photography section displays if invited as a Photographer
*   The videography section displays if invited as a Videographer
*   The Content Creation section displays if invited as a Content Creator
*   Drone section displays if invited as a Photographer or Videographer
*   The Other Gear section always displays
*   Empty sections display without data if not filled during onboarding
*   Camera Type, Lenses, Phone, and Drone Model are multi-select dropdowns
*   Selected values display as removable tags with (×) icon
*   "Other" option available in all dropdowns
*   Selecting "Other" displays an input field below the dropdown
*   Required when "Other" is selected; max 100 characters
*   Removing the "Other" tag hides the input field
*   Camera Type required in Photography and Videography sections
*   An error displays if trying to save without camera selection
*   Flash toggles switch between ON/OFF
*   Commercial License toggle shows/hides file upload field
*   The upload button and drag-and-drop are both functional
*   Maximum 20 files, each max 15 MB
*   Allowed formats: .jpeg, .jpg, .pdf
*   Uploaded files display with name, size, and a delete icon
*   The delete icon removes the file (not saved until Save Changes)
*   Each section has its own Reset Changes and Save Changes buttons
*   Buttons are disabled initially; enabled when changes are made
*   Reset reverts to saved state (including files)
*   Save validates and saves that section only
*   Saved gear details display in Agency Portal > Contractor Profile > Gear Details Tab

## **10\. Dependencies**

**Module/System**

**Dependency Type**

**Impact if Unavailable**

User Authentication

Security Dependency

Cannot identify the contractor to load/save gear details

Onboarding System

Data Dependency

Cannot retrieve initial gear values or invitation type

File Storage System

Data Dependency

Cannot upload or store commercial license files

Agency Portal - Contractor Profile

Integration Dependency

Cannot display gear details in contractor profile

## **11\. References**

*   **Figma Link -** [**click here**](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=7948-186176&t=Domgr1X3sDK9PNue-0)

✅ Stripe Integration

# **Functional Requirements Document (FRD)**

## **Module: Contractor Portal — Stripe Integration**

**Document Version:** 1.0 **Created Date:** February 25, 2026 **Author:** Business Analyst **Module Path:** Contractor Portal > Account Settings > Stripe Integration

## **1\. Module Overview**

**Module Name:** Contractor Portal — Stripe Integration

**Purpose:** The Stripe Integration module within the Contractor Portal enables contractors to connect their Stripe accounts with the agencies they work with, allowing them to receive online payments (ACH transfers) directly through the Pixally platform. This module provides contractors with a centralized view of all their agency relationships and brand assignments, along with the tools to complete Stripe onboarding, monitor verification status, and manage their payment connections across multiple agencies and brands.

**Business Goals:**

*   Enable contractors to complete Stripe Connect onboarding so they can receive automated ACH payments from agencies, eliminating the need for offline or manual payment coordination.
*   Provide contractors with a single, consolidated view of their payment connection status across all agencies and brands they are assigned to.
*   Support both Unified (one Stripe account for all brands under an agency) and Individual (separate Stripe account per brand) configurations as determined by the agency, while keeping the contractor experience clear and consistent.
*   Ensure contractors receive timely guidance and actionable feedback at every stage of the Stripe onboarding lifecycle, including pending setup, requirements due, under review, connected, and restricted states.
*   Facilitate seamless handling of agency configuration changes, new brand assignments, and brand removals without requiring contractor intervention beyond what is necessary.

##

##

##

## **2\. User Roles & Permissions**

**Role**

**Access Level**

**Permissions**

**Contractor**

Full Access

View the Stripe Integration tab, view all assigned agencies and brands, initiate Stripe Connect onboarding, complete/update/retry Stripe setup, view connection statuses, view bank account details, and expand/collapse brand details

**Agency Owner**

No Access

Cannot view or access the Contractor Portal; manages Stripe configuration from the Agency Global Settings

**Access Rule:** The Stripe Integration tab is accessible exclusively to logged-in contractors within the Contractor Portal. The contractor can only view agencies they are currently associated with and only the brands they are assigned to within each agency. No agency-side role can access or view this module.

## **3\. User Flow**

### **Page Access & Initial Load**

3.1 The contractor logs into the Contractor Portal and navigates to Account Settings from the left sidebar or profile menu.

3.2 The system loads the Account Settings page with horizontal tabs: General, Location & Travel, Working Days, Additional, Gear, and Stripe Integration.

3.3 The contractor clicks on the "Stripe Integration" tab.

3.4 The system loads the Stripe Integration page with the heading "Stripe Integration" and the subtitle "Manage your business information and payment preferences in one place."

3.5 The system displays a persistent informational banner at the top of the page titled "Payment configuration" with the subtitle "Connect and manage your payments with agencies."

3.6 The system retrieves all agencies the contractor is associated with and, for each agency, fetches only the brands the contractor is assigned to.

3.7 The system displays agency cards in alphabetical order, where each card shows the agency logo, agency name, configuration type badge ("Unified" or "Individual"), the number of brands assigned, and the applicable connection status and action buttons.

###

### **Empty State**

3.8 If the contractor has no active agency associations (e.g., all agencies have removed the contractor), the system displays an empty state with a wallet icon, the heading "Financial Information," and the message "Start receiving payment directly through Pixally."

### **Unified Flow — Agency Has Not Configured Stripe**

3.9 If the agency has not yet configured their Stripe account, the system displays the agency card without any configuration badge and without any action button.

3.10 The system displays a yellow warning banner below the brand chips stating "\[Agency Name\] hasn't configured their Stripe account yet. You'll be able to connect once they complete their setup."

### **Unified Flow — Ready to Connect**

3.11 Once the agency has completed their Stripe configuration in Unified mode, the system displays the agency card with a blue "Unified" badge and a yellow "Connect" button.

3.12 The contractor clicks the "Connect" button on the agency card.

3.13 The system opens the Stripe Account Setup page in a modal overlay on top of the Stripe Integration page, where the contractor must enter their personal details, address, identity verification documents, and bank account information.

3.14 The contractor completes all required fields on the Stripe setup form and submits it by clicking the "Confirm" button.

3.15 Upon successful submission, the modal closes and the system returns the contractor to the Stripe Integration page, where the agency card status updates to "Under Review."

### **Unified Flow — Requirements Due (Incomplete Submission)**

3.16 If the contractor exits the Stripe setup form before completing all required fields, the system displays the agency card with an orange "Requirements Due" status tag and an "Update" button.

3.17 The system displays a yellow warning banner below the brand chips stating "Some requirements are due. Please review and update them."

3.18 The contractor clicks the "Update" button, and the system opens the Stripe Account Setup modal where they left off so they can complete the remaining fields.

3.19 After the contractor completes and submits the form, the system updates the agency card status to "Under Review."

###

### **Unified Flow — Under Review**

3.20 When the Stripe account is under review, the system displays the agency card with an orange "Under Review" status tag and a "Review" button.

3.21 The system displays an informational yellow banner below the brand chips stating "Your stripe account is under verification. It could take up to 24-48 hours."

3.22 The contractor clicks the "Review" button, and the system opens the Stripe-hosted setup page in a modal where they can view and edit their submitted information.

### **Unified Flow — Connected (Approved)**

3.23 Once Stripe approves the contractor's account, the system updates the agency card to display a green "Connected" checkmark badge.

3.24 The system displays the connection count next to the brand count (e.g., "2 brands assigned · 2 of 2 connected").

3.25 The system displays a "Payment Account" section below the brand chips showing the linked bank name and masked account number (e.g., "Bank Of America · •••• 6021").

### **Unified Flow — Restricted (Rejected)**

3.26 If Stripe rejects the contractor's account, the system updates the agency card to display a red "Restricted" warning icon with a red "Retry" button.

3.27 The system displays specific error messages returned by Stripe as individual red-bordered alert rows inside the agency card, each with a red error icon.

3.28 If there are more than 3 error messages, the system displays the first 3 errors and collapses the rest behind a clickable "+ X more" link, where X is the number of remaining errors.

3.29 The system displays a red warning banner below the errors stating "There was an issue completing your onboarding. Please review the highlighted details and try again."

3.30 The contractor clicks the "Retry" button, and the system opens the Stripe Account Setup modal with their previously submitted data pre-filled so they can correct the flagged fields and resubmit.

3.31 After the contractor corrects and resubmits the form, the modal closes and the system updates the agency card status to "Under Review," and the Stripe review process begins again (24-48 hours).

3.32 This retry cycle continues until Stripe approves the contractor's account.

###

###

### **Individual Flow — Agency Has Not Configured Stripe for a Brand**

3.33 If the agency uses Individual mode and has not yet configured Stripe for a specific brand, the system displays that brand row with a green informational message stating "You'll be able to connect once the agency completes their Stripe integration for this brand."

3.34 No "Connect" button is shown for that brand.

### **Individual Flow — Ready to Connect (Per-Brand)**

3.35 Once the agency has configured Stripe for a brand in Individual mode, the system displays the agency card with an orange "Individual" badge and the connection counter (e.g., "3 brands assigned · 1 of 3 connected").

3.36 Each brand that is ready for connection is displayed as a separate row with the brand logo, brand name, a "Not connected yet" subtitle, and a yellow "Connect" button.

3.37 The contractor clicks the "Connect" button on a specific brand row.

3.38 The system opens the Stripe Account Setup modal, and the onboarding process follows the same lifecycle as the Unified flow (Connect → Requirements Due / Under Review → Connected / Restricted) but applies only to that specific brand.