✅ Calendar

Calendar Module

Functional Requirement Document

BA & Ideation: Paul Sangma

Reviewed By: KG (Project Manager)

Updated Date: 30 October 2025
Status: Approved

Version 1.0

Functional Requirement Document - Calendar Module (Agency Portal)

1. Module Overview

• Module Name: Calendar
• Purpose: The Calendar Module serves as a centralized hub for viewing, managing, and tracking all time-based activities within the CRM system. It consolidates events, tasks, meetings, and payments into unified Month View and List View interfaces, providing users with comprehensive visibility of their schedules and deadlines.
• Business Goal: Provide a unified view of all scheduled activities across the agency, enable efficient scheduling and time management, facilitate seamless integration with external calendar systems, improve project planning and resource allocation, and ensure accurate time zone handling for multi-location agencies and clients.

2. User Roles & Permissions

• Link - Roles and permissions - draft

3. User Flow

4. Functional Logic

4.1 Calendar Access and Empty State

• The Calendar module remains accessible to all authorized users (Agency Owner, Admin, Project Owner, and Team Members), even if no projects, brands, or tasks have been created.
• The module can be accessed at any time from the left sidebar menu under the “Tools” section.
• The calendar view loads in the Month View by default upon first access.
• The user can switch between Month View and List View using the toggle in the Calendar header.
• The system determines the Empty State or Populated State based on the existence of events, tasks, meetings, or payments associated with the logged-in user or their assigned projects.
• The current date (today) is always highlighted across all views and states..

4.1.1 Empty State — Month View

When there are no scheduled events, tasks, meetings, or payments for the selected month:

• The calendar grid displays an empty view with the current date highlighted.
• No placeholder illustrations or overlays are shown, maintaining a minimal interface.
• The Month/Year navigation controls (‹ ›) remain active, allowing users to browse between months.
• The View toggle (Month ↔ List) remains functional.

4.1.2 Empty State — List View

When the user switches to List View, by default, the current week (Sunday–Saturday) is displayed.If no events, tasks, meetings, or payments exist for the selected week or date range:

• The interface displays a centered message: “No events to display.”
• The list area remains blank with visible navigation controls and toggle options.
• Users can navigate between weeks (‹ ›) to locate scheduled items, if any exist.

4.2 Items Displayed in Calendar (Month View & List View)

• Once any event, meeting, task, or payment is created across any brand or project, the corresponding items will be displayed in both Month View and List View of the Calendar.
• Each item type is visually distinguished using different color codes, which the user can modify using the Filter panel.

4.2.1 Displayed Items

The following items appear in the Calendar:

• Projects’ Events
  • Events are displayed on the calendar only if a valid event date is added
  • If no specific start time is provided, the event is shown as an All-Day Event
  • If an event’s date is marked as TBD, it will not appear on the calendar until a date is assigned
  • If a project has multiple events, each event will be displayed on its respective scheduled date
  • If an event is a multi-day event, it appears across the entire duration — from Start Date to End Date
• Tasks
  • Tasks are displayed as All-Day items on their due date.
• Upcoming Payments
  • Displayed as reminders on the payment due date, as per the invoice's payment schedule. Partial payments should be visible in the calendar. Example format: Payment 2 of 3.
• Google Calendar Events/Meetings
  • Displayed Google Calendar events automatically when Google Calendar integration is enabled and sync is on for Google Calendar to Pixally. Refer - Click Here
• Calendly Meetings
  • Displayed automatically when Calendly integration is enabled. Refer - Click Here

4.2.2 Color Coding

• Event Color:
  • The default color for events is fetched from the Agency Global Settings.
• Other Items (User-Specific Colors):
  • The color codes for Tasks, Google Calendar events, Calendly meetings, and Team Members’ calendars are user-specific
  • Each user can update these colors from the Filter Settings panel
  • The color selections are stored per user and persist until modified manually

4.3 Calendar Month View

The default view when the Calendar module is accessed is always the Month View.

4.3.1 General Layout and Display Logic

• Each date cell in the Month View can contain multiple items (Events, Tasks, Payments, Google Meetings, or Calendly Meetings).
• If two events occur on the same day, both will be displayed. If more than two events occur, the system will display the first event (based on earliest time) and show "+1 more" (or similar indicator) for additional events.
• Items within each date cell are ordered:
  1. By time (earliest first), and
  2. By creation date (oldest first, if multiple items share the same time).
• Clicking on “+X more” opens a pop-up listing all items for that specific date.
• Each listed item displays its icon, color, and title for quick recognition.

4.3.2 Information Displayed per Item (Month View)

Events

• Each event label (e.g., “Wedding”) is displayed with a small color-coded dot.
• The dot color is fetched from the agency brand settings and varies by event type (e.g., “Wedding” and “Engagement” will have different colors).
• The project name will be displayed below the event type.
• Events without a start or end time are shown as All-Day events.
• If an event includes time, a start time (e.g., “12:00 PM”) appears in the block.
• Multi-day events are displayed across their entire date range (from Start Date to End Date).
• Timezone information is removed from event display in Month View.
• Clicking the Project Name redirects the user to the Event Details Page within the Project Module

Tasks

• Tasks are displayed as All-Day entries on their respective due dates
• The task title will be displayed within the task block
• The following indicator tags are removed from Month View: Due Today, Overdue, Upcoming, Paid. These tags will no longer appear in the Month View calendar cells.
• Clicking the Task Title redirects the user to the Task Details Page in the Tasks Module.

Payments

• Client payments are displayed based on the invoice payment schedule.
• Each payment block displays its installment position in the schedule along with the project name using the format: “Payment X of Y – Project Name”, where:
  • Y = total number of scheduled payments
  • X = current installment number
  • E.g.. Payment 2 of 3 - John Doe Wedding
• The amount due is also displayed within the block.Partial payments should be visible in the calendar with the format: Payment X of Y.
• The color of the payment block can be adjusted using available filters.
• Clicking the payment title redirects the user to the Finance Module → Billing → Transactions tab → Payment Status subtab, corresponding to the specific payment status

Google Calendar

• If the Google Calendar is active and Google to Pixally sync is on, it automatically displays synced meetings/events from the user’s Google account, with the Google icon (G) beside the title
• Shows the scheduled start time, duration, and meeting title. Timezone information is removed from the display.
• Clicking a Google event opens a pop-up. Refer - Click Here
• Selecting “View on Google” opens the event directly in Google Calendar

Calendly Meetings

• Displays all time-bound meetings imported via Calendly integration.
• Shows the meeting title, time, and meeting type (Phone, In-Person, or Online). On Calendar: Show Title instead of Phone Number for phone call type meetings. Phone number will be accessible via the "More Details" view.
• Clicking opens a Calendly Meeting Pop-up. Refer - Click Here
• If both Google Calendar and Calendly integrations are active, meetings are automatically synchronized and displayed

4.3.3 Click Interactions and Dialog/Popup Details

When users click on any calendar item in Month View or List View, a dialog/popup opens displaying detailed information and available actions.

A. Dialog Display Behavior

• Dialog opens centered on screen (not contextual positioning)
• No backdrop/overlay - dialog appears without dimming background
• Dialog can be closed via:
  • X button in top-right corner
  • Clicking outside the dialog area
  • Pressing ESC key
• Only one dialog can be open at a time
• Dialog displays different fields and actions based on item type
• Same dialog behavior applies to both Month View and List View

B. Event Dialog

Displayed Fields:

• Project Name
• Event Type/Name
• Start Date & Time
• End Date & Time (for multi-day events)
• Primary Venue (with full address)
• Client(s) - displayed with avatars
• Team Members - displayed with avatars

Action Button:

• "Open in Project" - Redirects to Project Details → Events Tab → Specific Event Details (opens in same tab)

C. Task Dialog

Displayed Fields:

• Title
• Project Name (if task is linked to project)
• Event Name (if task is linked to event)
• Reporter - displayed with avatar
• Assignee - displayed with avatar
• Due Date
• Description (full text content)

Action Buttons:

• "Open in Tasks" - Redirects to Tools → Tasks → Task Detail page for that specific task (opens in same tab)
• "Mark as Completed" - Marks task as completed and button disappears after action
  • Only displayed for tasks with due date today or in future
  • Not shown for tasks past their due date
  • Once clicked, task status changes to "Completed" and button is removed from dialog
  • Button disappears permanently after completion

Note: Task status tags (Due Today, Overdue, Upcoming) are NOT displayed in calendar views or in dialogs

D. Payment Dialog

Displayed Fields:

• Project Name
• Assignee - displayed with avatar
• Invoice Number (e.g., #INV00003) - display only, not clickable, fetched from invoice
• Due Date
• Amount

Action Button:

• "Open Invoice" - Redirects to Finance Module → Invoice Details page for that specific invoice (opens in same tab)

E. Google Calendar Meeting Dialog

Displayed Fields:

• Title
• Date
• Time
• Location (if location is set for the meeting)
• Google Meet link - displayed as clickable "Join with Google Meet" link with meeting URL
• Participants - displayed with avatars

Action Buttons:

• "Open in Google" - Opens the event directly in Google Calendar (opens in new browser tab)
• "Join with Google Meet" - Opens the meeting link directly in browser (opens in new browser tab)

Button State Management:

• Before or During Event: Both buttons are visible and active
• After Event End Time: Both buttons are completely hidden (not shown at all)

F. Calendly Meeting Dialogs

Calendly meetings display different dialog content based on meeting type. The system supports four meeting types:

F1) Phone Call Meeting Dialog

Displayed Fields:

• Title
• Date
• Time
• Dial Number (e.g., +1 (555) 123-4567)
• Participants - displayed with avatars
• Informational Message: "Please be ready to receive a call at the scheduled time" (displayed in yellow info/warning box)

Action Buttons:

• No action buttons displayed (phone calls don't require join links)

F2) In-Person Meeting Dialog

Displayed Fields:

• Title
• Date
• Time
• Location - full physical address (e.g., "137 Delancy St, Newark, NJ 07105, United States")
• Participants - displayed with avatars
• Informational Message: "This is a meeting where participants gather together at a physical location."

Action Buttons:

• "Show on Google Maps" - Opens the location address in Google Maps (opens in new browser tab)

F3) Google Meet / Zoom Video Meeting Dialog

Displayed Fields:

• Title
• Date
• Time
• Meeting Details - displayed as clickable link showing meeting URL (e.g., "https://zoom.us/j/93032185393")
• Participants - displayed with avatars

Action Buttons:

• "Join Meeting" - Opens the meeting link directly (opens in new browser tab)
  • For Google Meet meetings: Opens Google Meet interface
  • For Zoom meetings: Opens Zoom meeting interface

F4) Other Meeting Types Dialog

For meeting platforms other than Google Meet or Zoom:

Displayed Fields:

• Title
• Date
• Time
• Meeting Link - displayed as plain text URL (users must manually copy and paste)
• Participants - displayed with avatars

Action Buttons:

• No join button displayed
• Users must copy the meeting link manually to join

4.4 Calendar List View

• The List View provides a chronological overview of all scheduled calendar items — including Events, Tasks, Meetings, and Payments — grouped by date
• It helps users view the upcoming schedule and meetings in a linear, day-wise format for the selected week

4.4.1 Default Behavior

• When the user switches to List View, the system loads the current week (Sunday–Saturday) by default. The default view is always Month/Grid view, but when user selects the list view setting, then the list view is shown.
• The active week range is displayed at the top of the view (e.g., 16–22 November 2025).
• Navigation controls (‹ ›) allow users to move backward or forward by week
• The “Today” button resets the list to the current week.
• The List View dynamically updates when new events, tasks, or meetings are created, modified, or deleted

4.4.2 List View Layout Structure

• Each entry in the list view is grouped and displayed under the respective day header, formatted as: [Day of Week] · [Date] (e.g., Monday · November 17, 2025)
• Within each day block:
  • Items are listed with All-Day (Events and Tasks) displayed first, and then other items arranged chronologically by their start times.
• Each row includes the following columns:
• The header row (Time, Type, Title, Brand, etc.) is removed.
• Event details will be displayed directly without a header row.
• Columns should vary depending on event type.
• Example for Project Event: Event Date & Time (if applicable), Type, Title (Project Name + Event Name), Brand Name.
• Icons/indicators should be displayed appropriately in List View. Placement to be finalized in UI design.
  • Time — Displays “All-day”, time (e.g., 10:00 AM), or specific time ranges (e.g., 10:30 AM–1:30 PM).
    • All-day label appears for: Events or Tasks without specific start/end times.
    • Tasks and payments show their due dates
  • Type — Displays the item type (Event, Task, Meeting, Payment).
  • Title — Displays the main title. Clicking on the title redirects to the respective module/page.
    • Events: Event Type and Project Name
    • Task: Task Title and Project Name (if the task is linked to the project)
    • Meeting: Meeting Title and Project Name
    • Payment: Payment X of Y – Project Name
  • Brand — Displays the associated Brand logo and name
• Each day section is visually separated by a subtle divider for better readability.
• If no items exist for the selected week, the system displays a centered message: “No items to display.”

4.5 Calendar Filters

The Calendar Filters Drawer allows users to control the visibility and color coding of all items displayed on the calendar, including Events, Tasks, Google Calendar meetings, Calendly meetings, Team Members’ schedules, and Contractors

Filters apply to both Month View and List View, updating the display instantly as users make selections

4.5.1 Access and Layout

• The Filters Drawer opens when the user clicks the Filter icon in the Calendar module header
• The drawer slides in from the right and stays open until closed manually
• The layout includes collapsible sections for:
  • Events
  • Tasks
  • Google Calendar
  • Calendly
  • Team Members
  • Contractors
• Each section contains a list of items or subcategories with checkboxes to toggle their visibility on the calendar and color selectors (where applicable).
  • The Color Picker component supports Hex, RGB, and visual selection.
  • Color Picker must include Apply and Cancel buttons. Behavior must match Brand Setting & Brand Setup modules.
  • Color customization is available for:
    • Task statuses (To Do, In Progress, Completed)
    • Google Calendars (each connected calendar)
    • Calendly meetings
    • Team Members’ Calendar
  • Events always use colors defined in Agency Global Settings and cannot be changed here
  • Remove sub-filter hierarchy. Instead of "Payments → Upcoming" and "Payments → Paid", it should display simply: "Payments". Remove similar sub-filters for Calendly and Tasks.
• All visibility and color preferences are stored per user and persist until changed
• Changes made in filters or settings will not reflect in real time. Updates will only appear after clicking "Apply Changes.
• Initially, all events only will be selected by default in Filters. Tasks, Calendar items, and Team Member filters will NOT be selected by default – users need to select them manually. Updated filter preferences will be saved in the database. These saved preferences will apply across all modules (Events, Tasks, Calendar, Team Members).
• Filters will be selectable via checkboxes. Users can select or deselect categories as needed.
• The system remembers the user’s most recent configuration and restores it on the next login

4.5.2 Events

• The list of event types (e.g., Wedding, Engagement Photoshoot, Corporate Shoot, etc.) is fetched from the Agency’s Global Settings
• Each event type is displayed with a colored dot beside its label, representing its assigned agency-level color
• By default, all the events are visible. Users can toggle the visibility of each event type using checkboxes.
• Event colors are not editable in this drawer and always reflect agency configuration.
• If a user deselects an event type, all corresponding events are hidden from both Month and List Views.
• When no event types are configured in any Brand, this section remains visible but displays a message: “No event types available. Please configure events in Agency Settings.”

4.5.3 Tasks

• All tasks will now be displayed by default when the Tasks filter is selected.
• A checkbox option will be provided to select/deselect tasks.
• (Previous behavior of showing tasks as mandatory with changeable status is replaced.) Each status includes a checkbox to control visibility on the calendar.
• Users can customize the color for each status using the color picker
• All color and visibility preferences are saved per user.
• When a color is changed, all corresponding tasks update immediately to reflect the new color scheme.

4.5.4 Google Calendar

• This section appears only when Google Calendar integration is available
• If Google Calendar is NOT integrated:
  • The filter section displays the "Integrate Google Calendar" CTA
  • Message displayed: "Connect your Google Calendar with Pixally to sync your meetings and events"
  • Clicking "Connect" button opens Google Calendar integration popup (not full page redirect)
  • Popup appears centered on screen and it works same as done in integration:
    See: link
  • No Google Calendar filter options are shown until integration is complete

Multiple Google Calendar Accounts:

• If user has connected multiple Google calendars, filter displays list of all calendars
• Each calendar shows with its assigned color indicator
• Individual color settings available for each calendar account
• Users can toggle visibility for each calendar independently
• Format: Checkbox + Calendar Name + Color Indicator (as shown in designs)
• If Google Calendar is integrated, the system displays: Refer - Click Here
  • A list of connected calendars, each with its own checkbox and color box.
  • A Settings icon beside the section title that opens a small preferences pop-up for Google Calendar sync options
  • Two-way sync: Changes in either system are reflected in both
  • Default color assigned upon initial connection
  • If the user has multiple connected Google calendars, each appears separately with independent visibility and color settings
  • Users can toggle individual calendars' visibility on or off and update their color from the color picker

4.5.5 Calendly

• If Calendly is not integrated, in the filter, it will display a “Connect Calendly” button, and on click, it will open the Calendly integration pop-up.

After syncing Calendly to Pixally, a "Calendly" section appears in Pixally's calendar filter panel.

• Message displayed: "Connect Calendly with Pixally to sync your meetings and events"

4.5.6 Payments

• Client payments are shown on due dates
• Overdue Logic: All upcoming payments appear as Overdue until marked Paid
• Payment status updates in the Finance Module are reflected immediately in Calendar
• Partial payments should be visible in the calendar with format: Payment X of Y

4.5.7 Team Members

• The Team Members section is visible only to Agency Owners and Admins
• It lists all active team members under the agency with:
  • A checkbox to toggle each member’s calendar visibility.
  • A pencil/edit icon beside each member’s name, allowing the user to change the associated color used for that member’s entries on the calendar
• Colors selected for each team member are user-specific and persist until updated.
• When a team member’s visibility is toggled off, all their events, tasks, and meetings are hidden from the calendar
• Team Members filter section is displayed ONLY if at least one team member exists in any brand
• If no team members have been added to any brand: Team Members filter section is NOT displayed in Filters Drawer
• Section appears automatically when first team member is added to any brand

4.5.8 Team Member Google Calendar Privacy & Display Logic

Prerequisite: This section applies only when at least one team member exists in the agency. If no team members exist, the Team Members filter section is not displayed, and these privacy rules do not apply.

When Agency Owner or Admin views a team member's calendar (via Team Members filter), special privacy rules apply for Google Calendar integration.

A. Pixally-Created Calendar in Google

• When a team member connects Google Calendar, Pixally automatically creates a dedicated calendar named "Pixally — [Agency Name]" inside their Google account
• Full Visibility to Agency:
  • All events added to this Pixally-created calendar are fully visible to Agency Owner and Admin
  • Agency can see complete event details: title, time, description, participants
  • Events are interactive and clickable to view full Google Meeting Dialog
  • Two-way sync between Pixally and this specific Google calendar
• Display Behavior:
  • Events display with team member's assigned color
  • Show full event information in Month View and List View
  • Clicking event opens full Google Meeting Dialog (as described in section 4.3.3.E)

B. Personal / Other Google Calendars

• Team member's personal Google calendars (other than Pixally-created calendar) sync into Pixally as read-only data
• Agency Privacy Protection:
  • Agency Owner and Admin see these personal calendar items as "Busy" blocks only
  • No event title displayed
  • No event details visible
  • No participant information shown
  • Blocks are non-interactive - cannot click to open dialog
  • Preserves team member's personal calendar privacy
• Visual Representation:
  • Display as simple blocked time slots
  • Use neutral gray color or distinct pattern to differentiate from Pixally events
  • Label: "Busy" (no additional text)

C. Team Member's Own View

• When team member views their own calendar:
  • Pixally-created calendar: Full details visible (same as agency view)
  • Personal Google calendars: Full details visible including titles, times, descriptions
  • All their own Google events are fully interactive and clickable
  • No privacy restrictions when viewing own calendar

D. Overlap Priority Logic

• Scenario: Pixally task and "Busy" block occur at same time slot
• Display Rule: Pixally task takes display priority
  • Pixally task is shown in the calendar
  • "Busy" block is hidden/not displayed
  • Only Pixally-created items remain visible in case of overlap
  • Ensures agency work items are always visible to supervisors

E. Google Calendar Not Connected

• If team member has NOT connected Google Calendar:
  • Filter section shows message: "Connect your Google Calendar with Pixally to sync your meetings and events"
  • "Connect" button displayed
  • Clicking "Connect" button opens Google Calendar integration popup
  • Popup appears centered on screen for authentication flow
  • Integration happens at filter drawer level (not full page redirect)

4.5.9 Contractors

• The Contractors section provides users with a redirection to view contractor calendars
• Clicking the redirect icon opens the Contractors Management > Active Contractors list module in the same tab

4.6 Time Zone Logic

• Timezone information is removed from event display on the calendar UI. Backend still stores and converts timezones internally.
• The Calendar module automatically manages time zone conversions to ensure that all displayed items — including Events and Meetings (Google / Calendly) — appear accurately according to each user’s or event’s respective time zone
• All date and time values are stored in UTC in the backend and converted dynamically to the appropriate local time zone at runtime.

4.6.1 User Time Zone Configuration

• Each user can set their preferred local time zone under Global Settings.
• The selected time zone determines how all times are displayed within the Calendar module, including both Month View and List View.

4.6.2 Time Zone Impact on Events

• Events are displayed in the event’s local venue time zone, as defined during their creation.
  • Example: If an event venue is in Los Angeles (PST) and the user’s account time zone is New York (EST), the event will still appear in PST.
• This ensures consistency for project scheduling that depends on event-specific locations.
• When a project contains multiple events across different venues, each event is shown according to its own configured venue time zone

4.6.3 Time Zone Impact Meetings (Google / Calendly Integrations)

• Meetings fetched from Google Calendar or Calendly always display in the user’s local time zone (the time zone set in their user settings)
• Backend logic automatically converts meeting times from the source calendar’s time zone to the viewer’s current time zone at the time of loading
• Example:
  • A Calendly meeting scheduled at 2:00 PM GMT will appear as 9:00 AM EST for a user whose account time zone is Eastern Time
• If the user changes their account time zone, all integrated meeting times are recalculated and refreshed automatically

4.7 Project Status Indicators – Access Restriction

For Agency Global Calendar, project status indicators must be restricted to contractor-specific calendars only:

• Check Availability
• Contractor Profile
• Contractor Portal Calendar

Access Rule Examples:

• Agency Owner/Admin → Can view payment schedules in calendar.
• Other agency team members → Cannot view payment schedules.

4.8 Edge Case: Multiple Events on Same Date (Different Team Members)

• If two team members have events on the same date (e.g., 20th), and filters are applied, the date will appear separately for each team member.
• Example: Two events on 20th → Two separate 20th entries displayed.

4.9 Impacted Modules

The Calendar Module interacts with multiple other modules across the Pixally CRM ecosystem.

This section defines how the Calendar data synchronizes, displays, and reacts to updates from connected modules, ensuring real-time consistency and unified scheduling visibility.

4.9.1 Agency Portal (Dashboard & Access Control)

• The Dashboard includes a Calendar Overview Widget displaying a summarized view of upcoming events, tasks, and meetings for quick reference.
• Each entry in the widget includes the item title, date/time, and source type (Event, Task, Meeting, or Payment).
• Users can navigate directly to the Calendar Module by clicking the “View Full Calendar” link or selecting any individual item.
• The Access Control System determines user-level permissions for viewing calendar data.
  • Example: A team member without Finance access will not see payment entries in the calendar.
• All data displayed in the dashboard widget reflects real-time calendar updates, ensuring consistency between the dashboard and the full module view.

4.9.2 Projects & Events Module

• Any event created, updated, or deleted in the Projects & Events Module automatically synchronizes with the Calendar.
• The synchronization is bi-directional in display but unidirectional in modification — meaning:
  • The calendar reflects changes made in the project or event module automatically
  • Calendar items themselves are read-only and cannot be edited directly
• Event-related updates include:
  • New Event Creation: Automatically appears in the calendar under the corresponding date(s)
  • Event Updates: Rescheduled or time-adjusted events update instantly
  • Event Deletion: Removes the corresponding entry from the calendar view

4.9.3 Tasks Module

• Tasks created or updated in the Tasks Module automatically appear in the Calendar.
• Task Due Dates are shown as All-day entries on the due date
• Any status change (e.g., Pending, Completed, Overdue) is reflected in real time within the calendar
• When a task is deleted or reassigned, the calendar updates automatically to remove or update it in the corresponding user’s view

4.9.4 Payments & Finance Module

• The Calendar displays both Client Payments (incoming) to enhance financial visibility
• Each payment appears on its respective due date as defined in the invoice payment schedule
• Once a payment is marked as Paid, the corresponding entry automatically updates its status and visual indicator
• If a payment schedule is modified (due date changes), the calendar reflects these changes automatically

4.9.5 Integrations Module (Google Calendar & Calendly)

• The Calendar supports two-way synchronization with Google Calendar and real-time import of Calendly meetings
• Google Calendar Integration: Refer- Click Here
• Calendly Integration: Refer - Click Here
• Meeting times are automatically adjusted to the viewer’s local time zone (as per section 4.6 Time Zone Logic)

4.9.6 Settings Module (General Settings → Time Zone & Event Color Settings)

• The Calendar Module depends on the General Settings configuration to display data correctly based on user preferences
• Time Zone Setting:
  • Determines how events, tasks, meetings, and payments are displayed across the Calendar (see section 4.6)
  • Changing the user’s time zone recalculates all calendar entries instantly
• Event Color Settings:
  • Users can customize the default event color scheme for all events directly under General Settings → Event Color Settings
• All updates made in General Settings are applied globally across the user’s account and persist until modified again

5. Field Details & Validations

5.1 Calendar Display Fields (Month View)

Field Name

Type

Validation Rules

Month/Year Header

Text, Number

Format: "MMMM YYYY"

Current Date Highlight

Visual Indicator

Automatically applies to today's date

Date Cell

Container

Contains the current month’s days

Event Title

Text

Displays the event title

Event Time

Time Display

Format: "HH:MM AM/PM" or "All-day" (no timezone displayed)

Event Color Indicator

Visual Marker

Displays the event color code

Payment Icon

Icon

Client payment

Google Meeting Icon

Icon

Shows "G" icon for the Google meeting synced items from Google Calendar to Pixally Calendar

Calendly Meeting Icon

Icon

Shows Calendly logo for the Calendly meetings

"+X more" Indicator

Interactive Button

Displays when items are > 2 on the same day. Shows first event + '+1 more' indicator. On click displays the other events

5.2 Calendar Display Fields (List View)

Field Name

Type

Validation Rules

Week Range Selector

< > Buttons

- Must select from available weeks

- By default current week is selected

-week format: Sunday–Saturday

Date Section Header

Text

- Displays the current week range
- Format: "Day - Month DD, YYYY"

Time

Time

- Display the calendar events' time
- Format: "HH:MM AM/PM" or "All-day"

Type Label

Badge/Tag

Displays Event type, Task, Meeting, Payment

Title

Text

Displays the event title

Brand

Text, logo

Display the brand name with the logo for the associated brand

5.3 Filter Fields

Field Name

Type

Validation Rules

Event Type Filters

Multi-select Checkbox

From predefined event types

Task Status Filters

Multi-select Checkbox

Not selected by default; user must enable

Google Calendar Accounts

Multi-select Checkbox

Shows Google Calendar that is synced

Calendly Meeting Types

Calendly checkbox

Not selected by default; shows meeting types: Phone Call, Google Meeting, In Person, Others (Zoom Call categorized under Others)

Team Members Filter

Multi-select Checkbox

Shows team members

Contractors Filter

Link

On click, redirect to the contractor listing active tab

Apply Changes

Action Button

Required to apply filter changes. Non-real-time update.

Cancel

Action Button

To cancel changes

Color Picker

Modal

Must include Apply and Cancel buttons

6. Success Message Handling

Validation Scenario

Success Message

Filter applied successfully

No explicit message - Calendar updates in real-time

View toggled (Month ↔ List)

No explicit message - View changes instantly

Integration connected (Google/Calendly)

"Your [Integration Name] account has been connected successfully."

Integration disconnected

"Your [Integration Name] account has been disconnected."

Color preference saved

"Calendar color preferences have been saved successfully."

Calendar synced

"Calendar synchronized successfully."

7. Error Message Handling

Field

Validation Scenario

Error Message

Google Calendar Color

Duplicate color selected

"Please choose a different color. This color is already in use for another calendar."

Integration

Google Calendar sync failed

"Failed to sync with Google Calendar. Please try reconnecting your account."

Integration

Calendly sync failed

"Failed to sync with Calendly. Please try reconnecting your account."

Filters

Server error during filter application

"Unable to apply filters. Please try again."

General

Network timeout

"Please check your internet connection and try again."

General

Server error

"Something went wrong. Please try again later."

Empty State

No events in the selected timeframe

"No events to display."

Data Loading

Failed to load calendar data

"Failed to load calendar data. Please refresh the page."

8. Edge Cases

Scenario

Expected Behavior

More than 10 items exist on a single date

Date cell shows first 3 items + "+7 more" indicator; popup shows all 10+ items in scrollable list

User switches time zones in settings

All calendar items refresh and display in the new time zone; meetings adjust to the viewer's context

Google Calendar disconnected while viewing synced events

Synced events remain visible with "outdated" indicator; filter options hidden; "Integrate Google Calendar" option reappears; reconnection prompt appears

Calendly disconnected while viewing synced meetings

Meetings remain visible until next refresh; filter options hidden; "Integrate Calendly" option reappears; reconnection banner displayed

Google Calendar has never been integrated

The filter section shows the "Integrate Google Calendar" option with the integration icon; clicking redirects to the Integrations Module

Calendly never integrated

The filter section shows the "Integrate Calendly" option with the integration icon; clicking redirects to the Integrations Module

No contractors exist in the agency

Contractors filter section not displayed in Filters Drawer; section appears when the first contractor is added

Same meeting synced via both Google and Calendly

System deduplicates and shows a single entry with both integration badges

User applies filters, resulting in zero visible items

Calendar displays an empty grid/list with no "No results" message; filters remain visible for adjustment

Network timeout during month navigation

Loading indicator shows; after timeout displays error with retry button; previous month data remains cached

User has no team members added in any brand

Team Members filter category not displayed in Filters Drawer

All filters are unchecked simultaneously

Calendar resets to show all items (default state)

User tries to select a duplicate color for the Google Calendar account

Validation modal appears: "Please choose a different color. This color is already in use for another calendar."

User tries to select a duplicate color for a team member

Validation modal appears: "Please choose a different color. This color is already in use."

Date cell contains a mix of all item types

Items display in order: Events (by time), Tasks (all-day), Meetings (by time), Payments (all-day)

Contractor sets Do Not Book days overlapping with the scheduled event

Contractor calendar shows both striped pattern and event; no conflict warning

Session timeout during filter selection

Filter selections persist after re-authentication; the user sees previously selected filters

User searches while filters are active

Search applies only to filtered results; matching items highlighted

"+X more" pop-up opened while navigating away

Popup auto-closes on navigation; no data loss occurs

Google Calendar Preferences pop-up opens during disconnection

Popup remains open; disconnect completes; user must manually close and reconnect

List View with long event titles

Titles truncate with ellipsis after 200 characters; full title visible on hover tooltip

Multiple users viewing the same calendar data simultaneously

Each user sees the calendar in their own time zone; real-time updates via WebSocket push notifications

User rapidly clicks between months (rapid navigation)

System queues requests and cancels pending ones; only latest month data loads; prevents duplicate API calls

Integration sync in progress during manual refresh

Existing sync continues; new refresh waits until completion; loading indicator persists

Week selector in List View spans across two months

Week displays items from both months; date headers show full dates with month names

Payment marked as paid while viewing the calendar

Payment status updates in real-time; Overdue badge changes to Paid; color indicator updates

Task completed while viewing the calendar

Task status updates immediately; Completed badge appears; action icons update if applicable

The event was rescheduled to a different date while viewing

Event moves to new date cell automatically; previous date cell updates item count or removes "+X more"

The user has only one Google Calendar account connected

Filter shows single account only; no account selection dropdown needed

User connects multiple Google Calendar accounts

Each account appears separately with individual color customization; you can toggle visibility per account

User role changed from Admin to Team Member during the session

Calendar view immediately restricts to personal items only; admin-level filters disappear; team member color customization options are hidden

Lazy loading fails for historical data

Error message displays with retry option; current visible data remains intact; user can attempt reload

Color Picker modal remains open during navigation

Modal auto-closes; color selection not saved if Apply not clicked

Team Member filter accessed by Project Manager or Team Member

The Team Members filter section is not visible; only the Agency Owner and Admin can access

First contractor added to the agency

The Contractors filter section appears in the Filters Drawer with an external link icon

The last contractor was removed from the agency

Contractors filter section disappears from the Filters Drawer

Multiple events on same date (different team members)

If two team members have events on the same date and filters are applied, the date appears separately for each team member

Event dialog opened for past event

"Open in Project" button remains active; user can still view event details in Project module

Task dialog opened for completed task

"Mark as Completed" button not shown; "Open in Tasks" button remains active

Google Meeting dialog opened after meeting ended

Both "Open in Google" and "Join with Google Meet" buttons are completely hidden

Calendly video meeting dialog opened after meeting ended

"Join Meeting" button is completely hidden; other fields remain visible

User clicks "Mark as Completed" in task dialog

Task status changes to Completed; button disappears from dialog; dialog remains open showing updated status

Agency Owner views team member's personal Google calendar events

Shows as "Busy" blocks with no title/details; blocks are non-interactive (cannot click)

Pixally task and "Busy" block overlap on same time slot

Only Pixally task displays; "Busy" block is hidden; Pixally task takes priority

9. Test Cases

• Link:

10. Acceptance Criteria

Here is the full Acceptance Criteria section with all changes applied. Just copy-paste this entire block to replace your existing Section 10 in the Calendar module:

10. Acceptance Criteria

• Access & Default View: Calendar is always accessible (Owner/Admin/Project Owner/Team); opens from Tools; defaults to Month View with switch to List View; today is always highlighted; empty vs populated state determined by user/project items. Default view is always Month/Grid view, but when user selects the list view setting, then list view is shown.

• Empty State – Month: Empty grid with today highlighted; month nav and view toggle remain active.

• Empty State – List: Current week loads (Sunday–Saturday format); shows "No events to display" if none; week nav and toggles remain active.

• Displayed Items: Events, Tasks, Payments, Google events, and Calendly meetings appear in both Month and List views with distinct color codes, editable via Filters (per-user).

• Events Rules: Show only with a date; no time = All-Day; TBD not shown; multi-day spans start→end; click opens details with link to Event Details. Timezone information is removed from event display.

• Tasks Rules: Show as All-Day on due date; color reflects status (To Do/In Progress/Completed); click opens Task Details. Tags (Due Today, Overdue, Upcoming, Paid) are removed from Month View and list view.

• Payments Rules: Show on due date as "Payment X of Y – Project Name" with amount; partial payments visible in calendar with "Payment X of Y" format; click opens Finance > Transactions for that payment.

• Google & Calendly: If integrated, show meetings with icons, titles, and times; the Google item has "View on Google"; Calendly opens its pop-up; both can coexist and display. Timezone information is removed from display.

• Phone Number Display: On Calendar, show Title instead of Phone Number for phone call type meetings. Phone number will be accessible via "More Details" view.

• Month View Layout: Max two items per day cell; if more than two events occur, display the first event (based on earliest time) and show "+1 more" (or similar indicator) for additional events; items ordered by time, then creation date; "+X more" opens full day list.

• List View Behavior: Loads current Sunday–Saturday week; Today resets range; dynamic updates on create/edit/delete; items grouped by day, All-Day first, then by time. Header row (Time, Type, Title, Brand) is removed. Event details displayed directly without a header row.

• List View – Dynamic Columns: Columns should vary depending on event type. Example for Project Event: Event Date & Time (if applicable), Type, Title (Project Name + Event Name), Brand Name.

• Filters – Default Behavior: Initially, all events only will be selected by default in Filters. Tasks, Calendar items, and Team Member filters will NOT be selected by default – users need to select them manually. Updated filter preferences will be saved in the database. These saved preferences will apply across all modules (Events, Tasks, Calendar, Team Members).

• Filters – Apply Changes: Changes made in filters or settings will not reflect in real time. Updates will only appear after clicking "Apply Changes." This replaces the previous instant-update behavior.

• Filters – Access & Persistency: Right drawer with collapsible sections (Events, Tasks, Google, Calendly, Team Members, Contractors); checkbox visibility + color pickers (Hex/RGB); changes persist per user after clicking Apply Changes.

• Filters – Events: Event types from Agency Settings with fixed agency colors; user can show/hide types; message shown if no event types are configured.

• Filters – Tasks: All tasks will now be displayed by default when the Tasks filter is selected. A checkbox option will be provided to select/deselect tasks. Per-status colors customizable and applied after clicking Apply Changes.

• Filters – Google: If not integrated, show "Integrate Google Calendar" CTA; if integrated, list calendars with per-calendar visibility/color and sync prefs. Not selected by default.

• Filters – Calendly: If not integrated, show "Connect Calendly" CTA; once connected, the Calendly section appears with controls. If Calendly is integrated, show meeting types as: Phone Call, Google Meeting, In Person, Others (e.g., Zoom Call should be categorized under "Others"). Not selected by default.

• Filters – Payments: Payments shown on due dates; overdue until marked Paid; status changes reflect after clicking Apply Changes. Partial payments visible with "Payment X of Y" format.

• Filters – Sub-Filters Removed: Remove sub-filter hierarchy. Instead of "Payments → Upcoming" and "Payments → Paid", display simply: "Payments". Remove similar sub-filters for Calendly and Tasks. Flat filter structure only.

• Filters – Team Members: (Owner/Admin only) toggle each member's items and set per-member color; persists; message if none exist. Not selected by default.

• Filters – Contractors: Section redirects to the Contractors module to view contractor calendars; message if none exist.

• Color Picker: Color Picker must include Apply and Cancel buttons. Behavior must match Brand Setting & Brand Setup modules.

• Project Status Indicators – Access Restriction: For Agency Global Calendar, project status indicators must be restricted to contractor-specific calendars only (Check Availability, Contractor Profile, Contractor Portal Calendar). Agency Owner/Admin can view payment schedules in calendar. Other agency team members cannot view payment schedules.

• Multiple Events on Same Date (Different Team Members): If two team members have events on the same date and filters are applied, the date will appear separately for each team member. Example: Two events on 20th → Two separate 20th entries displayed.

• Time Zones (General): Backend stores UTC; UI converts to appropriate local time at runtime. Timezone information is removed from event display on calendar.

• User Time Zone: User's global setting drives displayed times in Month/List views.

• Event Time Zone: Events render in the event venue's time zone regardless of the user's Time Zone; each event honors its own venue Time Zone.

• Meetings Time Zone: Google/Calendly meetings render in the viewer's time zone and recalculate on Time Zone change.

• Dashboard Widget: Shows upcoming Events/Tasks/Meetings/Payments with deep links; respects access control (e.g., no Finance → no payments); mirrors calendar in real time.

• Projects & Events Sync: Create/update/delete in Projects auto-reflects in Calendar; calendar is display-only (no direct edits).

• Tasks Sync: Task due/status changes and reassignments reflect in Calendar in real time.

• Finance Sync: Payment due/paid/status/date changes auto-update the Calendar.

• Integrations Sync: Supports Google two-way and Calendly import per integration settings; meeting times honor time-zone logic.

• Settings Dependence: Time zone and Event Color Settings from General Settings drive display; changes apply globally and immediately.

Dialog/Popup behaviors function correctly:

• Clicking any calendar item (Month or List View) opens centered dialog without backdrop
• Dialog displays correct fields based on item type (Event, Task, Payment, Meeting)
• Dialog closes via X button, clicking outside, or ESC key
• Only one dialog open at a time
• Event dialog shows: Project, Event, Dates, Venue, Clients, Team with "Open in Project" button
• Task dialog shows: Title, Project, Event, Reporter, Assignee, Due Date, Description with "Open in Tasks" and "Mark as Completed" buttons
• Payment dialog shows: Project, Assignee, Invoice #, Due Date, Amount with "Open Invoice" button
• Google Meeting dialog shows: Title, Date, Time, Location, Meet link, Participants with "Open in Google" and "Join with Google Meet" buttons
• Calendly dialogs vary by type: Phone (dial number), In-Person (location + Maps), Video (join link), Other (text link)

Dialog action buttons work correctly:

• "Open in Project" redirects to Project Details → Events Tab → Event (same tab)
• "Open in Tasks" redirects to Tools → Tasks → Task Detail (same tab)
• "Mark as Completed" marks task complete and button disappears (only shown for current/future tasks)
• "Open Invoice" redirects to Finance → Invoice Details (same tab)
• "Open in Google" opens Google Calendar event (new tab)
• "Join with Google Meet" / "Join Meeting" opens meeting link (new tab)
• "Show on Google Maps" opens location in Maps (new tab)
• Post-event buttons hide completely after meeting end time

Team Member Google Calendar privacy works correctly:

• Pixally-created calendar ("Pixally — [Agency Name]") fully visible to Agency Owner/Admin
• Personal Google calendars display as "Busy" blocks to Agency with no details
• Busy blocks are non-interactive and non-clickable
• Team member sees full details of their own personal calendar events
• Overlap priority: Pixally tasks display, Busy blocks hidden
• "Connect Google Calendar" CTA shown when not connected with message and button
• Connect button opens integration popup (not page redirect)

Team Members filter visibility works correctly:

• Team Members filter section displayed ONLY if at least one team member exists
• Section not displayed when no team members exist in any brand
• Section appears automatically when first team member is added
• Section disappears when last team member is removed

Task status tags not shown in calendar:

• Due Today, Overdue, Upcoming tags removed from calendar display
• Tags removed from Task Dialog in calendar context
• Only task title and basic info shown

11. Dependencies

Module/System

Dependency Type

Impact if Unavailable

Projects Module

Data dependency

Events do not populate in the calendar, event creation fails, click-through to event details fails, and event color settings are not accessible

Tasks Module

Data dependency

Tasks do not populate in the calendar, task status updates are not reflected, click-through to task details fails, and overdue logic is not functional

Finance Module

Data dependency

Payments do not populate in the calendar, payment status updates are not reflected, click-through to payment details fails, overdue payment logic is not functional, and milestone action icons are incomplete

Settings Module (General Settings)

Configuration dependency

Time zone settings not applied, calendar displays in the default system time zone, event color preferences unavailable, user preferences not saved

Integrations Module (Google Calendar)

Integration dependency

Google Calendar sync fails, two-way sync is not functional, connected accounts are not displayed in filters, Calendar Preferences pop-up is unavailable, and color customization for accounts fails

Integrations Module (Calendly)

Integration dependency

Calendly meetings do not sync, meeting type filters are unavailable, meeting detail popups fail to load, and real-time updates are not received

Agency Portal (User Management)

Data dependency

Team Members filter is not functional, permission-based visibility fails, cannot identify user roles, and team member calendar views are incomplete

Contractor Management

Data dependency

Contractor calendar redirect fails, contractor list not accessible, Do Not Book days not displayed, contractor profile unavailable

Authentication Service

System dependency

Users cannot access the calendar, session timeout handling fails, permission validation is not functional, and filter persistence fails

Backend API

System dependency

Calendar data not loaded, all CRUD operations fail, real-time updates not received, lazy loading not functional

Database

System dependency

No data persists, filter selections not saved, calendar items not stored, complete system failure

12. References

• Figma Design Link: - Click Here

✅ Check Availability

Check Availability Module

Functional Requirement Document

BA & Ideation: Paul Sangma

Reviewed By: KG (Project Manager)

Updated Date: 25 November 2025
Status: Approved

Version 1.0

Functional Requirement Document – Check Availability Module

1. Module Overview

• Module Name: Check Availability
• Purpose: The Check Availability module enables agency users (Agency Owner, Admin, and Project Owner) to search, view, and assess contractor availability across brands, roles, events, service types, service area and venue for any given date. This module provides a comprehensive view of contractor schedules through both list and calendar interfaces, helping agencies make informed decisions when assigning contractors to projects and events.
• Business Goal:
  • Streamline the contractor assignment process by providing availability insights
  • Reduce scheduling conflicts and double-bookings
  • Enable efficient resource planning across multiple brands and projects
  • Facilitate quick contractor discovery based on location, skills, and availability
  • Improve project staffing decisions through comprehensive contractor profile information

2. User Roles & Permissions

Link - Roles and permissions - draft

3. User Flow

Click here - to view the Flowchart.

4. Functional Logic

4.1 Empty / Initial State

The Initial Empty State represents the condition when the user navigates to the Check Availability module before applying any filters or performing a search. When the user opens the Check Availability page:

• All filter fields appear in their default, unselected state.
• The Available Contractors panel displays an instructional placeholder message:
  “Use the filters above and click Search to view available contractors.”
• The Calendar/List View panel shows the default message:
  “Please select a contractor to view their availability calendar.”
• The current month’s calendar is shown, with today’s date highlighted.

4.2 Check Availability Filters

The Filter Panel enables users to search for available contractors by combining mandatory and optional filter criteria. The system uses these filters to generate precise availability results upon clicking the Search button.

Filter validations, For validation, Refer- Click Here

4.2.1 Date Filter (Mandatory)

The Date field is the only mandatory filter required to execute a search. It defines the day for which contractor availability is checked.

System Behaviour:

• Users must select a valid date before performing a search.
• The system retrieves contractors who are not booked on the selected date.
• Manual Entry: User types the date manually following the configured date format.
• Calendar Picker: User selects a date by opening the visual calendar dropdown.
• Today’s date (Current date) is highlighted with a circular border/background.
• Past dates are disabled and cannot be selected.
• Only current and future dates are selectable.
• If the user enters a past date manually, the system auto-corrects to today’s date.
• Placeholder displays the user’s configured date format (e.g., DD/MM/YYYY, MM/DD/YYYY, YYYY-MM-DD).

4.2.2 Brand Filter

Filters contractors associated with the selected brand. All brands configured by the agency appear in this dropdown.

System Behaviour:

• Clicking the dropdown shows all available brands.
• If only one brand exists, it appears as the single selectable option.
• Selecting a brand dynamically updates dependent filters:
  • Event
  • Service Type
  • Service Area
• When a brand is selected, results will only include contractors linked to that brand.
• If no brand is selected, results include contractors from all brands.

4.2.3 Event Filter

Filters contractors based on their assigned event types.

System Behaviour:

• The Event dropdown remains disabled until a brand is selected.
• Once a brand is chosen, the dropdown shows event types configured for that brand.
• Example: If Brand A has “Wedding” and “Engagement,” only these events appear.
• If the user switches to a different brand, the previously selected event is cleared.
• Search results include only contractors who are set up to work on the selected event type.

4.2.4 Service Type Filter

Filters contractors by the service they provide (e.g., Photography, Videography, Content Creation).

System Behaviour:

• The Service Type dropdown is disabled until a brand is selected.
• After selecting a brand, the dropdown shows service types set up for that brand.
• When the brand changes, the previously selected service type is cleared.
• When a service type is selected, only contractors assigned to that service type appear in the results.

4.2.5 Service Area Filter

Filters contractors by their operational or preferred working area.

System Behaviour:

• The dropdown shows service areas configured under the selected brand.
• When the brand changes, the selected service area is cleared.
• Contractors appear in results if their assigned service areas match the selected area.
• Contractors with multiple areas appear for all relevant service areas.

4.2.6 Venue Filter

Filters and sorts contractors based on how close they are to a selected venue.

System Behaviour:

• The venue filter allows users to search for a location by typing a venue name or a full address.
• As the user begins typing, the system leverages the Google Maps API to provide real-time autocomplete suggestions.
• Suggestions appear in a dropdown list based on the entered text.
• The user can select any option from the suggestions, and the selected venue/address is populated into the field.
• The Venue filter’s coordinates (lat/long) are used for:
  • Calculating the distance from the contractor’s home address to the venue.
  • Estimating the travel fee based on the calculated distance and the contractor’s travel preferences.
• If no venue is selected:
  • Distance is not calculated.
  • Contractor cards display “—” for distance and travel fees.

4.2.7 Role Filter

Filters contractors based on their assigned professional roles.

System Behaviour:

• Clicking the dropdown shows all defined roles:
  • Lead Shooter
  • Second Shooter
  • Assistant
  • Drone Operator
• Each role is displayed with its own unique icon.
• Contractors may have multiple roles assigned during onboarding.
• Selecting a role displays only contractors who have that role assigned.
• Contractors without the selected role are excluded.

4.3 Search Execution Logic

When the user clicks Search, the system retrieves and displays contractors who match all applied filter criteria. The Available Contractors list is generated using a step-by-step filtering and sorting algorithm to ensure the most relevant contractors appear first.

4.3.1 Contractor Eligibility Validation

The system evaluates each contractor against the following eligibility rules. If they fail any rule, they are excluded from the search results.

A. Contractor Status

Only contractors with Active status (Contractor Management → Active tab) are included.

The following statuses are excluded:

• Pending Invitation
• Setup Required

B. Date-Based Availability Rules

A contractor appears in the results only if they are available on the selected date. Contractors are excluded if:

• They do not work on the weekday corresponding to the selected date (defined in Contractor Settings > Working Days).
• They have marked the selected date as a “Do Not Book Day.”
• They are already assigned to another event on the same date:
  • For a different brand under the same agency
  • For a brand under another agency

C. Brand, Event, Service, Role & Service Area Matching

• Contractors must match all selected configuration filters:
  • Assigned to the selected Brand
  • Set up for the selected Event Type
  • Assigned to the selected Service Type
  • Assigned to the selected Role
  • Included in the selected Service Area
• If the user applies all or any of these filters, contractors who fail any of the criteria are excluded from the results.

4.3.2 Venue-Based Distance Logic (If Venue Filter Is Applied)

If a venue is selected:

• The system calculates travel distance using:
  • Contractor’s home address (onboarding and Contractor Settings > Location and Travel tab)
  • Google Maps venue coordinates
• Contractors are sorted from nearest to farthest.
• Contractors who exceed their maximum travel limit (if a travel fee is provided) still appear but are ranked lower.
• Travel fee is calculated for eligible contractors (based on the distance provided for travel without a fee)

If a venue is NOT selected:

• Distance is not calculated.
• Travel fee is not calculated.
• “—” is shown for the Travel Fee on contractor cards.

4.3.3 Contractor Sorting Priority

After filtering, the system displays contractors in the search results using the following hierarchical priority order:

1. Venue-Based Sorting (When Venue Is Selected)

• Primary sorting: Shortest travel distance
• Nearest contractors appear at the top of the list.

2. Average Star Rating (When Venue Is NOT Selected)

• Contractors sorted from highest to lowest average star rating.
• Contractors without ratings move to the next priority sorting rule.

3. Role-Based Sorting

If contractors have no rating or ratings tie:

• Sorting by role priority for the selected service type:
  • Lead Shooter
  • Second Shooter
  • Assistant
  • Drone Operator

4. Alphabetical Sorting (Final Fallback)

If none of the above sorting conditions apply:

• Contractors are sorted alphabetically (A → Z) by first name.

4.3.4 Final Result Rendering

• After applying all filters and sorting rules, the system displays the final ordered list of contractors in the Available Contractors section.
• Contractors that fail any eligibility or filter condition are not displayed.
• When No Contractors Match the Search Criteria
  • If the applied filters return zero eligible contractors, the system displays the message: “No contractors found. Try adjusting your filters.”

4.4 Available Contractors List and Selected Contractor Details

The Check Availability module displays contractor results in a two-panel layout. The left panel shows the Available Contractors List, while the right panel displays Selected Contractor Details. This layout allows users to quickly browse contractors and view their full availability for the selected date.

4.4.1 Available Contractors List (Left Side Panel)

The left panel displays all contractors returned from the search execution logic.

A. List Population

• The system displays contractors that match all applied search filters and sorting rules.
• Each contractor is shown as an individual list item containing:
  • Profile photo
  • Contractor name
  • Assigned role icon
  • Distance to venue (if venue is selected)
  • “Select” / “Selected” button
• For validation, refer- Click Here

B. Search by Name

• A search bar is displayed at the top of the contractor list.
• The user can type part or the full contractor name.
• The list updates dynamically to show only contractors whose names match the entered text.
• Clearing the input field restores the full filtered list.

C. Selection Indicator

• When a contractor is not selected, the button label shows “Select”.
• When selected, the button label changes to “Selected”, and the contractor card receives a visual highlight state.
• Only one contractor can be selected at a time.
• Selecting a new contractor automatically deselects the previous one.

4.4.2 Selected Contractor Details (Right Side Panel)

When the user selects a contractor from the left panel, the system displays detailed information and availability indicators in the right panel.

A. Contractor Profile Header

Displays key information, including:

• Profile photo
• Full name
• Assigned service type
• Assigned role icon
• Pay rate (e.g., $100/hr)
• Travel fee (if calculated based on venue)
• Service area
• Average star rating
• “View Profile” button to open contractor profile page

B. Calendar & List Toggle

• The user can switch between Calendar View and List View.
• The default view is Calendar View.
• The calendar displays events and tasks for the selected contractor for the chosen month.
• For details, refer- Click Here

4.4.3 Dynamic Update Behavior

A. Selecting a New Contractor

• Immediately updates the right panel with the new contractor's profile.

B. Updating Filters & Clicking Search Again

• Clears any current selection.
• Re-renders the contractor list based on new search results.
• The right panel resets to the default instructional message: “Please select a contractor to view their availability calendar.”

4.5 Check Availability from Project Details

The Check Availability feature is also accessible from within the Project Details workflow. This allows agency users to quickly evaluate contractor availability in the context of a specific event.

4.5.1 Access Path

Users can initiate the Check Availability process directly from:

Project Details → Event Details → Contractors Tab → Check Availability

4.5.2 Pre-Filled Filters from Project & Event Data

When Check Availability is launched from the Project or Event Details page, the system automatically pre-fills the following filters based on project configuration:

• Date – event date
• Brand – brand associated with the project
• Event Type – event selected within the project
• Service Area – defined event service area
• Venue – event venue (if added)

System Behaviour:

• All pre-filled fields remain editable.
• The user may modify any filter before clicking Search.
• Only applicable filters that exist in the event data will be auto-populated.

4.5.3 Handling Events Without a Confirmed Date (TBD)

If the event date is marked as TBD:

• When the user clicks Check Availability, the system displays a blocking warning message: “Please define the event date first before checking contractor availability.”
• The Check Availability module does not open until the user sets a valid date.
• Once the date is defined in the Event Details, the feature becomes fully accessible.

5. Fields & Validations

5.1 Check Availability Filter Fields

Field Name

Type

Validation Rules

Page Header

Text

Format: "Check Availability"

Date*

Date Picker with Text Input

- Mandatory field;

- Displays selected date (e.g., "August 18");

- Only current and future dates are selectable; Past dates are grayed out and non-selectable.

- If a past date is entered manually, it auto-converts to the current date

Brand

Dropdown Selector

- Optional field

- Displays brand name with avatar (e.g., "Emma Taylor");

- Fetched all from Brand Settings

- Single selection

- Auto-updates dependent filters (Events, Service Type, Service Area)

Events

Dropdown Selector

- Optional field

- Displays event types (e.g., "Wedding", "Engagement", "Rehearsal Dinner")

- Options fetched from the selected brand's event configuration

- Single selection

Service Type

Dropdown Selector

- Optional field

- Displays service categories (e.g., "Photography", "Videography", "Content Creation");

- Options fetched from the brand configuration and contractor setup

- Single selection

- Auto-refreshes when brand changes

Service Area

Dropdown Selector

- Optional field

- Options fetched from the selected brand's configuration

- Single selection

Venue

Text Input with Autocomplete

- Optional field

- Google Maps API powered autocomplete

- Displays full venue address when selected (e.g., "Hotel California, Tempest...")

- Suggestions appear as the user types.

- Single selection from suggestions

Role

Dropdown Selector

- Optional field

- Each role has a unique icon for identification

- Options fetched from contractor registrations

- Single selection

Reset Button

Action Button

Clears all filter selections instantly; Returns all fields to the default placeholder state

Search Button

Action Button

The user can search for results on the contractor's name

5.2 Available Contractors List Panel

Field Name

Type

Validation Rules

Panel Header

Text

Format: "Available Contractors"

Displayed at the top of the contractor list panel

Search Input

Text Input with Icon

- Placeholder for contractor name search;

- Filters contractor list in real-time as user types

- Case-insensitive search

Contractor Card

Interactive Container

- Displays individual contractor information

- Contains profile picture, name, distance, and select button

- Single selection

Profile Picture

Circular Image

- Displays contractor's avatar image;

- Default placeholder shown if no image is uploaded

Contractor Name & Role

Text & Role Icon

Contractor Full name displayed along with the contractor role

Distance to Location

Text Display

- Format: "X miles to location" displays the distance between the contractor's home address and the event venue

- Displays "—" when no venue is selected

- Calculated using Google Maps API coordinates

Select Button

Toggle Button

- Two states: "Select" (unselected) and "Selected" (active)

- Only one contractor can be selected at a time

Contractor List Container

Scrollable Container

- Vertical scrollable list when contractors exceed the visible area

- Displays all contractors matching filter criteria

- Updates dynamically when filters change

- Empty state message when no contractors match

Empty State Message

Text Display

- Displays when no contractors match filters

- Message: "No contractors found. Try adjusting your filters.”

5.3 Selected Contractor Profile Card Fields

Field Name

Type

Validation Rules

Card Container

Horizontal Container

- Appears above Calendar/List View when contractor is selected

- Displays all fields in a single horizontal row

- Clears when the contractor is deselected

Profile Picture

Circular Image

Displays the contractor's avatar image fetched from the Contractor portal

Contractor Name

Text with Badge

Displays the contractor’s full name

Service Type

Text Label

- Displays contractor service specialization (e.g., "Photographer", "Videographer") as assigned by the agency

- Fetched from Contractor Management

Pay Rate

Text with Label

- Format: "$[Amount]/h" (e.g., "$100/h")

- Displays the contractor pay rate for the selected event role combination for the brand

Travel Fee

Text with Label

- Format: "$[Amount]" or "—"

- Calculated based on venue distance vs contractor travel with/without fee settings

- Shows "—" when no venue is selected or within contractor travel without a fee threshold

Service Area

Text with Label

- Displays contractor's assigned service area region (e.g., "Los Angeles, ....")

- Defined by the agency during contractor setup or a later update

- Fetched from Contractor Management

Rating

Numeric with Star Icon

- Display the contractor's average rating

- Fetch from the contractor management

View Profile Button

Text Link/Button

Label: "View Profile"; Positioned on right side of card; Opens contractor's full profile in Contractor Management; Opens in new tab to preserve Check Availability context; Allows detailed review of complete contractor information

5.4 Calendar Month View Fields

• Refer - Click Here

5.5 Calendar List View Fields

• Refer - Click Here

6. Success Message Handling

Validation Scenario

Success Message

Search executed successfully

No explicit message - Available Contractors list and Calendar/List View update in real-time

Filters applied successfully

No explicit message - Results refresh instantly based on applied criteria

Contractor selected

No explicit message - Contractor Profile Card and Calendar data populate instantly

Contractor deselected

No explicit message - Profile Card clears, and Calendar returns to neutral state instantly

View toggled (Month ↔ List)

No explicit message - View changes instantly

Month navigation (Previous/Next)

No explicit message - Calendar updates to show selected month instantly

Reset filters

No explicit message - All filters clear to the default state immediately

Venue autocomplete selected

No explicit message - Venue address populates and distance calculations update instantly

Date selected from calendar picker

No explicit message - Date field populates with selected date instantly

Search input filtering

No explicit message - Contractor list filters in real-time as user types

Event/Task row clicked

No explicit message - Redirects to Project Details or Task Detail page

View Profile clicked

No explicit message - Contractor profile opens in new tab

Check Availability opened from Project Details

No explicit message - Filters pre-populate with event context automatically

7. Error Message Handling

Field

Validation Scenario

Error Message

Date

Search attempted without date selection

"Please select a date to check contractor availability."

Venue

Google Maps API connection failed

"Venue search is temporarily unavailable. Please try again sometime."

Role

No roles configured in the system

"No contractor roles available. Please configure roles in settings."

Search Results

No contractors match applied filters

"No contractors found. Try adjusting your filters."

Contractor Selection

Contractor data failed to load

"Unable to load contractor details. Please try again."

Contractor Profile Card

Pay rate not configured

Displays "—" in Pay Rate field (no error message)

Contractor Profile Card

Travel fee not applicable

Displays "—" in Travel Fee field (no error message)

Distance Calculation

Contractor location not set

Displays "—" for distance in contractor card (no error message)

Distance Calculation

Venue not selected

Displays "—" for distance in contractor card (no error message)

Network

Connection lost during search

"Connection lost. Please check your internet connection and try again."

Network

Server error during filter application

"Unable to apply filters. Please try again."

Network

Timeout during search execution

"Search timed out. Please try again."

Project Details Access

Event date is TBD

"Please define the event date first before checking contractor availability."

View Profile

Failed to open contractor profile

"Unable to open contractor profile. Please try again."

8. Edge Cases

Scenario

Expected Behavior

User manually enters a past date

System automatically converts entered past date to current date; No error message displayed; Date field shows current date after conversion

All contractors booked on the selected date

Empty state displayed: "No contractors found. Try adjusting your filters."; No contractors appear in the Available Contractors list; All booked/unavailable contractors excluded

All contractors marked no-booking days on the selected date

Empty state displayed: "No contractors found. Try adjusting your filters."; Contractors with self-marked unavailability excluded from results

Multiple contractors at the same distance from the venue

Contractors sorted by secondary criteria (Rating, then Alphabetical); Distance displayed identically for all contractors at the same location

Venue selected, but contractor location not set

Distance displays as "—" in contractor card; Contractor still appears in result,s but without distance information; Cannot calculate proximity without location data

No venue selected in filters

Distance field displays "—" for all contractor cards; Travel fee shows "—" in Profile Card; Distance sorting priority skipped; Contractors sorted by other criteria

Contractor's travel threshold exceeded by venue distance

Travel fee calculated and displayed in Profile Card; Fee based on miles beyond threshold × rate per mile; Contractor still appears in results with calculated fee

Brand filter changed after the contractor selected

Only applicable if the search button is triggered. Previously selected contractor is deselected if not associated with the new brand; Results refresh to show contractors for the new brand; Profile Card and Calendar cleared

Google Maps API unavailable

Venue field displays error: "Venue search temporarily unavailable"; Autocomplete suggestions don't appear; Distance calculations cannot be performed; User can proceed without venue

The user rapidly switches between contractors

Each selection updates Profile Card and Calendar immediately; Previous contractor's data is cleared before new data loads; No data persistence between selections; System handles rapid switching gracefully

Contractor selected, then filters reset

Contractor deselected; Profile Card cleared; Calendar returns to neutral state; Available Contractors list cleared; All filters return to default placeholders

All optional filters applied with no matches

Empty state displayed: "No contractors found. Try adjusting your filters."; AND logic means all criteria must match; User can remove filters to broaden results

Project Owner views Check Availability

Brand dropdown shows only assigned brands; Contractor results filtered to assigned brands; Calendar date clicks restricted to assigned projects only

Project Owner clicks the date for a non-assigned project

No action - date appears but is non-clickable; Only dates related to assigned projects are interactive; Maintains data privacy

Agency Owner/Admin clicks any calendar date

Opens Project or Task details in a new tab; Full access to all dates regardless of project assignment; Complete visibility across the agency

The events section is empty for the selected contractor

Section displays: "No events scheduled"; Collapsible header still shows "0 EVENTS"; Section remains functional but without content

The tasks section is empty for the selected contractor

Section displays: "No tasks assigned"; Collapsible header still shows "0 TASKS"; Section remains functional but without content

Contractor has 20+ events in the selected month

All events displayed in the scrollable Events section; Count indicator shows actual number (e.g., "23 EVENTS"); Performance optimized for large lists

Contractor has events spanning multiple days

Multi-day event may appear as a single entry or multiple date entries; Calendar highlights all dates of the multi-day event; List View shows the event with a date range

Task overdue by a significant margin

"Overdue" badge displayed in red/orange regardless of days overdue; Task remains visible in list until completed; Visual urgency indicator maintained

Check Availability opened from Project Details with TBD date

Blocking message displayed: "Please define the event date first before checking contractor availability."; User must set event date before proceeding; "Set Event Date" button provided

Network timeout during search

Loading indicator followed by error: "Search timed out. Please try again."; Previous results cleared; User can retry search

Network disconnected during contractor selection

Error: "Unable to load contractor details. Please check your connection and try again."; Selection not completed; User can retry when the connection is restored

Contractor deactivated after appearing in the results

Contractor removed from active results on next search; If currently selected, system notifies of unavailability; Profile Card cleared with message

Contractor profile updated while viewing

Profile Card may show outdated information until page refresh or contractor reselected; Real-time sync depends on system implementation

The brand was deleted while viewing its contractors

Results cleared; Error message: "Selected brand no longer available"; User prompted to select a different brand; Filter resets brand selection

User has no brand permissions (restricted Project Owner)

Empty brand dropdown with message: "No brands available for your account"; Cannot execute meaningful search without brand access; Guided to request access

Calendar month navigation beyond the contractor's booking history

Calendar shows empty month with no booking indicators; Available dates display as plain cells; No-booking days still shown if contractor has marked them

View Profile was clicked, but the contractor profile was deleted

Error: "Contractor profile not found"; New tab shows error page or redirects to Contractor Management list; Original Check Availability remains open

More than 50 contractors match filters

Scrollable list displays all matching contractors; Performance optimized for large result sets; No pagination - continuous scroll; Search input helps locate specific contractors

User switches timezone in settings while viewing

Calendar dates and event times refresh to display in the new timezone; All timestamps adjust to the viewer's context; No data loss during timezone change

The contractor has overlapping events on the same date

Both events are displayed in List View as separate rows; Calendar date shows a combined indicator; Clicking the date may show event selection or list

9. Test Cases

• Link -

10. Acceptance Criteria

• Access & Navigation: Check Availability is accessible from Tools menu and from Project Details → Event Details → Contractors Tab; opens in two-panel layout with filters on top, Available Contractors list on left, and Selected Contractor Details on right.
• Empty/Initial State: On first load, all filter fields appear unselected/default; Available Contractors panel displays "Use the filters above and click Search to view available contractors"; Calendar panel shows "Please select a contractor to view their availability calendar" with current month displayed and today's date highlighted.
• Date Filter (Mandatory): Date field is required for search execution; supports manual entry and calendar picker; today's date highlighted with circular border; past dates disabled and unselectable; manual past date entry auto-corrects to today; placeholder reflects user's configured date format (DD/MM/YYYY, MM/DD/YYYY, YYYY-MM-DD).
• Brand Filter: Dropdown displays all agency-configured brands; single brand shows as only option; selecting brand dynamically updates Event, Service Type, and Service Area dropdowns; no selection returns contractors from all brands.
• Event Filter: Disabled until brand selected; populates with event types configured for selected brand; clears when brand changes; results filtered to contractors assigned to selected event type.
• Service Type Filter: Disabled until brand selected; populates with service types for selected brand; clears on brand change; filters results to contractors assigned to selected service type.
• Service Area Filter: Populates with service areas under selected brand; clears on brand change; matches contractors by assigned service areas; contractors with multiple areas appear for all relevant selections.
• Venue Filter: Accepts venue name or full address input; Google Maps API provides real-time autocomplete suggestions; selected venue populates field and coordinates used for distance/travel fee calculations; no venue selection shows "—" for distance and travel fees on contractor cards.
• Role Filter: Dropdown displays all defined roles (Lead Shooter, Second Shooter, Assistant, Drone Operator) with unique icons; filters to contractors with selected role assigned; contractors may have multiple roles.
• Contractor Eligibility – Status: Only Active status contractors (from Contractor Management → Active tab) appear in results; Pending Invitation and Setup Required statuses excluded.
• Contractor Eligibility – Date Availability: Contractors excluded if: selected date falls on non-working weekday (per Contractor Settings > Working Days); date marked as "Do Not Book Day"; contractor already assigned to another event on same date (any brand/agency).
• Contractor Eligibility – Filter Matching: Contractors must match all applied configuration filters (Brand, Event Type, Service Type, Role, Service Area); failure on any criterion excludes contractor from results.
• Venue-Based Distance Logic: When venue selected, system calculates travel distance using contractor's home address and Google Maps coordinates; contractors sorted nearest to farthest; those exceeding max travel limit still appear but ranked lower; travel fee calculated based on distance threshold for free travel.
• Sorting Priority – With Venue: Primary sort by shortest travel distance (nearest first).
• Sorting Priority – Without Venue: Primary sort by highest to lowest average star rating; unrated contractors fall to next priority.
• Sorting Priority – Role-Based: When ratings tie or absent, sort by role priority for selected service type: Lead Shooter → Second Shooter → Assistant → Drone Operator.
• Sorting Priority – Alphabetical Fallback: When no other criteria apply, sort alphabetically (A→Z) by first name.
• No Results State: When zero contractors match criteria, display message: "No contractors found. Try adjusting your filters."
• Available Contractors List (Left Panel): Displays all contractors matching search filters and sorting rules; each card shows profile photo, name, role icon, distance to venue (if applicable), and Select/Selected button.
• Search by Name: Search bar at top of contractor list; dynamic filtering as user types; clearing input restores full filtered list.
• Selection Behavior: Unselected contractors show "Select" button; selected contractor shows "Selected" with visual highlight; only one contractor selectable at a time; new selection auto-desects previous.
• Selected Contractor Details (Right Panel): Displays profile photo, full name, service type, role icon, pay rate, travel fee (if calculated), service area, average star rating, and "View Profile" button linking to contractor profile page.
• Calendar & List Toggle: User can switch between Calendar View and List View; Calendar View is default; displays events and tasks for selected contractor for chosen month.
• Dynamic Update – New Selection: Selecting a new contractor immediately updates the right panel with the new contractor's profile and availability.
• Dynamic Update – New Search: Updating filters and clicking Search clears current selection, re-renders contractor list, and resets right panel to default instructional message.
• Access from Project Details: Check Availability accessible via Project Details → Event Details → Contractors Tab → Check Availability button.
• Pre-Filled Filters from Project: When launched from Project/Event Details, system auto-populates Date (event date), Brand, Event Type, Service Area, and Venue (if added) based on project configuration; all pre-filled fields remain editable.
• TBD Event Date Handling: If event date is TBD, clicking Check Availability displays a blocking warning: "Please define the event date first before checking contractor availability"; module does not open until valid date is set in Event Details.

11. Dependencies

Module/System

Dependency Type

Impact if Unavailable

Brand Management Module

Data dependency

Brand dropdown does not populate, brand-specific filters (Events, Service Type, Service Area) remain empty, contractor results cannot be filtered by brand, and dependent filter updates fail

Contractor Management Module

Data dependency

Contractor cards do not populate in the Available Contractors list, Profile Card data unavailable (name, pay rate, travel fee, service area, rating), contractor profile pictures missing, View Profile redirects fail

Projects & Events Module

Data dependency

Events do not populate in the calendar Month View, the List View Events section is empty, booked date indicators are missing, click-through to Project Details fails, and contractor availability determination is incomplete

Task Management Module

Data dependency

Tasks do not populate in the List View Tasks section, task status badges are unavailable, overdue indicators are missing, click-through to Task Details fails, and due date information is incomplete

Contractor Portal Module

Data dependency

No-booking days not reflected in the calendar or results, contractor self-marked unavailability ignored, striped/shaded indicators missing, availability results may include unavailable contractors

Google Maps API

External integration

Venue autocomplete suggestions unavailable, distance calculations fail, contractor cards show "—" for distance, travel fee calculations incomplete, proximity sorting disabled, error message displayed

Settings Module (General Settings)

Configuration dependency

Date format defaults to system standard, distance units not applied correctly, currency display incorrect for pay rates and travel fees, timezone settings not applied to calendar displays

Team Management & Permissions

Access dependency

Role-based access is not enforced; Project Owners may see all brands instead of being assigned only; calendar date click permissions are not restricted; unauthorized access to contractor data is possible

Calendar Module

Data dependency

Calendar view data is inconsistent with the main Calendar, event scheduling conflicts are possible, booking status is inaccurate, and date highlighting is not synchronized

12. Reference

• Figma Design Link - Click Here