Chunks — 2. Dashboard

Dashboard

#

#

#

#

#

# **Dashboard**

**Functional Requirement Document**

**BA & Ideation: Deval Chauhan**

**Reviewed By: Keval Gajjar**

**Updated Date:6 January 2025  
Status:**

**Version: 1.0**

# **Dashboard Module - FRD Summary**

**Module:** Dashboard | **FRDs:** 3 | **Test Cases:** 162 | **Date:** January 6, 2026

## **FRD #1: New Users' Dashboard (Agency Owner Role)**

First-login experience with trial period management and onboarding guidance.

**Trial Period Banner:** Color-coded by remaining days (14 days = yellow, 7 days = blue, 3 days = red, Day 0 = account lockout); "Choose Plan" button redirects to subscription page; banner removed immediately after subscription.

**Email Verification Requirement:** Account locked after 7 days without verification; modal blocks dashboard access with "Resend Verification Link" button (rate-limited to 1 per minute); 24-hour link expiration; verification unlocks account instantly.

**Setup Progress Checklist:** 6 steps (Set Up Brand, Lead Form, Booking Proposal, Link Contract, Configure Data, Connect Stripe); completable in any sequence; strikethrough styling for completed steps; progress indicator updates (e.g., "3/6 steps completed"); entire card removed after 100% completion; help videos/links per step.

**Empty States (8 Sections):**

*   New Leads ("Setup Contact Form" CTA)
*   Events ("Create New Project" CTA)
*   Calendar ("Connect Google Calendar" button + OAuth flow)
*   Activity (passive, no CTA)
*   Unread Messages ("Connect Email" CTA)
*   Overdue Payments ("Add Payment Method" CTA)
*   New Contractors ("Add Contractor" CTA)
*   Overview cards (New Leads, Overdue Tasks, Unread Messages, 2025 Revenue all display $0/0 with N/A percentages)

**Promotional Upgrade Card:** Displays "$49/m - Unlock All Features" with "View all plans" button only if no active subscription; removed after subscription.

**Google Calendar Integration:** Agency Owner only; OAuth redirect to external Google authorization; "Connect Google Calendar" button becomes "Manage Calendar Settings" after connection.

**Theme Toggle:** Light/dark mode available in top navigation; preference saved per user; applies globally across dashboard; persists across sessions.

**Default Settings:** 365-day reporting period (static global default); greeting changes by time (Good Morning 5AM-12PM, Good Afternoon 12PM-6PM, Good Evening 6PM-5AM); inspirational quote rotates on each page load.

## **FRD #2: Existing Users' Dashboard (Agency Owner Role)**

Operational command center for established agencies with full data visibility and financial analytics.

**Overview Metrics (4 Cards):** New Leads, Overdue Tasks, Unread Messages, 2025 Revenue (gross income, no deductions); percentage change indicators (↑ green, ↓ red) compare last 30 days vs previous 30 days; cards clickable (redirect to detail pages); metrics refresh on page load only (not real-time).

**Pending Contractor Agreements:** Lists contractors with unsigned service agreements showing contractor name, project name, pending status icon; "Send Reminder" button (24-hour rate limit per contractor); "Send All" button for batch reminders; success message displays count; contractors auto-removed after signing; empty state: "All contractors have signed their agreements"; max 5 displayed with "View all" link.

**Profit & Loss Section:** Visible only to subscribed Agency Owners with Stripe connected; locked state message if Stripe disconnected; time period dropdown (7 days default, 1 month, 3 months, 6 months, 1 year); displays Total Income (gross revenue), Total Expenses (all costs), Total Profit (Income - Expenses); line chart with 3 colored lines (Income = yellow, Expenses = blue, Profit = cyan); chart updates dynamically without page reload; insufficient data message if < minimum threshold.

**New Leads Table:** Columns: Lead Name, Created Date, Contact Information, Lead Source, Action ("Show More" button); max 5-6 recent leads; "View all" link opens popup modal first, then navigates to full Leads page.

**Calendar Widget:** Shows 3-5 upcoming events for current week; "Go to Calendar" link; "Manage Calendar Settings" if Google connected, "Connect Google Calendar" button if not.

**Events Section (4 Filter Tabs):**

*   **All:** Default active, shows every event
*   **Next 7 Days:** Events within 7 days from current date, sorted ascending
*   **Date Pending:** TBD status events with "Set Date" button in Action column
*   **Unassigned:** Events with ≥1 unassigned contractor role; info icon with tooltip: "This area displays events with at least one unassigned contractor role, even if others are filled but one remains open"
*   Count badges dynamic but update on page reload only

**SMS Reminder System:** Auto-sent 5 days before event to assigned contractors; asks for "yes" response to confirm attendance; "Reminder" button in Events table opens modal with two tabs:

1.  **Pending Reminders:** Contractors who haven't responded; shows name/photo/timestamp; "Select" button; search bar to filter by name; "Send Reminders" button with 24-hour rate limit; skip message if <24 hours
2.  **Accepted Reminders:** Contractors who responded "yes"; shows name/photo/timestamp; green "Accepted" badge; no action buttons

*   Contractor response validation accepts "yes" case-insensitive with extra characters

**Activity Feed:** Chronological feed of recent system activities (contract signings, project updates, event creations, lead conversions); shows icon, description, entity name, timestamp, optional action button; displays 5-7 recent activities; "View all" link for complete history; excludes financial transactions (payments, invoices, revenue).

**Unread Messages:** Table columns: Project Name, From, Subject, Date Received, Action ("View" button); "View" opens modal with full message content, sender details, link to associated project/event; max 5-7 unread messages; "View all" navigates to Email Center inbox.

**Overdue Payments (2 Tabs):**

*   **Clients Tab:** Overdue from clients to agency; columns: Client/Date/Amount/Action; "View all payments" → Finances > Billing > Transactions > Overdue; max 3-5 displayed
*   **Contractors Tab:** Overdue from agency to contractors; columns: Contractors/Date/Amount/Action; "View all payments" → Finances > Contractor Invoices > Unpaid with Overdue filter; max 3-5 displayed
*   Overdue = current date > due date; highlighted red/orange; empty state: "No overdue payments" with checkmark

**New Contractors:** Recently onboarded contractors with pending setup; columns: Name (with role), Location, Action ("Set Up User" button redirects to contractor profile); max 3-5 displayed; "View all" link to full Contractors page; removed/marked complete after setup.

**Navigation:** "Create" button dropdown (Project, Lead, Task, Contractor, Invoice); Tasks icon with count badge; all "View all" links open popup modal first; data refreshes on page load only.

## **FRD #3: Other Roles' Dashboard (Admin & Project Manager)**

Role-based filtered views maintaining data security while enabling collaborative workflows.

### Admin Role (Brand-Scoped Access):

**Visible Sections:**

*   Overview: 3 cards only (New Leads, Overdue Tasks, Unread Messages) - **NO Revenue card**
*   Pending Contractor Agreements (can send individual/batch reminders with 24-hour rate limit)
*   New Leads, Calendar, Events, Activity, Unread Messages (all scoped to assigned brands)
*   Overdue Payments (can view client and contractor overdue payments from assigned brands' projects, manage invoices/payment status)
*   New Contractors (shows all contractors from assigned brands regardless of who invited)

**Hidden Sections:**

*   Profit & Loss section (completely hidden)
*   Revenue card (excluded from Overview)
*   Trial Period Banner
*   Setup Checklist
*   Promotional Cards

**Data Filtering:** All data filtered by assigned brands (configured by Agency Owner in admin profile); Activity feed excludes financial activities (no payments, invoices, revenue updates); "View all" links navigate with brand filter applied; if admin assigned to multiple brands, data aggregated across all assigned brands.

**Access Restrictions:** Cannot see profit/loss or overall revenue metrics; can view project-level payment status but not aggregate financial performance.

### Project Manager Role (Project-Scoped Access):

**Visible Sections:**

*   Overview: 3 cards only (New Leads, Overdue Tasks, Unread Messages) - **NO Revenue card**
*   New Leads, Calendar, Events, Activity, Unread Messages (all scoped to assigned projects)
*   New Contractors (shows **only contractors personally invited by the PM**)

**Hidden Sections:**

*   Profit & Loss section (completely hidden)
*   Revenue card (excluded from Overview)
*   Pending Contractor Agreements (no access to manage agreements)
*   Overdue Payments (no access to payment data)
*   Trial Period Banner
*   Setup Checklist
*   Promotional Cards

**Data Filtering:** All data filtered by assigned projects only (configured by Owner/Admin); Activity feed excludes financial activities; "View all" links navigate with project filter applied; if PM assigned to multiple projects, data aggregated; does not show other contractors on their projects, even if assigned.

**Contractor Visibility Restriction:** Only sees contractors they personally invited; cannot view contractors invited by others, even if those contractors are assigned to PM's projects.

### Common Features (Both Roles):

**Empty States:**

*   If 0 brand/project assignments: "No data available. Contact your administrator" or "No projects assigned yet. Contact your administrator"
*   If assigned brands/projects exist but have no data: Standard empty states ("No leads yet", "No events yet")

**Permissions Enforcement:** Database queries automatically include role-based filters (brand filter for Admin, project filter for PM); attempting to access out-of-scope data results in "You do not have permission to view this data" error and redirect; PM cannot access Overdue Payments or Pending Contractor Agreements via URL manipulation.

**SMS Reminder System:** Both roles can view/send SMS reminders for events within their scope; Pending/Accepted tabs functional; 24-hour rate limit enforced.

**Data Assignment Changes:** If admin's brand assignment or PM's project assignment removed while viewing dashboard, data remains visible until page refresh; after refresh, data hidden and empty state displayed.

## **Cross-Module Integration Points**

**Subscription Module:** Trial period enforcement (14-day countdown, Day 0 lockout); subscription status determines Profit & Loss visibility; upgrade prompts and "Choose Plan" redirects; promotional card visibility tied to subscription status; account unlock after subscription on Day 0.

**User Authentication:** Email verification 7-day grace period; session management and role detection; permission checks for financial data access.

**Financial Module (Stripe):** Profit & Loss data retrieval via Stripe API; connection status detection; locked state if Stripe disconnected; financial transaction records for Income/Expenses calculation; overdue payment status from Billing and Contractor Invoices modules.

**Email Service (SMTP):** Contractor agreement reminder emails; email verification link sending; rate limiting (1 verification email per minute, 1 contractor reminder per 24 hours).

**SMS Gateway:** Auto-send 5 days before event; contractor response tracking ("yes" validation); reminder resend with 24-hour rate limit; delivery confirmation and failure handling.

**Lead Management:** New Leads count, table population, "Setup Contact Form" CTA; lead source tracking; "View all" navigation with role-based filters.

**Event/Project Management:** Events section data (All, Next 7 Days, Date Pending, Unassigned filters); Calendar widget population; event count badges; "Create New Project" CTA; "Set Date" functionality for Date Pending events; contractor role assignment tracking for Unassigned filter.

**Task Management:** Overdue Tasks count; Tasks icon badge in top navigation; task list popup.

**Contractor Management:** Pending Contractor Agreements section; New Contractors onboarding status; contractor invitation tracking (PM-specific visibility); service agreement status; "Set Up User" redirect to contractor profile; SMS reminder system for event confirmations.

**Email Center/Messaging:** Unread Messages section; message modal display; project/event link navigation from messages.

**Activity Logging:** Activity feed population (excluding financial activities for non-owners); timestamp tracking; entity association (project/client/contractor names).

**Google Calendar API:** OAuth 2.0 integration for calendar connection; token storage and management; connection status display; calendar sync for events.

**Brand Management:** Brand-scoped data filtering for Admins; brand assignment configuration; brand context in events and projects.

**Team Management:** Role-based permission enforcement; brand/project assignment tracking; access control for different user types.

**Reports Module:** 365-day reporting period default (global static setting); revenue calculation for 2025 Revenue card; financial data aggregation.

**Theme/UI Preferences:** Theme toggle (light/dark mode) saved per user; greeting time-of-day logic (server or browser timezone); inspirational quote rotation system.

## **Key Business Rules**

**Trial Period Management:** 14-day trial starts on signup date; banner color progression (yellow → blue → red); Day 0 = immediate account lockout; subscribing at any point removes trial banner permanently; lockout persists until subscription completed; trial expiration does not disconnect active session (enforced on next login/refresh).

**Email Verification:** 7-day grace period before lockout; verification modal blocks all dashboard access after 7 days; verification link expires after 24 hours; rate limit: 1 verification email per minute; account unlocks immediately upon successful verification; verification status persists across all sessions and devices.

**Setup Checklist:** Steps completable in any order (no enforced sequence); completion detection via backend API/database flags; strikethrough styling applied on completion; progress indicator updates incrementally (1/6, 2/6, etc.); entire checklist card removed when all 6 steps complete; no draft saving (exit = data loss).

**Financial Data Restrictions:** Revenue card visible only to Agency Owners; Profit & Loss section visible only to subscribed Agency Owners with Stripe connected; Admins and Project Managers have NO access to Profit & Loss or overall Revenue metrics; Admin can view project-level Overdue Payments but not aggregate financial performance; Project Manager cannot access any payment data.

**Role-Based Data Filtering:** Admin scope = assigned brands only (configured by Agency Owner); Project Manager scope = assigned projects only; Team Member scope = assigned brands, read-only; contractor visibility: Admin sees all brand contractors, PM sees only personally invited contractors; database queries include automatic role-based filters to prevent unauthorized data access.

**SMS Reminder System:** Auto-trigger: 5 days before event date; sent only to events with confirmed dates (not Date Pending); contractor response: "yes" (case-insensitive, accepts variations like "Yes!", "yes please"); rate limit: 1 SMS per contractor per 24 hours; Pending Reminders shows non-responders, Accepted Reminders shows confirmed; search functionality within Pending tab.

**Contractor Agreements:** Pending section shows unsigned agreements; "Send Reminder" rate limit: 24 hours per contractor; "Send All" skips contractors reminded <24 hours ago; contractors removed from section immediately after signing (no refresh needed on backend, visible on next page load).

**Events Filtering:** All tab = every event regardless of status; Next 7 Days = confirmed dates within current date + 7 days, sorted ascending; Date Pending = events without confirmed dates (TBD status), "Set Date" button replaces standard actions; Unassigned = events with ≥1 unassigned contractor role (even if other roles filled); count badges calculated on page load, not real-time; tooltip on Unassigned explains: "at least one unassigned contractor role, even if others are filled but one remains open".

**Overdue Payments Logic:** Overdue = current date > invoice due date; Client tab = client-to-agency overdue payments; Contractor tab = agency-to-contractor overdue invoices; highlighted red/orange for visibility; "View all payments" links include role-based filters (brand filter for Admin, project filter for PM, no filter for Owner); max 3-5 displayed per tab on dashboard.

**Data Refresh Policy:** All dashboard data refreshes on page load only (not real-time); count badges update on page reload; contractor status updates on page reload; event filter counts recalculate on page reload; percentage changes recalculated on load (last 30 days vs previous 30 days).

**Empty States:** New users see all 8 empty state sections simultaneously; each section has appropriate CTA button (Setup Contact Form, Create New Project, Connect Email, Add Payment Method, Add Contractor); promotional upgrade card displays if no subscription; if no data in assigned scope (Admin/PM), show "No data available. Contact your administrator" across all sections.

**Navigation & Interaction:** "View all" links open popup modal first, then option to navigate to full page (PM: confirm popup content); "Create" button dropdown includes Project, Lead, Task, Contractor, Invoice (options may vary by role); all CTAs redirect to appropriate module/configuration page with context preserved; Dashboard menu item highlighted in sidebar when active.

**Google Calendar Integration:** Agency Owner only (not available to Admin/PM); OAuth 2.0 flow to external Google; "Connect Google Calendar" button initiates flow; success = button changes to "Manage Calendar Settings"; failure = error message with retry option; connection status saved per user, not per brand.

**Percentage Change Calculation:** Formula: ((current period count - previous period count) / previous period count) × 100; comparison period fixed at last 30 days vs previous 30 days (not user-changeable); green up arrow (↑) for increases, red down arrow (↓) for decreases; if no historical data (<30 days old account), display "N/A" or hide percentage.

**Theme & UI Preferences:** Light/dark mode toggle in top navigation; preference saved to user profile (persists across sessions and devices); applies globally to entire dashboard and all modules; greeting changes based on server/browser time: Good Morning (5AM-12PM), Good Afternoon (12PM-6PM), Good Evening (6PM-5AM); inspirational quote randomly selected from database on each page load.

**Historical Data Preservation:** Completed projects retain original data even if contractor/service/event discontinued; activity feed maintains historical log even after deletions; overdue payment records persist until payment received; financial data in Profit & Loss based on transaction timestamps (never retroactively modified).

## **TBD Items (Requiring Future Clarification)**

**PM Notes Pending Confirmation:**

*   Popup modal content for "View all" links (what summary information displays before navigation?)
*   Email verification for invited users (Admin/PM) - do they follow same 7-day lockout rule or handled differently?
*   Google Calendar OAuth flow verification (exact redirect URLs, error handling for failed authorization, token refresh logic)
*   Task creation popup design specifications (fields, layout, submit behavior)
*   Help video links placement in setup checklist (embedded player or external link?)
*   Setup checklist final step count (Figma shows 6 steps, transcript mentions 5 - confirmed 6 steps per Figma)
*   Complete list of automated emails affected by auto-include toggle (captured: Contract sent, Proposal sent, Payment confirmation, Booking confirmation - are there others?)
*   SMS gateway provider details (Twilio, MessageBird, or other? Error codes and retry logic?)
*   Email verification success/failure email templates (subject lines, body content, sender name)
*   Dashboard data refresh frequency (currently page load only - should there be periodic auto-refresh for critical sections?)

**Designer Notes Pending Specifications:**

*   Task creation popup complete design (modal vs sidebar, fields, buttons, validation messages)
*   Empty state icon styles (consistent iconography across all 8 empty state sections)
*   Trial banner exact color codes (yellow #XXXXXX, blue #XXXXXX, red #XXXXXX)
*   Profit & Loss chart design specifications (line thickness, data point markers, axis labels, legend placement, responsive behavior)
*   Tooltip styling for Unassigned info icon (max width, arrow position, animation)
*   Modal overlay design for Reminders popup (dimensions, close button placement, tab styling)
*   Message detail modal design (width, max-height, scroll behavior, sender avatar display)
*   Loading states for all sections (skeleton screens vs spinners, animation timing)

**Total: 3 FRDs | 12 Sections Each | 162 Test Cases | All Deliverables Complete**

1\. New Users' Dashboard (Agency Owner Role)

# **Functional Requirements Document (FRD)**

# **Dashboard - New Users (Agency Owner Role)**

## **1\. Module Overview**

### Module Name

Dashboard - New Users (Agency Owner Role)

### Purpose

The Dashboard serves as the first landing page for newly registered Agency Owners, providing guided onboarding through an 8-step setup checklist while displaying essential empty state sections. The Dashboard progressively reveals operational features as the user completes setup steps, transitioning from an onboarding-focused interface to a fully functional operational command center upon completion of all setup requirements.

### Business Goals

*   Guide new Agency Owners through systematic platform setup with clear progress tracking.
*   Reduce time-to-value by providing structured onboarding with 8 essential configuration steps.
*   Minimize abandonment by breaking complex setup into manageable, sequential tasks.
*   Encourage subscription conversion through trial period awareness and feature unlock visibility.
*   Establish proper system configuration (brands, forms, contracts, agreements, questionnaires, payment processing, contractor settings) before operational use.
*   Provide email verification enforcement to maintain account security and reduce spam.
*   Display relevant empty states to preview platform capabilities without overwhelming new users.
*   Create positive first impression through intuitive interface and helpful guidance.

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

### Roles with Access

*   **Agency Owner** (Full Access - New User State)

### Granular Permissions

**Permission Type**

**Agency Owner (New User)**

View Dashboard

✅ Yes

View Trial Period Banner

✅ Yes

View Email Verification Modal

✅ Yes (if 7+ days without verification)

View Setup Progress Checklist

✅ Yes

Complete Setup Steps

✅ Yes

View Overview Metrics (Empty State)

✅ Yes

View New Leads Section (Empty State)

✅ Yes

View Events Section (Empty State)

✅ Yes

View New Contractors Section (Empty State)

✅ Yes

View Unread Messages Section (Empty State)

✅ Yes

View Promotional Upgrade Card

✅ Yes (if not subscribed)

View Pending Contractor Agreements

❌ No (hidden until setup complete)

View Pending Counter Sign

❌ No (hidden until setup complete)

View Profit & Loss Chart

❌ No (hidden until setup complete)

View Calendar Widget

❌ No (hidden until setup complete)

View Overdue Payments

❌ No (hidden until setup complete)

View Activity Feed

❌ No (hidden until setup complete)

Toggle Theme Preference

✅ Yes

Access Google Calendar Integration

❌ No (available after setup complete)

Access Calendly Integration

❌ No (available after setup complete)

## **3\. User Flow**

3.1 **The user completes the signup process** and is redirected to the Dashboard page.

3.2 **The system loads the Dashboard** and displays a color-coded trial period banner at the top based on the remaining trial days (yellow for 14 days, blue for 7 days, red for 3 days).

3.3 **The system checks if the user's email is verified.**

3.4 If the email is not verified and more than 7 days have passed since signup, **the system displays an "Email Verification Required" modal overlay** blocking access to the Dashboard.

3.5 If the email is not verified but less than 7 days have passed, **the system allows Dashboard access** without restriction.

3.6 **The user views the Dashboard content** which includes a greeting message ("Good Morning, \[User Name\]"), an inspirational quote section, and the main setup progress area.

3.7 **The system displays the "Let's get you all set up" checklist card** showing 0/8 steps completed with a progress bar indicator.

3.8 **The user views eight setup steps** listed with checkboxes (all unchecked): Set Up Your Brand, Set Up Lead Form, Set Up Contract, Set Up Booking Proposal, Set Up Service Agreement, Set Up Post Event Questionnaires, Connect to Stripe, Configure Data.

3.9 **Each setup step displays a small help icon or embedded video link** (if available) provided by the design team.

3.10 **The user clicks on any setup step** in any sequence (steps can be completed in any order).

3.11 **The system redirects the user** to the respective configuration page (Brand Settings, Lead Form Builder, Contract Setup, Booking Proposal Setup, Service Agreement Setup, Questionnaire Builder, Stripe Connection, or General Settings).

3.12 After the user completes a setup step in the respective module, **the system marks that step as completed** (strikethrough text) in the Dashboard checklist.

3.13 **The system updates the progress bar and completion indicator** (e.g., "1/8 steps completed").

3.14 **The user views visible empty state sections** on the Dashboard including Overview Metrics (4 cards showing 0s), New Leads, Events, New Contractors, and Unread Messages.

3.15 **Each visible empty state section displays a placeholder message** (e.g., "You have no active leads"), an icon, and a call-to-action button where applicable (e.g., "Setup Contact Form", "Create New Project").

3.16 **The following sections are HIDDEN** and not visible to new users until setup is complete: Pending Contractor Agreements, Pending Counter Sign, Profit & Loss, Calendar widget, Overdue Payments, Activity feed.

3.17 If the user has not subscribed, **the system displays a promotional upgrade card** (e.g., "$49/m - Unlock All Features") with a "View all plans" button in the designated location per Figma design.

3.18 **The user clicks the "Choose Plan" button** in the trial period banner or "View all plans" button in the promotional card.

3.19 **The system redirects the user to the Subscription Plans page.**

3.20 **The user returns to the Dashboard** after viewing subscription options.

3.21 **The user progresses through setup steps,** completing them one by one in any order.

3.22 **The user clicks "Configure Data"** (the 8th and final setup step).

3.23 **The system redirects the user** to Settings → General tab.

3.24 **The user views the General Settings page** with two required fields for contractor travel settings: "Contractors will be paid a travel fee starting at" (dropdown) and "Rate per mile" (manual input).

3.25 **The user selects a distance** from the "Contractors will be paid a travel fee starting at" dropdown (options: 25, 50, 75, 100, 125, 150, 175, 200, 225, 250 miles).

3.26 **The user enters a rate** in the "Rate per mile" field (numeric value between $1 and $1000).

3.27 **The user clicks "Save Changes"** to save the contractor travel settings.

3.28 **The system validates the input,** saves the settings, and marks "Configure Data" as completed.

3.29 **The user returns to the Dashboard.**

3.30 **The system detects all 8 setup steps are complete** (progress bar shows "8/8 steps completed").

3.31 **The system removes the "Let's get you all set up" checklist card** from the Dashboard.

3.32 **The system reveals previously hidden sections:** Pending Contractor Agreements (if any pending), Pending Counter Sign (if any pending), Profit & Loss (if Stripe connected and subscribed), Calendar widget (with "Connect Google Calendar" and "Connect Calendly" buttons), Overdue Payments (empty state initially), Activity feed (empty state initially).

3.33 **The user views the now fully operational Dashboard** with all sections visible.

3.34 **The promotional card remains visible** if the user has not subscribed (even after setup complete).

3.35 **The user can toggle between light and dark mode** using the theme selector in the top navigation area.

3.36 **The system applies the selected theme preference** globally across the Dashboard and saves the preference for future sessions.

3.37 If the email verification modal is displayed, **the user clicks the "Resend Verification Link" button.**

3.38 **The system sends a new verification email** to the registered email address and displays a success toast message.

3.39 **The user checks their email, clicks the verification link,** and the system marks the account as verified.

3.40 Upon the next login, **the system no longer displays the email verification modal** and grants full Dashboard access.

3.41 If the trial period expires (Day 0) and the user has not subscribed, **the system locks the account** and displays a subscription required message on the Dashboard.

3.42 **The user navigates away from the Dashboard** using the left sidebar menu to access other modules.

## **4\. Functional Logic**

### 4.1 Trial Period Banner

*   The trial period banner is displayed prominently at the top of the Dashboard for all new users during their trial period.
*   The banner color changes based on the number of remaining trial days to create urgency:
    *   **14 days remaining:** Yellow background
    *   **7 days remaining:** Blue background
    *   **3 days or fewer remaining:** Red background
    *   **Day 0 (trial expired):** Red background with "Your trial has expired" message
*   The banner text displays: "You have X day(s) left in trial period, choose a plan to unlock all features."
*   A "Choose Plan" button is prominently displayed within the banner.
*   Clicking the "Choose Plan" button redirects the user to the Subscription Plans page.
*   The trial period countdown is calculated based on the signup date stored in the database (signup date + 14 days = expiration).
*   The banner is removed immediately after the user successfully subscribes to a paid plan.
*   If the user subscribes on Day 1 (last day of trial), the banner is removed instantly upon successful subscription, and the account is not locked on Day 0.
*   On Day 0 (trial expiration), if the user has not subscribed, the account is locked, and the user can only access the Subscription page.

### 4.2 Email Verification Requirement

*   All new agency owners must verify their email address within 7 days of signup.
*   If the user has not verified their email and 7 days have passed since signup, the system displays an "Email Verification Required" modal overlay when the user logs in.
*   The modal blocks all access to the Dashboard until the email is verified.
*   The modal message states: "Your account has been locked because the email verification was not completed within 7 days. To unlock your account, click the button below to resend a verification email."
*   A "Resend Verification Link" button is displayed prominently in the modal.
*   Clicking "Resend Verification Link" sends a new verification email to the user's registered email address.
*   The system displays a success toast message: "Verification email sent successfully. Please check your inbox and spam folder."
*   The system enforces a rate limit of 1 verification email per minute to prevent spam.
*   The verification email contains a unique link that expires after 24 hours.
*   When the user clicks the verification link in the email, the system marks the email as verified in the database.
*   Upon successful verification, the user can log in without seeing the modal, and full Dashboard access is granted.
*   If the user has verified their email OR if less than 7 days have passed since signup, the modal is not displayed, and Dashboard access is unrestricted.
*   **PM Note:** Clarify email verification requirements for invited users (Admins/Project Managers) - do they follow the same 7-day lockout rule?

### 4.3 Setup Progress Checklist

#### **4.3.1 Checklist Display**

*   The "Let's get you all set up" card is displayed prominently on the Dashboard for all new users who have not completed all 8 setup steps.
*   The card includes a title, a progress bar, a completion indicator (e.g., "0/8 steps completed"), and a list of 8 setup steps.
*   The progress bar visually represents the completion percentage (e.g., 0% when no steps complete, 50% when 4/8 complete, 100% when all complete).
*   Each setup step is displayed as a list item with a checkbox (unchecked by default), the step name, and an optional help icon or video link.
*   The 8 setup steps are:
    1.  Set Up Your Brand
    2.  Set Up Lead Form
    3.  Set Up Contract
    4.  Set Up Booking Proposal
    5.  Set Up Service Agreement
    6.  Set Up Post Event Questionnaires
    7.  Connect to Stripe
    8.  Configure Data

#### **4.3.2 Step Completion Logic**

*   Setup steps can be completed in any order; there is no enforced sequence.
*   Each step is clickable and redirects the user to the appropriate configuration page or module.
*   Completion of each step is detected automatically by the system based on backend API/database flags set when the user saves their configuration in the respective module.
*   When a step is completed, the system marks it with a strikethrough text style and checks the checkbox.
*   The progress bar and completion indicator update incrementally (e.g., "1/8 steps completed", "2/8 steps completed", etc.).
*   The entire "Let's get you all set up" card is removed from the Dashboard once all 8 steps are completed (100% progress).

#### **4.3.3 Setup Step Details**

**Step 1: Set Up Your Brand**

*   Redirects to: Settings → Brands → Create New Brand wizard
*   Completion criteria: User completes all 5 steps of the brand setup wizard and saves the brand
*   Required actions: Fill brand name, upload logo, select brand color, upload cover photo, add service areas

**Step 2: Set Up Lead Form**

*   Redirects to: Lead Form Builder
*   Completion criteria: User creates and saves at least one lead form
*   Required actions: Configure form fields, set form settings, activate form

**Step 3: Set Up Contract**

*   Redirects to: Templates → Contracts or Contract Management
*   Completion criteria: User creates or customizes at least one contract template(client)
*   Required actions: Define contract terms, add clauses, save template

**Step 4: Set Up Booking Proposal**

*   Redirects to: Proposal Management or Booking Proposal Builder
*   Completion criteria: User creates at least one booking proposal template
*   Required actions: Configure proposal sections, add pricing, save template

**Step 5: Set Up Service Agreement**

*   Redirects to: Service Agreement Management or Contract Templates
*   Completion criteria: User creates at least one service agreement template for contractors
*   Required actions: Define agreement terms, add contractor clauses, save template

**Step 6: Set Up Post Event Questionnaires**

*   Redirects to: Questionnaire Builder or Post-Event Forms
*   Completion criteria: User creates at least one post-event questionnaire template
*   Required actions: Add questionnaire questions, configure settings, save template

**Step 7: Connect to Stripe**

*   Redirects to: Payment Settings → Stripe Integration
*   Completion criteria: User completes Stripe OAuth connection successfully
*   Required actions: Authorize Stripe account, confirm connection

**Step 8: Configure Data**

*   Redirects to: Settings → General tab
*   Completion criteria: User fills and saves contractor travel settings (travel fee starting distance + rate per mile)
*   Required actions: Select travel fee starting distance from dropdown, enter rate per mile, click "Save Changes"
*   **NEW STEP:** This is the final step that unlocks all hidden Dashboard sections upon completion

#### **4.3.4 Configure Data Step - Detailed Logic**

*   When the user clicks "Configure Data" in the setup checklist, the system redirects to Settings → General tab.
*   The General Settings page displays two contractor travel setting fields:
    *   **Contractors will be paid a travel fee starting at:** Dropdown with options: 25, 50, 75, 100, 125, 150, 175, 200, 225, 250 miles (increments of 25)
    *   **Rate per mile:** Manual text input field for entering the rate (numeric)
*   All other fields on the General Settings tab (Timezone, Country, Measurement System, Currency) are pre-filled with default values and do not require user input for setup completion.
*   **Validation Rules:**
    *   Travel fee starting distance: Required field; must select one option from dropdown; no default value selected
    *   Rate per mile: Required field; must be a numeric value between $1 and $1000; accepts decimal values (e.g., 20.50); no default value
*   The user must fill both fields to save successfully.
*   If the user attempts to save without filling both fields, the system displays validation errors: "Please select travel fee starting distance" and/or "Please enter rate per mile."
*   Upon successful save, the system marks "Configure Data" as completed and updates the Dashboard setup checklist progress to 8/8.
*   **PM Note:** Confirm if any other fields on the General Settings tab must be filled for "Configure Data" completion, or if the two travel fee fields are sufficient.

#### **4.3.5 Help Resources**

*   Each setup step may display a small help icon or embedded video link next to the step name.
*   Clicking the help icon or video link opens a tutorial video in a modal player or redirects to a help article in a new tab.
*   **Designer Note:** Confirm placement and design of help video links in setup checklist (embedded player vs external link).

### 4.4 Conditional Section Visibility

#### **4.4.1 Sections VISIBLE Before Setup Complete (0-7 steps)**

The following sections are visible to new users even before they complete all 8 setup steps:

1.  **Trial Period Banner:** Visible (if trial active and not subscribed)
2.  **Greeting and Quote:** Visible
3.  **Setup Progress Checklist:** Visible
4.  **Overview Metrics (4 Cards):** Visible with all values showing 0 and percentage changes showing "N/A"
    *   New Leads: 0 (with 0% or N/A)
    *   Overdue Tasks: 0 (with 0% or N/A)
    *   Unread Messages: 0 (with 0% or N/A)
    *   2025 Revenue: $0 (with 0% or N/A)
5.  **New Leads Table:** Visible with empty state message: "You have no active leads" and "Setup Contact Form" CTA button
6.  **Events Section:** Visible with empty state message and 4 filter tabs (All, Next 7 Days, Date Pending, Unassigned - all showing 0 counts) and "Create New Project" CTA button
7.  **New Contractors Section:** Visible with empty state message: "You have no contractors yet" and "Add Contractor" CTA button
8.  **Unread Messages Section:** Visible with empty state message: "You have no messages yet" and "Connect Email" CTA button
9.  **Promotional Upgrade Card:** Visible (if not subscribed) with "$49/m - Unlock All Features" and "View all plans" button

#### **4.4.2 Sections HIDDEN Before Setup Complete**

The following sections are completely hidden and do not appear on the Dashboard until all 8 setup steps are completed:

1.  **Pending Contractor Agreements:** Hidden
2.  **Pending Counter Sign:** Hidden
3.  **Profit & Loss:** Hidden
4.  **Calendar Widget:** Hidden (including "Connect Google Calendar" and "Connect Calendly" buttons)
5.  **Overdue Payments:** Hidden
6.  **Activity Feed:** Hidden

#### **4.4.3 Sections REVEALED After Setup Complete (8/8 steps)**

Once the user completes all 8 setup steps and the "Let's get you all set up" card is removed, the following sections become visible:

1.  **Pending Contractor Agreements:** Visible (if any contractors have pending service agreements); if none, empty state: "All contractors have signed their agreements"
2.  **Pending Counter Sign:** Visible (if any service agreements await counter-signature); if none, empty state: "No agreements awaiting your signature"
3.  **Profit & Loss:** Visible if user has subscribed AND connected Stripe; if Stripe not connected, displays locked state: "Connect Stripe to view Profit & Loss analytics"
4.  **Calendar Widget:** Visible with:
    *   Upcoming events list (3-5 events) or empty state: "No upcoming events this week"
    *   "Go to Calendar" link
    *   **"Connect Google Calendar" button** (initiates Google OAuth)
    *   **"Connect Calendly" button** (initiates Calendly OAuth)
5.  **Overdue Payments:** Visible with Clients and Contractors tabs; initially empty state: "No overdue payments"
6.  **Activity Feed:** Visible showing recent activities (Proposals, Contracts, Invoices, Payments, Questionnaires); initially empty state: "No recent activity. Client interactions will appear here"

#### **4.4.4 Post-Setup Checklist Removal**

*   Once all 8 steps are completed, the "Let's get you all set up" card is permanently removed from the Dashboard.
*   The setup checklist never reappears even if the user unconfigures certain settings (e.g., disconnects Stripe).
*   The promotional upgrade card **remains visible** even after setup completion if the user has not subscribed.
*   The trial period banner **remains visible** even after setup completion if the user has not subscribed and is still within the trial period.

### 4.5 Overview Section - Empty State Metrics

*   The Overview section displays four metric cards for new users, all showing zero values initially:
    1.  **New Leads:** 0 with percentage change "N/A" or "0%" (no historical data)
    2.  **Overdue Tasks:** 0 with percentage change "N/A"
    3.  **Unread Messages:** 0 with percentage change "N/A"
    4.  **2025 Revenue:** $0 (displayed as "0" with currency symbol) with percentage change "N/A"
*   Each card displays an icon representing the metric category.
*   Percentage change indicators are either hidden or display "N/A" for new users with no historical data.
*   The cards are clickable but redirect to empty pages or modules with empty states (e.g., clicking "New Leads" shows empty Leads page).

### 4.6 Empty State Sections

#### **4.6.1 New Leads Empty State**

*   Message: "You have no active leads"
*   Icon: Clipboard or document icon
*   CTA Button: "Setup Contact Form"
*   "View all" link: Present but redirects to empty Leads page
*   Clicking "Setup Contact Form" redirects to Lead Form Builder

#### **4.6.2 Events Section Empty State**

*   Filter tabs displayed: All (0), Next 7 Days (0), Date Pending (0), Unassigned (0)
*   Message: "You have no events yet"
*   Icon: Calendar icon
*   CTA Button: "Create New Project"
*   "View all" link: Present but redirects to empty Events/Projects page
*   Clicking "Create New Project" redirects to Project Creation page

#### **4.6.3 New Contractors Empty State**

*   Message: "You have no contractors yet"
*   Icon: User or team icon
*   CTA Button: "Add Contractor"
*   "View all" link: Present but redirects to empty Contractors page
*   Clicking "Add Contractor" redirects to Contractor Management → Add Contractor page

#### **4.6.4 Unread Messages Empty State**

*   Message: "You have no messages yet"
*   Icon: Envelope or message icon
*   CTA Button: "Connect Email"
*   "View all" link: Present but redirects to empty Email Center
*   Clicking "Connect Email" may redirect to Email Integration settings or Email Center setup

### 4.7 Promotional Upgrade Card

*   Displays for users who have not subscribed to a paid plan (during trial or after setup).
*   Content: "$49/m - Unlock All Features" with rocket icon and feature highlights
*   Button: "View all plans"
*   Clicking "View all plans" redirects to Subscription Plans page
*   The card is displayed in a designated location per Figma design (typically in a side column or bottom area)
*   **The promotional card remains visible even after setup completion** if the user has not subscribed
*   The card is only removed after the user successfully subscribes to a paid plan

### 4.8 Google Calendar Integration (Post-Setup Only)

*   Google Calendar integration is NOT available until all 8 setup steps are complete.
*   After setup completion, the Calendar widget appears with a "Connect Google Calendar" button.
*   This functionality is identical to the Google Calendar integration documented in FRD #2 for existing users.
*   The "Connect Google Calendar" button initiates an OAuth 2.0 flow to external Google authorization.
*   Upon successful connection, the button changes to "Manage Calendar Settings."

### 4.9 Calendly Integration (NEW - Post-Setup Only)

*   Calendly integration is NOT available until all 8 setup steps are complete.
*   After setup completion, the Calendar widget appears with a "Connect Calendly" button (displayed alongside "Connect Google Calendar").
*   Clicking "Connect Calendly" initiates an OAuth flow to Calendly's authorization page.
*   The user grants permissions to Pixally to access their Calendly account.
*   Upon successful connection, the button changes to "Manage Calendly Settings" or is replaced with a connection status indicator.
*   Calendly events may be synced to the Calendar widget and displayed alongside Google Calendar events.
*   **PM Note:** Confirm exact Calendly OAuth flow, redirect URLs, and post-connection functionality.

### 4.10 Theme Preference

*   Users can toggle between light and dark mode using the theme selector in the top navigation area.
*   The theme preference is saved to the user profile and persists across sessions and devices.
*   The theme applies globally to the entire Dashboard and all other modules.
*   The system remembers the user's theme choice and applies it automatically on subsequent logins.

### 4.11 Navigation and Interaction

*   The Dashboard includes a persistent left sidebar menu with navigation links to all major modules.
*   The "Dashboard" menu item is highlighted when the user is viewing the Dashboard.
*   The top navigation bar includes global actions: search, notifications, Tasks icon with count badge, user profile dropdown, theme toggle, and "Create" button.
*   The "Create" button opens a dropdown menu with options to create new records (Project, Lead, Task, Contractor, Invoice, etc.).
*   All "View all" links in Dashboard section headers first open a popup modal with summary information; from the popup, the user can navigate to the full detail page.
*   **PM Note:** Confirm the exact content and structure of the popup modals for "View all" links.

### 4.12 Greeting and Inspirational Quote

*   The Dashboard displays a personalized greeting: "Good Morning, \[User First Name\]", "Good Afternoon, \[User First Name\]", or "Good Evening, \[User First Name\]" based on the current time.
*   Time-of-day logic:
    *   Good Morning: 5:00 AM - 11:59 AM
    *   Good Afternoon: 12:00 PM - 5:59 PM
    *   Good Evening: 6:00 PM - 4:59 AM
*   The system uses the server time or the user's browser time zone to determine the greeting.
*   Below the greeting, an inspirational quote is displayed, randomly selected from a predefined list stored in the database.
*   The quote changes on each Dashboard page load (refresh displays a new quote).
*   Quote format: "\[Quote text\]" — \[Author Name\]

### 4.13 Default Settings

*   The Overview section's reporting period is set to a global default of 365 days (static, not user-changeable).
*   All date-related sections default to the current date as the starting point.
*   The system uses UTC or the user's local timezone for all date/time calculations.

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

**Field Name**

**Field Type**

**Validation Rules**

New Leads Count

Calculated Number

System-calculated; displays 0 for new users; display-only.

Overdue Tasks Count

Calculated Number

System-calculated; displays 0 for new users; display-only.

Unread Messages Count

Calculated Number

System-calculated; displays 0 for new users; display-only.

2025 Revenue

Calculated Currency

System-calculated; displays $0 for new users; display-only.

Percentage Change

Calculated Percentage

Displays "N/A" or hidden for new users with no historical data; display-only.

Setup Progress

Calculated Percentage

System-calculated based on completed steps (0-100%); display-only.

Contractors Travel Fee Starting At

Dropdown

Required; options: 25, 50, 75, 100, 125, 150, 175, 200, 225, 250 miles; no default selected.

Rate Per Mile

Number Input

Required; numeric value; range: $1 - $1000; allows decimals (e.g., 20.50); no default value.

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

**Success Scenario**

**Success Message**

**Trigger Condition**

**Post-Success Action**

Email Verification Sent

"Verification email sent successfully. Please check your inbox and spam folder."

User clicks "Resend Verification Link"; email sent successfully.

Modal remains open; user must check email to verify; rate limit: 1 email per minute.

Email Verified

"Email verified successfully. Welcome to Pixally!"

User clicks verification link in email; verification successful.

Email verification modal never appears on future logins; full Dashboard access granted.

Setup Step Completed

No explicit message per step (implicit success)

User completes configuration in a module and saves; step marked complete.

Checkbox checked; step text strikethrough; progress bar updates; completion indicator updates (e.g., "3/8 steps completed").

All Setup Steps Completed

"Setup complete! Your dashboard is now fully operational." (Optional)

User completes the 8th step (Configure Data) and saves; all steps now complete.

Setup checklist card removed; previously hidden sections revealed; Dashboard transitions to operational state.

Configure Data Saved

"Contractor travel settings saved successfully."

User fills travel fee distance and rate per mile; clicks "Save Changes" in General Settings.

Settings saved to database; "Configure Data" step marked complete; user can return to Dashboard.

Theme Changed

No explicit message (implicit success)

User toggles theme preference; theme applied successfully.

Theme updates immediately across Dashboard; preference saved to user profile.

Subscription Completed

"Welcome to \[Plan Name\]! Your account is now upgraded."

User completes subscription payment.

Trial banner removed permanently; promotional card removed; full features unlocked.

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

**Error Scenario**

**Error Message**

**Trigger Condition**

**Required User Action**

**System Response**

Email Verification Send Failed

"Failed to send verification email. Please try again or contact support if the issue persists."

System fails to send verification email due to SMTP error or invalid email address.

User should retry clicking "Resend Verification Link"; if issue persists, contact support.

Display error toast; "Resend Verification Link" button remains available for retry; error logged to backend.

Email Verification Rate Limit Exceeded

"Please wait 1 minute before requesting another verification email."

User clicks "Resend Verification Link" multiple times within 1 minute.

User should wait 60 seconds before retrying.

Display warning message; disable "Resend Verification Link" button for 60 seconds; countdown timer optional.

Setup Step Save Failed

"Failed to save \[Module Name\]. Please try again or contact support."

User attempts to save configuration in a setup module; save fails due to database error or validation issue.

User should retry saving; verify all required fields filled; contact support if error persists.

Display error message in the module; user remains on configuration page; setup step not marked complete; error logged.

Configure Data Validation Error (Travel Fee Empty)

"Please select travel fee starting distance."

User attempts to save Configure Data without selecting travel fee distance from dropdown.

User must select a value from the dropdown before saving.

Display validation error below the travel fee field; "Save Changes" button does not submit; focus on travel fee field.

Configure Data Validation Error (Rate Per Mile Empty)

"Please enter rate per mile."

User attempts to save Configure Data without entering rate per mile.

User must enter a numeric value in the rate per mile field.

Display validation error below the rate field; "Save Changes" button does not submit; focus on rate field.

Configure Data Validation Error (Rate Out of Range)

"Rate per mile must be between $1 and $1000."

User enters a rate per mile value less than $1 or greater than $1000.

User must enter a value within the valid range ($1-$1000).

Display validation error below the rate field; "Save Changes" button does not submit; focus on rate field.

Configure Data Validation Error (Rate Invalid Format)

"Please enter a valid numeric value for rate per mile."

User enters non-numeric characters in the rate per mile field.

User must enter only numbers (decimals allowed, e.g., 20.50).

Display validation error below the rate field; "Save Changes" button does not submit; focus on rate field.

Dashboard Load Failed

"Unable to load Dashboard data. Please check your internet connection and try again."

Dashboard fails to load due to network connectivity issues or server downtime.

User should check internet connection and refresh page; contact support if server is down.

Display error message in place of Dashboard content; provide "Retry" button to reload data; error logged.

Account Locked (Trial Expired)

"Your trial has expired. Please choose a subscription plan to continue using Pixally."

User attempts to access Dashboard on Day 0 (trial expired) without subscribing.

User must click "Choose Plan" or "Subscribe Now" to access Subscription Plans page.

Dashboard content blocked; lockout message displayed prominently; "Choose Plan" button redirects to subscription page; account remains locked until subscription.

Expired Verification Link

"This verification link has expired. Please request a new verification email."

User clicks verification link from email sent more than 24 hours ago.

User must return to Dashboard and click "Resend Verification Link" to get a new email.

Error page displays message; link to return to Dashboard provided; verification not completed.

## **8\. Edge Cases**

**Edge Case**

**Expected Behavior**

User closes browser before initial Dashboard load completes

On next login, Dashboard loads normally; trial period banner displays with correct days remaining; setup checklist shows 0 steps completed; trial countdown continues from signup date.

User completes some setup steps, logs out, then logs in again

Dashboard loads with setup checklist showing previously completed steps with strikethrough; progress bar reflects current completion percentage; user can continue setup from where they left off.

User completes all 8 steps but doesn't subscribe

Setup checklist card removed; previously hidden sections revealed; promotional card REMAINS visible; trial banner remains visible if trial active; all features accessible during trial; account locks on Day 0 if no subscription.

User subscribes before completing setup

Trial banner removed immediately; promotional card removed; setup checklist remains visible until all 8 steps complete; hidden sections remain hidden until setup complete; user has unlimited time to complete setup.

User subscribes on Day 1 (last day of trial)

Trial banner removed immediately after subscription; account is NOT locked on Day 0; user has uninterrupted access; setup can be completed at any time.

User completes "Configure Data" but doesn't save

"Configure Data" step remains incomplete; setup progress stays at 7/8; hidden sections remain hidden; user must return to General Settings and save to complete setup.

User completes setup step, system marks it complete, but user later unconfigures that setting

Step remains marked as complete in checklist; setup checklist card already removed (if all 8 were complete); system does not revert setup completion status; user can reconfigure at any time without affecting Dashboard state.

User clicks multiple setup steps rapidly

System allows multiple navigation actions; multiple tabs/windows may open for each configuration page; user can complete steps independently; Dashboard updates correctly for all completed steps on return.

User completes setup on mobile device, logs in on desktop

Setup completion status persists across devices; Dashboard on desktop shows operational state with hidden sections revealed; promotional card behavior consistent (removed if subscribed, visible if not subscribed).

Email verification on exactly Day 7 (last moment before lockout)

System accepts verification on Day 7; account is not locked; email verification modal does not appear on next login; user has full Dashboard access.

User verifies email after 7 days have passed (account locked)

Verification link still works; email marked as verified; on next login, account is unlocked; email verification modal does not appear; full Dashboard access restored.

Configure Data saved successfully but user navigates away immediately

"Configure Data" step marked complete in database; on next Dashboard load, progress shows 8/8; setup checklist card removed; hidden sections revealed.

User refreshes Dashboard immediately after completing final setup step

Dashboard reloads; system detects 8/8 steps complete; setup checklist card removed; hidden sections immediately visible; no manual action required.

User has 0 upcoming events after setup complete

Calendar widget displays empty state: "No upcoming events this week"; "Connect Google Calendar" and "Connect Calendly" buttons visible; "Go to Calendar" link available.

User completes setup but hasn't created any data (leads, projects, contractors)

All revealed sections display empty states with appropriate messages; CTAs available (e.g., "Create New Project", "Add Contractor"); Dashboard fully functional but data-less.

User selects highest travel fee option (250 miles) and enters $1000 rate

Values accepted and saved successfully; no upper limit warnings; contractor travel calculations will use these values.

User enters decimal rate (e.g., 20.50) in rate per mile

Decimal value accepted; saved with precision (two decimal places); displayed as $20.50 in settings and calculations.

## **9\. Acceptance Criteria**

### Functional Requirements

*   Dashboard loads successfully after signup and displays trial period banner with correct color based on remaining days.
*   Email verification modal displays after 7 days without verification; blocks Dashboard access; allows verification email resend.
*   Setup progress checklist displays with 8 steps, progress bar, and "0/8 steps completed" indicator.
*   All 8 setup steps are clickable and redirect to appropriate configuration pages in any order.
*   Completing a setup step in a module marks the step complete on Dashboard; checkbox checked; text strikethrough; progress updates.
*   "Configure Data" step redirects to General Settings → General tab; displays travel fee dropdown and rate per mile input.
*   Travel fee dropdown contains options from 25 to 250 miles in increments of 25.
*   Rate per mile field accepts numeric values from $1 to $1000 with decimal precision.
*   Validation errors display if user attempts to save Configure Data without filling required fields or with invalid values.
*   Upon completing all 8 steps, setup checklist card is removed from Dashboard.
*   After setup completion, previously hidden sections are revealed: Pending Contractor Agreements, Pending Counter Sign, Profit & Loss (if Stripe connected and subscribed), Calendar widget (with Google Calendar and Calendly buttons), Overdue Payments, Activity feed.
*   Promotional upgrade card remains visible after setup completion if user has not subscribed.
*   Trial period banner remains visible after setup completion if user has not subscribed and trial is active.
*   Overview metrics display 0 values for new users; percentage changes show "N/A" or are hidden.
*   Empty state sections (New Leads, Events, New Contractors, Unread Messages) display appropriate messages, icons, and CTAs before setup complete.
*   Clicking CTA buttons in empty states redirects to respective configuration or creation pages.
*   Theme toggle functions correctly; theme preference saved and persists across sessions.
*   Greeting message updates based on time of day (Good Morning, Good Afternoon, Good Evening).
*   Inspirational quote displays and changes on each Dashboard page load.
*   "View all" links open popup modals before navigating to full pages (PM: confirm popup content).
*   Trial banner "Choose Plan" button and promotional card "View all plans" button redirect to Subscription Plans page.
*   Email verification link expires after 24 hours; displays appropriate error message.
*   Rate limit on verification email resend enforced (1 per minute).
*   Account locks on Day 0 (trial expiration) if user has not subscribed; lockout message displayed.

### Validation Expectations

*   Travel fee starting distance: Required; must select from dropdown; no default.
*   Rate per mile: Required; numeric; $1-$1000 range; decimals allowed; no default.
*   Email verification: Required within 7 days; account locks after 7 days without verification.
*   Setup step completion: Automatically detected by backend flags; user cannot manually mark steps complete.

### Data Consistency Rules

*   Trial period expiration date calculated as signup date + 14 days; stored in database; checked on each login.
*   Setup step completion status stored per user in database; persists across sessions and devices.
*   Email verification status updated immediately when user clicks verification link; persists permanently.
*   Theme preference saved to user profile; applies globally; persists across sessions and devices.
*   Configure Data settings (travel fee distance, rate per mile) saved to agency global settings; apply to all contractor calculations.

### User Actions and System Flow Validations

*   Users can complete setup steps in any order without restrictions.
*   Setup checklist card removal is automatic and permanent after 8/8 steps complete.
*   Hidden sections remain hidden until ALL 8 steps are complete; no partial reveals.
*   Subscribing removes trial banner and promotional card but does not affect setup completion requirements.
*   Email verification can be completed at any time; unlocks account if locked; does not affect setup progress.

## **10\. Manual Test Cases**

**Test Case File:** TestCases\_Dashboard\_New\_Users\_Agency\_Owner\_v2.xlsx

## **11\. Dependencies**

**Dependency Type**

**Description**

**Expected Behavior if Dependency Fails**

User Authentication Service

Required to verify user identity and session on Dashboard load.

If authentication fails, user is redirected to login page; Dashboard does not load.

Email Service (SMTP)

Required to send verification emails.

If email service fails, verification emails are not sent; error message displayed; user can retry.

Database

Required to store and retrieve all Dashboard data: setup progress, trial status, email verification status, user preferences.

If database unavailable, Dashboard cannot load data; error message displayed with retry option.

Stripe API

Required for "Connect to Stripe" setup step completion detection.

If Stripe API fails, step 7 cannot be completed; user sees error; can retry later; setup progress stuck at 7/8.

Lead Form Builder Module

Required for "Set Up Lead Form" step completion.

If module unavailable, step cannot be completed; user sees error; can complete other steps; setup stuck until module available.

Contract Management Module

Required for "Set Up Contract" and "Set Up Service Agreement" steps.

If module unavailable, steps cannot be completed; user can complete other steps; setup stuck until module available.

Questionnaire Builder Module

Required for "Set Up Post Event Questionnaires" step.

If module unavailable, step cannot be completed; user can complete other steps; setup stuck until module available.

Brand Management Module

Required for "Set Up Your Brand" step.

If module unavailable, step cannot be completed; user can complete other steps; setup stuck until module available.

General Settings Module

Required for "Configure Data" step.

If module unavailable, final step cannot be completed; setup stuck at 7/8; hidden sections remain hidden.

Frontend Assets (CSS, JS, Images)

Required to render Dashboard UI, progress bar, icons, and interactive components.

If assets fail to load, Dashboard may appear broken or unstyled; functionality impaired.

Configuration Service

Required to load default settings, quote list, time-of-day thresholds.

If config fails, system uses hardcoded fallback values; Dashboard loads with defaults.

## **12\. References**

### Figma Links

*   **Dashboard - New User:** 05\_Dashboard\_(New\_User).png (uploaded screenshot)

### Meeting Transcript

*   **Dashboard Meeting - January 3, 2026:** Dashboard\_Jan\_3\_\_2026.pdf
*   **Dashboard Transcript JSON:** Dashboard-d06b8a5b-37a7.json

### Additional Resources

*   **Product Requirements Document (PRD):** \[Link to PRD if available\]
*   **User Stories:** \[Link to User Stories if available\]
*   **Design System / Style Guide:** \[Link to Design System if available\]

**Document Version:** 2.0 (Updated)  
**Last Updated:** January 6, 2026  
**Author:** Business Analyst  
**Reviewers:** Product Manager, Lead Developer, QA Lead, UX Designer

**End of FRD - Dashboard - New Users (Agency Owner Role)**

2\. Dashboard - Existing Users (Agency Owner Role)

# **Functional Requirements Document (FRD)**

# **Dashboard - Existing Users (Agency Owner Role)**

## **1\. Module Overview**

### Module Name

Dashboard - Existing Users (Agency Owner Role)

### Purpose

The Dashboard serves as the operational command center for Agency Owners who have completed the initial setup process. It provides a comprehensive overview of business performance, pending actions, financial analytics, upcoming events, contractor management, payment tracking, and client activities, enabling efficient day-to-day management and strategic decision-making.

### Business Goals

*   Provide at-a-glance visibility into key business metrics (leads, tasks, messages, revenue) with trend analysis.
*   Highlight actionable items requiring immediate attention (pending agreements, counter-signatures, overdue payments, unassigned events).
*   Enable proactive contractor relationship management through agreement tracking and reminder automation.
*   Deliver financial insights through Profit & Loss analytics to support business planning and growth.
*   Facilitate efficient event and project management with calendar integration and filter-based event views.
*   Streamline payment collection and contractor payment tracking through dedicated overdue payment monitoring.
*   Reduce administrative overhead by centralizing critical information and actions in a single interface.
*   Support data-driven decision-making through percentage change indicators and historical trend visibility.
*   Enhance client relationship management by displaying recent client-related activities (proposals, contracts, invoices, payments, questionnaires).

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

### Roles with Access

*   **Agency Owner** (Full Access)

### Granular Permissions

**Permission Type**

**Agency Owner**

View Dashboard

✅ Yes

View Overview Metrics

✅ Yes

View Revenue Card

✅ Yes

View Profit & Loss Chart

✅ Yes (if subscribed + Stripe connected)

View Pending Contractor Agreements

✅ Yes

Send Contractor Agreement Reminders

✅ Yes

View Pending Counter Sign

✅ Yes

Counter-Sign Service Agreements

✅ Yes

View New Leads Table

✅ Yes

View Calendar Widget

✅ Yes

Connect Google Calendar

✅ Yes

Connect Calendly

✅ Yes

View Events Section (All Filters)

✅ Yes

Send SMS Event Reminders

✅ Yes

View Activity Feed

✅ Yes

View Unread Messages

✅ Yes

View Overdue Payments

✅ Yes

View New Contractors

✅ Yes

Toggle Theme Preference

✅ Yes

## **3\. User Flow**

3.1 **The Agency Owner logs into their account** and is redirected to the Dashboard page.

3.2 **The system checks the user's setup completion status.** If all 8 setup steps are complete, the Dashboard displays in "operational mode" (this FRD). If setup is incomplete, the Dashboard displays in "new user mode" (refer to FRD #1).

3.3 **The system loads the Dashboard** and displays the greeting message ("Good Morning, \[User Name\]") with an inspirational quote.

3.4 **The user views the Overview section** with four metric cards: New Leads, Overdue Tasks, Unread Messages, 2025 Revenue.

3.5 **The user clicks on a metric card** to drill down into details.

3.6 **The system redirects the user** to the respective detail page (Leads page, Tasks page, Email Center, or Financial Reports).

3.7 **The user views the Pending Contractor Agreements section** displaying contractors who have not signed their service agreements.

3.8 **The user clicks "Send Reminder"** next to a contractor's name.

3.9 **The system sends a reminder email** to the contractor with a link to sign the agreement.

3.10 **The system displays a success message** and records the timestamp of the reminder sent.

3.11 **The "Send Reminder" button is disabled** for 24 hours to prevent spam.

3.12 **The user clicks "Send All" button** to send reminders to all pending contractors at once.

3.13 **The system sends batch reminder emails** to all contractors in the pending list.

3.14 **The user views the Pending Counter Sign section** displaying service agreements awaiting the Agency Owner's counter-signature.

3.15 **The user clicks "Counter Sign" button** next to an agreement.

3.16 **The system opens the service agreement document** for review.

3.17 **The user reviews the agreement** and clicks "Sign" to apply their counter-signature.

3.18 **The system applies the counter-signature,** marks the agreement as fully executed, and sends confirmation emails to both the contractor and the Agency Owner.

3.19 **The user views the Profit & Loss section** (if subscribed and Stripe connected) showing income, expenses, and profit trends over the selected time period.

3.20 **The user clicks the time period dropdown** in the Profit & Loss section and selects a different period (7 Days, 30 Days, 90 Days, 6 Months, 1 Year).

3.21 **The system refreshes the Profit & Loss chart** with data for the selected time period.

3.22 **The user views the New Leads table** showing the 5-6 most recent leads with key information.

3.23 **The user clicks "View all" link** in the New Leads section.

3.24 **The system displays a popup modal** with summary lead information.

3.25 **The user clicks a navigation option** in the modal to go to the full Leads page.

3.26 **The user views the Calendar widget** showing 3-5 upcoming events.

3.27 **The user clicks "Connect Google Calendar"** button in the Calendar widget.

3.28 **The system redirects the user** to Google's OAuth authorization page.

3.29 **The user authorizes Pixally** to access their Google Calendar.

3.30 **The system receives the authorization token,** saves it, and redirects the user back to the Dashboard.

3.31 **The "Connect Google Calendar" button changes** to "Manage Calendar Settings."

3.32 **The user clicks "Connect Calendly"** button in the Calendar widget.

3.33 **The system redirects the user** to Calendly's OAuth authorization page.

3.34 **The user authorizes Pixally** to access their Calendly account.

3.35 **The system receives the authorization token,** saves it, and returns the user to the Dashboard.

3.36 **The "Connect Calendly" button changes** to "Manage Calendly Settings."

3.37 **The user views the Events section** with four filter tabs: All, Next 7 Days, Date Pending, Unassigned.

3.38 **The user clicks a filter tab** to view events matching that filter criteria.

3.39 **The system updates the events table** to display filtered results with a count badge on the active tab.

3.40 **The user clicks the "Reminder" button** in the Action column of an event row.

3.41 **The system displays a modal popup** showing contractors assigned to the event, split into two tabs: Pending and Accepted.

3.42 **The user views the Pending tab** showing contractors who have not yet confirmed attendance.

3.43 **The user selects one or more contractors** and clicks "Resend SMS Reminder."

3.44 **The system sends SMS reminders** to the selected contractors.

3.45 **The user views the Activity feed** showing recent client-related activities: Proposals, Contracts, Invoices, Payments, Questionnaires.

3.46 **The user clicks on a specific activity item** (e.g., "Payment received from John & Monica").

3.47 **The system redirects the user to the Activity detail page** showing complete information about that specific activity (payment details, invoice breakdown, related documents, timeline).

3.48 **The user clicks "View Active Projects" link** at the bottom of the Activity feed section.

3.49 **The system redirects the user to the Project Listing page** filtered to show only active projects.

3.50 **The user views Unread Messages** from clients and projects.

3.51 **The user clicks "View" button** next to a message.

3.52 **The system displays a message detail modal** with the full message content.

3.53 **The user views the Overdue Payments section** with two tabs: Clients and Contractors.

3.54 **The user clicks the Clients tab** to view overdue payments from clients to the agency.

3.55 **The user clicks the Contractors tab** to view overdue payments from the agency to contractors.

3.56 **The user clicks "View all payments"** link in the Overdue Payments section.

3.57 **The system redirects the user** to the Finance module → Billing → Transactions → Overdue filter applied.

3.58 **The user views the New Contractors section** showing recently added contractors who need profile setup.

3.59 **The user clicks "Set Up User"** button next to a contractor.

3.60 **The system redirects the user** to the contractor's profile page to complete setup.

3.61 **The user navigates away** using the sidebar menu to access other modules.

## **4\. Functional Logic**

### 4.1 Overview Section - Key Metrics

The Overview section displays four metric cards providing a snapshot of critical business indicators:

#### **4.1.1 New Leads Card**

*   **Display:** Count of new leads created in the last 30 days.
*   **Percentage Change:** Comparison of last 30 days vs. previous 30 days.
    *   Formula: ((Last 30 Days - Previous 30 Days) / Previous 30 Days) × 100
    *   Green upward arrow (↑) for positive growth; Red downward arrow (↓) for decline; Gray dash (—) for no change.
*   **Clickable:** Yes. Redirects to Leads page filtered by "Last 30 Days."
*   **Data Source:** Leads module database table, filtered by created\_date.

#### **4.1.2 Overdue Tasks Card**

*   **Display:** Count of tasks with due\_date < current\_date and status ≠ "Completed."
*   **Percentage Change:** Comparison of last 30 days vs. previous 30 days (tasks that became overdue).
*   **Clickable:** Yes. Redirects to Tasks page filtered by "Overdue."
*   **Data Source:** Tasks module database table, filtered by due\_date and status.

#### **4.1.3 Unread Messages Card**

*   **Display:** Count of messages with read\_status = false for the current user.
*   **Percentage Change:** Comparison of last 30 days vs. previous 30 days (new unread messages).
*   **Clickable:** Yes. Redirects to Email Center filtered by "Unread."
*   **Data Source:** Messages/Email module database table, filtered by read\_status.

#### **4.1.4 2025 Revenue Card**

*   **Display:** Total revenue for the current year (2025 in example; updates dynamically each year).
*   **Format:** Currency with commas (e.g., $2.3k for $2,300; $150.5k for $150,500).
*   **Percentage Change:** Comparison of last 30 days vs. previous 30 days revenue.
*   **Clickable:** Yes. Redirects to Financial Reports → Revenue page.
*   **Data Source:** Invoices/Payments module, sum of paid invoices for current year.
*   **Visibility:** This card is visible ONLY to Agency Owners; hidden from Admins and Project Managers (who see "Total Booked Jobs" instead).

### 4.2 Pending Contractor Agreements

#### **4.2.1 Section Purpose**

*   Displays contractors who have been invited to the platform but have not yet signed their service agreements.
*   Enables the Agency Owner to send reminder emails to prompt contractors to complete the agreement signing process.

#### **4.2.2 Display Logic**

*   The section displays a maximum of 3-5 contractors with pending agreements.
*   Each contractor entry shows:
    *   Contractor name and profile picture (or initials if no picture)
    *   Event/project name they are assigned to
    *   Date the agreement was sent
    *   "Send Reminder" button in the Action column
*   If there are more than 5 pending contractors, a "View all" link is displayed at the section bottom.
*   If no contractors have pending agreements, the section displays an empty state: "All contractors have signed their agreements."

#### **4.2.3 Reminder Functionality**

*   **Individual Reminder:** Clicking "Send Reminder" sends an email to that specific contractor with a direct link to view and sign the agreement.
*   **Batch Reminder:** The "Send All" button sends reminder emails to all contractors in the pending list.
*   **Rate Limit Enforcement:** After sending a reminder, the "Send Reminder" button is disabled for 24 hours for that contractor to prevent spam. The button displays "Sent X hours ago" during the cooldown period.
*   **Email Content:** The reminder email includes the contractor's name, project name, a direct link to the agreement, and a friendly message encouraging them to complete the signing process.
*   **Success Message:** After sending, the system displays: "Reminder email sent to \[Contractor Name\] successfully."
*   **Error Handling:** If the email fails to send, the system displays: "Failed to send reminder email. Please try again."

#### **4.2.4 Agreement Workflow Integration**

*   When a contractor signs their service agreement (via the link in the email), the system automatically:
    *   Moves the contractor from "Pending Contractor Agreements" to "Pending Counter Sign" (if counter-signature required).
    *   Updates the agreement status in the database.
    *   Sends a notification to the assigned counter-signer (Agency Owner, Admin, or PM depending on who sent the agreement).

### 4.3 Pending Counter Sign Section

#### **4.3.1 Section Purpose**

*   Displays service agreements that have been signed by contractors but now require the Agency Owner's counter-signature to become fully executed.
*   This section enables the Agency Owner to review and counter-sign agreements to complete the contracting process.

#### **4.3.2 Counter-Signer Assignment Logic**

*   **Auto-Send Agreements:** When service agreements are automatically sent to contractors via system automation, the counter-signer is automatically assigned to the Agency Owner.
*   **Manual Send Agreements:** When an agency representative (Owner, Admin, or PM) manually sends a service agreement, the sender becomes the assigned counter-signer.
*   The assignment is recorded in the database at the time the agreement is sent and does not change if the agreement is resent.

#### **4.3.3 Section Display Logic**

*   The Pending Counter Sign section is visible to all three roles (Agency Owner, Admin, PM).
*   The Agency Owner sees all pending counter-sign agreements agency-wide (since auto-sent agreements default to Owner, and Owner can send agreements manually).
*   Each agreement entry shows:
    *   Contractor name and profile picture/initials
    *   Project name associated with the agreement
    *   Date the contractor signed the agreement
    *   Status indicator: "Awaiting Your Counter-Signature"
    *   "Counter Sign" button in the Action column
*   Maximum 5 agreements displayed; if more exist, "View all" link provided.
*   If no agreements await counter-signature, empty state: "No agreements awaiting your signature."

#### **4.3.4 Counter-Signing Workflow**

*   **Step 1:** User clicks "Counter Sign" button.
*   **Step 2:** System opens the service agreement document for review (modal overlay or dedicated signing page).
*   **Step 3:** User reviews agreement terms, contractor signature, and all contract details.
*   **Step 4:** User clicks "Sign" or "Apply Signature" button.
*   **Step 5:** System applies the Agency Owner's electronic signature with timestamp and IP address logging.
*   **Step 6:** Agreement status updated to "Fully Executed" or "Complete" in the database.
*   **Step 7:** Agreement removed from Pending Counter Sign section.
*   **Step 8:** Both contractor and counter-signer receive email confirmation with the fully executed agreement attached as PDF.
*   **Step 9:** Fully executed agreement stored in Documents module and linked to the project.

#### **4.3.5 Error Handling**

*   If agreement document cannot load: "Unable to load agreement. Please try again or contact support."
*   If signature submission fails: "Failed to apply signature. Please try again."
*   If user is no longer authorized (e.g., role changed): "You are not authorized to counter-sign this agreement."

### 4.4 Profit & Loss Section

#### **4.4.1 Display Conditions**

*   The Profit & Loss section is displayed ONLY if:
    *   The user has an active subscription (not on trial or expired trial).
    *   The user has connected their Stripe account successfully.
*   If the user has not subscribed OR has not connected Stripe, the section displays a locked state card:
    *   Message: "Connect Stripe to view Profit & Loss analytics."
    *   Button: "Connect Stripe" (redirects to Payment Settings → Stripe Integration).

#### **4.4.2 Time Period Selection**

*   A dropdown selector is displayed at the top-right of the Profit & Loss section with five time period options:
    *   7 Days
    *   30 Days
    *   90 Days
    *   6 Months
    *   1 Year
*   Default selection: **7 Days**
*   Clicking a time period updates the chart data dynamically without page refresh.

#### **4.4.3 Data Display**

*   The section displays three key financial metrics in card format:
    *   **Total Income:** Sum of all paid invoices for the selected time period.
    *   **Total Expenses:** Sum of all expenses (contractor payments, operational costs) for the selected time period.
    *   **Total Profit:** Calculated as Total Income - Total Expenses.
*   Each metric card shows:
    *   Metric name
    *   Current period value (currency formatted)
    *   Percentage change compared to the previous equivalent period (e.g., if viewing "30 Days," compares last 30 days to previous 30 days)
    *   Color-coded arrow: Green ↑ for increase, Red ↓ for decrease

#### **4.4.4 Chart Visualization**

*   Below the metric cards, a line chart displays the trend of Total Income, Total Expenses, and Total Profit over the selected time period.
*   **X-Axis:** Time intervals (days, weeks, or months depending on selected period).
*   **Y-Axis:** Currency values (auto-scaled based on data range).
*   **Lines:**
    *   Total Income: Displayed in one color (e.g., green or blue).
    *   Total Expenses: Displayed in another color (e.g., red or orange).
    *   Total Profit: Displayed in a third color (e.g., purple or teal).
*   **Interactivity:** Hovering over data points displays a tooltip with exact values for that date/period.
*   **Legend:** Displayed at the top or bottom of the chart to identify each line.
*   **Designer Note:** Confirm exact chart design specifications (line thickness, marker styles, legend position, tooltip format, responsive behavior).

#### **4.4.5 Data Source**

*   Income data sourced from Invoices module (paid invoices only).
*   Expense data sourced from Expenses module and Contractor Payments (paid amounts).
*   All data is queried from Stripe via API integration to ensure accuracy.

### 4.5 New Leads Section

#### **4.5.1 Display Logic**

*   Displays the 5-6 most recent leads created in the system.
*   Table columns: Lead Name, Created Date, Contact Information (email or phone), Lead Source, Action.
*   **Lead Name:** Clickable, redirects to Lead detail page.
*   **Created Date:** Formatted as relative time (e.g., "2 hours ago", "Yesterday", "3 days ago").
*   **Contact Information:** Displays email address or phone number based on lead data.
*   **Lead Source:** Displays the source of the lead (e.g., "Lead Form," "Referral," "Google Search," "Social Media").
*   **Action Column:** "Show More" button that redirects to the Lead detail page.

#### **4.5.2 Empty State**

*   If no leads exist, the section displays: "You have no active leads" with an icon and a "Setup Contact Form" CTA button.

#### **4.5.3 "View all" Link**

*   At the bottom of the section, a "View all" link is displayed.
*   Clicking "View all" opens a popup modal with lead summary information.
*   From the modal, the user can navigate to the full Leads page.
*   **PM Note:** Confirm the exact content and structure of the popup modal for "View all" links.

### 4.6 Calendar Widget

#### **4.6.1 Display Logic**

*   The Calendar widget displays 3-5 upcoming events (events with event\_date >= current\_date).
*   Each event entry shows:
    *   Event name
    *   Event date and time
    *   Client name
    *   Location or service area
*   If no upcoming events exist, the widget displays an empty state: "No upcoming events this week."

#### **4.6.2 Google Calendar Integration**

*   A "Connect Google Calendar" button is displayed in the Calendar widget.
*   **Before Connection:** Button text: "Connect Google Calendar"
*   **OAuth Flow:**
    *   User clicks "Connect Google Calendar."
    *   System redirects to Google OAuth 2.0 authorization page.
    *   User logs into their Google account (if not already logged in).
    *   User grants Pixally permission to access their Google Calendar.
    *   Google redirects back to Pixally with an authorization code.
    *   Pixally backend exchanges the authorization code for an access token and refresh token.
    *   Tokens are securely stored in the database, associated with the user's account.
    *   System redirects user back to Dashboard.
*   **After Connection:** Button text changes to "Manage Calendar Settings" or "Connected."
*   **Post-Connection Functionality:**
    *   Pixally events are automatically synced to the user's Google Calendar.
    *   User can view Pixally events in their Google Calendar app.
    *   Two-way sync may be enabled (optional): Google Calendar events appear in Pixally Dashboard.
*   **PM Note:** Confirm exact Google Calendar OAuth flow, redirect URLs, error handling, token refresh logic, and two-way sync requirements.

#### **4.6.3 Calendly Integration (NEW)**

*   A "Connect Calendly" button is displayed in the Calendar widget (alongside or below "Connect Google Calendar").
*   **Before Connection:** Button text: "Connect Calendly"
*   **OAuth Flow:**
    *   User clicks "Connect Calendly."
    *   System redirects to Calendly OAuth authorization page.
    *   User logs into their Calendly account (if not already logged in).
    *   User grants Pixally permission to access their Calendly account.
    *   Calendly redirects back to Pixally with an authorization code.
    *   Pixally backend exchanges the authorization code for an access token.
    *   Token is securely stored in the database.
    *   System redirects user back to Dashboard.
*   **After Connection:** Button text changes to "Manage Calendly Settings" or "Connected."
*   **Post-Connection Functionality:**
    *   Calendly events/bookings may be synced to the Calendar widget and displayed alongside Google Calendar events.
    *   User can manage Calendly settings or disconnect from within Pixally.
*   **PM Note:** Confirm exact Calendly OAuth flow, redirect URLs, post-connection functionality (event sync, display format), and error handling.

#### **4.6.4 "Go to Calendar" Link**

*   At the bottom of the Calendar widget, a "Go to Calendar" link is displayed.
*   Clicking this link redirects the user to the full Calendar module/page.

### 4.7 Events Section with Filters

#### **4.7.1 Filter Tabs**

The Events section includes four filter tabs at the top:

**1\. All Tab**

*   Displays all events regardless of date or status.
*   Count badge shows total number of events in the system.
*   Default active tab on Dashboard load.

**2\. Next 7 Days Tab**

*   Displays events with event\_date between current\_date and current\_date + 7 days.
*   Count badge shows number of events in the next 7 days.

**3\. Date Pending Tab**

*   Displays events with event\_date = null or event\_date not confirmed.
*   Count badge shows number of events with pending dates.

**4\. Unassigned Tab**

*   Displays events that have at least one contractor role unassigned.
*   Count badge shows number of events with unassigned roles.
*   Tooltip on "Unassigned" tab explains: "Events with at least one contractor role not yet assigned."

#### **4.7.2 Events Table**

*   Columns: Next Event Date, Project Name, Users (assigned team members or contractors), Brand, Service Area, Action.
*   **Next Event Date:** Displays the event date; if pending, displays "Date Pending" with a calendar icon.
*   **Project Name:** Clickable, redirects to Project detail page.
*   **Users:** Displays profile pictures of assigned users (contractors, team members); stacked avatars if multiple users.
*   **Brand:** Displays the brand name associated with the project.
*   **Service Area:** Displays the location or service area (e.g., "New Jersey").
*   **Action Column:**
    *   "Reminder" button for events with assigned contractors (sends SMS reminders).
    *   "View Details" button to navigate to Event detail page.

#### **4.7.3 Filter Interaction**

*   Clicking a filter tab updates the events table to display only matching events.
*   The active tab is highlighted with a different background color or underline.
*   Count badges update dynamically as events are added, completed, or updated.

### 4.8 SMS Reminder System for Events

#### **4.8.1 Automatic SMS Reminders**

*   The system automatically sends SMS reminders to contractors 5 days before an event date.
*   SMS content includes: Event name, event date, event location, and a request to confirm attendance.
*   Contractors reply "yes" (case-insensitive; also accepts "Yes", "YES", "yeah", "ok", "confirm") to confirm attendance.
*   When a contractor replies "yes," the system updates their status to "Accepted" and moves them from the Pending tab to the Accepted tab in the Reminders modal.

#### **4.8.2 Manual SMS Reminders**

*   The Agency Owner can manually send SMS reminders by clicking the "Reminder" button in the Action column of an event row.
*   Clicking "Reminder" opens a modal popup with two tabs: Pending and Accepted.
*   **Pending Tab:** Shows contractors assigned to the event who have not confirmed attendance.
*   **Accepted Tab:** Shows contractors who have already confirmed attendance (replied "yes" to SMS).
*   The user can select one or more contractors in the Pending tab and click "Resend SMS Reminder" to send another SMS.
*   Rate limit: A contractor can receive a maximum of 1 SMS reminder per 24 hours to prevent spam.

#### **4.8.3 SMS Provider Integration**

*   SMS messages are sent via an SMS gateway provider (e.g., Twilio, MessageBird).
*   The system logs all SMS sends with timestamp, recipient, message content, and delivery status.
*   If SMS delivery fails, the system logs the error and displays a warning to the user: "Failed to send SMS to \[Contractor Name\]. Please try again."
*   **PM Note:** Confirm SMS gateway provider, error codes, retry logic, and rate limit enforcement mechanism.

### 4.9 Activity Feed (UPDATED)

#### **4.9.1 Section Purpose**

*   The Activity feed displays recent client-related activities to help the Agency Owner stay informed about business interactions, document status, and financial transactions.
*   Activities are displayed in reverse chronological order (most recent first).

#### **4.9.2 Activity Types Displayed (UPDATED)**

The Activity feed shows the following client-related activity types:

1.  **Proposals:** When a proposal is sent to a client, viewed by a client, accepted, or declined.  
    *   Example: "Proposal sent to John & Monica" (2 hours ago)
2.  **Contracts:** When a contract is sent to a client, signed by a client, or executed.  
    *   Example: "Contract signed by John & Monica" (1 day ago)
3.  **Invoices:** When an invoice is created, sent to a client, viewed, or marked as paid.  
    *   Example: "Invoice #1234 sent to John & Monica" (3 days ago)
4.  **Payments (NEW):** When a payment is received from a client.  
    *   **Format:** "Payment received from \[Client Name\]: \[Paid Amount\] for Invoice #\[Invoice Number\]"
    *   **Example:** "Payment received from John & Monica: $2,500 for Invoice #1234" (1 hour ago)
    *   **Data Displayed:**
        *   Client name (clickable, links to Client detail page)
        *   Paid amount (currency formatted)
        *   Invoice number (clickable, links to Invoice detail page)
    *   **Click Behavior:** Clicking on the payment activity item redirects to the **Activity detail page** showing complete payment information (payment method, transaction ID, payment date, related invoice, payment breakdown).
5.  **Questionnaires (NEW):** When a post-event questionnaire is sent to a client, viewed, or completed.  
    *   Example: "Questionnaire completed by John & Monica" (2 days ago)
    *   **Click Behavior:** Clicking on the questionnaire activity item redirects to the **Questionnaire detail page** (as shown in uploaded screenshot: /mnt/user-data/uploads/1774556598224\_image.png) showing questionnaire responses, completion status, and related project information.

**Activities EXCLUDED from Agency Owner Activity feed:**

*   Internal activities: Task assignments, team member updates, system configuration changes

**Difference vs. Team Members (Admin/PM) — see FRD #3, Section 4.10:**

*   Team Members (Admin & Project Manager) DO see Proposals, Contracts, Invoices, and Payments (including payment schedules) — there is no financial limitation on their activity feed.
*   Team Members do NOT see Questionnaire activities (Questionnaires appear only in the Agency Owner feed).
*   Scope: Admin activity is brand-scoped (assigned brands); PM activity is project-scoped (assigned projects only, which may span multiple brands).

#### **4.9.3 Activity Display Format**

*   Each activity entry shows:
    *   **Icon:** Representing the activity type (proposal icon, contract icon, invoice icon, payment icon, questionnaire icon)
    *   **Description:** Brief text describing the action (e.g., "Proposal sent to client", "Payment received from John & Monica")
    *   **Related Entity:** Client name, project name, or document reference (e.g., "Invoice #1234")
    *   **Timestamp:** Relative time (e.g., "2 hours ago", "Yesterday", "3 days ago")
    *   **Action Button (optional):** Quick action like "View Proposal", "Download Contract", "View Payment"

#### **4.9.4 Activity Item Interaction (UPDATED)**

*   **Clicking on an activity item:** The system redirects the user to the **Activity detail page** showing complete information about that specific activity.  
    
*   **Activity detail page displays:  
    **
    *   Full activity description and context
    *   Related documents (PDF downloads, preview links)
    *   Associated project and client information
    *   Timeline of related activities
    *   Action buttons (e.g., "View Proposal", "Resend Email", "Download PDF")
*   **Example for Payment Activity:  
    **
    *   Activity detail page shows: Payment amount, payment method, transaction ID, payment date, related invoice (with link), payment breakdown, receipt download, client information, project association
*   **Example for Questionnaire Activity:  
    **
    *   Activity detail page shows: Questionnaire name, client responses, completion status, project name, submission date, respondent information, file activity log (as shown in screenshot)

#### **4.9.5 "View Active Projects" Link (UPDATED)**

*   At the bottom of the Activity feed section, a "View Active Projects" link is displayed.
*   **Clicking this link:** The system redirects the user to the **Project Listing page**.
*   **Project Listing page displays:**
    *   All active projects (not completed, cancelled, or archived)
    *   Standard project list columns: Project Name, Client, Event Date, Status, Assigned Team, Actions
    *   "Active" status filter automatically applied
    *   User can further filter, sort, or search projects

#### **4.9.6 Empty State**

*   If there are no recent activities, the Activity feed displays: "No recent activity. Client interactions will appear here."
*   Empty state does not include a CTA button (this is a passive information section).

#### **4.9.7 Maximum Activities Displayed**

*   The Dashboard displays a maximum of 5-7 recent activities.
*   A "View all" link at the bottom navigates to a full Activity history page showing all activities with pagination.

### 4.10 Unread Messages Section

#### **4.10.1 Display Logic**

*   Displays unread messages from clients related to projects or general inquiries.
*   Table columns: Project Name, From (client name), Subject, Date Received, Action.
*   Maximum 5-6 unread messages displayed on Dashboard.
*   Messages are sorted by date received (most recent first).

#### **4.10.2 Message Interaction**

*   Clicking "View" button in the Action column opens a message detail modal.
*   The modal displays:
    *   Full message content
    *   Sender information (name, email)
    *   Related project or inquiry context
    *   "Reply" button to compose a response
    *   "Mark as Read" button
*   After viewing, the message is automatically marked as read, and the Unread Messages count decrements.

#### **4.10.3 Empty State**

*   If no unread messages exist, the section displays: "You have no messages yet" with an icon and a "Connect Email" CTA button.

### 4.11 Overdue Payments Section

#### **4.11.1 Two Tabs: Clients and Contractors**

The Overdue Payments section includes two tabs:

**1\. Clients Tab**

*   Displays payments that are overdue from clients to the agency.
*   Table columns: Client Name, Due Date, Amount, Project, Action.
*   Each row represents an unpaid or partially paid invoice past its due date.
*   Action: "Show More" button redirects to Invoice detail page.

**2\. Contractors Tab**

*   Displays contractor payments owed by the agency that are past due, covering two categories of items in a single combined list:
    *   **Overdue (unpaid) invoices:** Contractor invoices that the agency owes and has not attempted to pay, where the due date has passed.
    *   **Failed payments (overdue):** Contractor payments the agency attempted to process but which failed (e.g., card declined, transfer bounced, processor error), and where the due date has now passed.
*   Both categories appear together in one list, distinguished by the **Status** column rather than being split into separate sub-sections.
*   **Table columns:** Status, Number, Due Date, Amount Due, Project Name, Action.
    *   **Status:** A color-coded badge indicating the row type:
        *   **"Overdue"** badge — an unpaid contractor invoice past its due date (no payment attempted yet).
        *   **"Failed"** badge — a contractor payment that was attempted but failed, and is now past due.
    *   **Number:** The contractor invoice/payment reference number (e.g., "DDD-CTR-1779270068"). Clickable; redirects to the contractor payment/invoice detail page.
    *   **Due Date:** The date the payment was due, formatted as day and date (e.g., "Wed, 05/27/2026").
    *   **Amount Due:** The outstanding amount owed to the contractor, currency formatted (e.g., "$34").
    *   **Project Name:** The associated project name with an event-type badge below it (e.g., "Test Payment" with "ANNIVERSARY (2)" badge). Clickable; redirects to the Project detail page.
    *   **Action:** Two action buttons per row — **"Pay"** and **"Void"** (see 4.11.2 below).
*   The list is scrollable horizontally if columns exceed the viewport width.
*   A maximum of 5 rows is displayed on the Dashboard; if more exist, a "View all payments" link is provided (see 4.11.3).

#### **4.11.2 Contractors Tab Actions (Pay and Void)**

**Pay Action**

*   Each row in the Contractors tab includes a **"Pay"** button in the Action column.
*   Clicking **"Pay"** opens a menu (dropdown or modal) presenting two options:
    1.  **Pay Now:** Initiates an actual payment to the contractor through the connected payment processor (e.g., Stripe).
        *   For a **Failed** row, this re-attempts the payment.
        *   For an **Overdue** (unpaid) row, this processes the payment for the first time.
        *   On success, the item is removed from the Overdue Payments list and the payment status is updated to "Paid".
    2.  **Mark as Paid:** Manually marks the contractor invoice/payment as paid without processing a payment through the system (used when the agency has paid the contractor outside the platform, e.g., by cash, check, or external transfer).
        *   On confirmation, the item is removed from the Overdue Payments list and the status is updated to "Paid (Manual)" or equivalent.

**Void Action**

*   Each row also includes a **"Void"** button in the Action column.
*   Clicking **"Void"** cancels/voids the contractor invoice or payment so it is no longer owed.
*   On confirmation, the item is removed from the Overdue Payments list and its status is updated to "Voided".
*   **PM Note:** Confirm whether a confirmation dialog is required before voiding, and whether voided items are recoverable or permanently cancelled.

#### **4.11.3 "View all payments" Link**

*   At the bottom of each tab, a "View all payments" link is displayed.
*   **For Clients tab:** Redirects to Finance module → Billing → Transactions → Overdue filter (client payments).
*   **For Contractors tab:** Redirects to Finance module → Contractor Payments → Overdue filter (showing both overdue unpaid and failed payments).

#### **4.11.4 Empty State**

*   If no overdue payments exist, the respective tab displays: "No overdue payments" with a checkmark icon.

### 4.12 New Contractors Section

#### **4.12.1 Display Logic**

*   Displays contractors who have been recently added to the platform but have not completed their profile setup.
*   Shows contractor name, role/specialty, location, and a "Set Up User" button.
*   Maximum 3-5 contractors displayed on Dashboard.

#### **4.12.2 "Set Up User" Action**

*   Clicking "Set Up User" redirects to the contractor's profile page where the Agency Owner can complete or assist with profile setup (add portfolio, services, rates, etc.).

#### **4.12.3 "View all" Link**

*   A "View all" link at the bottom navigates to the full Contractors management page.

#### **4.12.4 Empty State**

*   If no new contractors exist, the section displays: "You have no contractors yet" with an icon and an "Add Contractor" CTA button.

### 4.13 Navigation and Interaction

*   Left sidebar menu accessible with "Dashboard" menu item highlighted.
*   Top navigation bar includes: search, notifications, Tasks icon with count badge, user profile dropdown, theme toggle, "Create" button.
*   "Create" button opens dropdown with quick actions: Create Project, Create Lead, Create Task, Add Contractor, Create Invoice, etc.
*   All "View all" links open popup modals first, then navigate to full detail pages.
*   Data refreshes on page load; no real-time auto-refresh (user must manually refresh page to see latest data).
*   **PM Note:** Confirm if Dashboard data should auto-refresh at intervals (e.g., every 5 minutes) or remain static until page reload.

### 4.14 Greeting and Inspirational Quote

*   Same logic as documented in FRD #1 (New Users).
*   Greeting message updates based on time of day: "Good Morning, \[Name\]", "Good Afternoon, \[Name\]", "Good Evening, \[Name\]".
*   Inspirational quote displayed below greeting, randomly selected from database, changes on each page load.

### 4.15 Theme Preference

*   Same logic as documented in FRD #1.
*   Users can toggle between light and dark mode.
*   Theme preference saved to user profile and persists across sessions and devices.

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

**Field Name**

**Field Type**

**Validation Rules**

New Leads Count

Calculated Number

System-calculated based on last 30 days; display-only.

Overdue Tasks Count

Calculated Number

System-calculated based on due\_date < current\_date and status ≠ completed; display-only.

Unread Messages Count

Calculated Number

System-calculated based on read\_status = false; display-only.

2025 Revenue

Calculated Currency

System-calculated sum of paid invoices for current year; display-only.

Percentage Change

Calculated Percentage

Calculated as ((Last Period - Previous Period) / Previous Period) × 100; display-only.

Profit & Loss Time Period

Dropdown

Options: 7 Days, 30 Days, 90 Days, 6 Months, 1 Year; default: 7 Days.

Total Income

Calculated Currency

Sum of paid invoices for selected time period; display-only.

Total Expenses

Calculated Currency

Sum of expenses and contractor payments for selected time period; display-only.

Total Profit

Calculated Currency

Total Income - Total Expenses; display-only.

Event Filter Tab

Tab Selection

Options: All, Next 7 Days, Date Pending, Unassigned; default: All.

SMS Reminder Selection

Checkbox

Multiple contractors can be selected; validated to ensure at least one selected before sending.

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

**Success Scenario**

**Success Message**

**Trigger Condition**

**Post-Success Action**

Contractor Reminder Sent

"Reminder email sent to \[Contractor Name\] successfully."

User clicks "Send Reminder"; email sent successfully.

Button disabled for 24 hours; button text changes to "Sent X hours ago"; timestamp recorded.

Batch Reminders Sent

"Reminder emails sent to \[X\] contractors successfully."

User clicks "Send All"; all emails sent successfully.

All buttons disabled; status indicators updated.

SMS Reminders Resent

"SMS reminders resent to \[X\] contractors successfully."

User selects contractors in modal and clicks "Resend SMS Reminder"; SMS sent.

Modal updated; contractors moved to Accepted tab if they reply "yes"; 24-hour cooldown enforced.

Google Calendar Connected

"Google Calendar connected successfully."

User completes Google OAuth flow; tokens saved.

Button text changes to "Manage Calendar Settings"; events synced to Google Calendar.

Calendly Connected

"Calendly connected successfully."

User completes Calendly OAuth flow; token saved.

Button text changes to "Manage Calendly Settings"; Calendly events may sync to Calendar widget.

Message Marked as Read

"Message marked as read."

User views message; system marks as read.

Message removed from Unread Messages section; count decrements.

Event Date Set

"Event date set successfully for \[Event Name\]."

User sets event date from "Date Pending" filter.

Event moved from Date Pending tab to appropriate date filter; count badges updated.

Counter-Signature Applied

"Agreement counter-signed successfully. \[Contractor Name\]'s service agreement is now fully executed."

User completes counter-signature.

Agreement removed from Pending Counter Sign; moved to executed agreements; email sent to contractor and counter-signer.

Contractor Payment Paid (Pay Now)

"Payment of \[Amount\] to \[Contractor Name\] processed successfully."

User clicks "Pay" → "Pay Now"; payment processed successfully via processor.

Item removed from Overdue Payments (Contractors tab); status updated to "Paid".

Contractor Payment Marked as Paid

"Payment for \[Number\] marked as paid."

User clicks "Pay" → "Mark as Paid"; confirms manual payment.

Item removed from Overdue Payments (Contractors tab); status updated to "Paid (Manual)".

Contractor Payment Voided

"Payment \[Number\] has been voided."

User clicks "Void"; confirms void action.

Item removed from Overdue Payments (Contractors tab); status updated to "Voided".

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

**Error Scenario**

**Error Message**

**Trigger Condition**

**Required User Action**

**System Response**

Reminder Email Failed

"Failed to send reminder email to \[Contractor Name\]. Please try again."

SMTP error or invalid email address.

User should retry sending; check contractor's email address; contact support if error persists.

Display error toast; button remains enabled for retry; error logged to backend.

SMS Reminder Failed

"Failed to send SMS reminder to \[Contractor Name\]. Please try again."

SMS gateway error or invalid phone number.

User should retry; verify contractor's phone number; contact support if error persists.

Display error toast; contractor remains selected in modal; retry available; error logged.

Google Calendar Connection Failed

"Failed to connect Google Calendar. Please try again or contact support."

OAuth flow fails; token exchange error; network issue.

User should retry connection; ensure Google account permissions granted; contact support if issue persists.

Display error message; "Connect Google Calendar" button remains available; error logged.

Calendly Connection Failed

"Failed to connect Calendly. Please try again or contact support."

OAuth flow fails; token exchange error; network issue.

User should retry connection; ensure Calendly account permissions granted; contact support if issue persists.

Display error message; "Connect Calendly" button remains available; error logged.

Profit & Loss Load Failed

"Unable to load Profit & Loss data. Please try again."

Stripe API error; database query failure; network issue.

User should refresh page; contact support if error persists.

Display error message in place of chart; "Retry" button available; error logged.

Dashboard Load Failed

"Unable to load Dashboard data. Please check your internet connection and try again."

Network connectivity issue; server downtime; database unavailable.

User should check internet connection; refresh page; contact support if server is down.

Display error message; "Retry" button available; error logged.

Counter-Sign Document Load Failed

"Unable to load agreement. Please try again or contact support."

Agreement document fetch fails; file not found; database error.

User should retry; contact support if error persists.

Display error toast; "Counter Sign" button remains clickable for retry; error logged.

Counter-Signature Submission Failed

"Failed to apply signature. Please try again."

Database update error; API failure; network issue.

User should retry signing process.

Display error toast; user remains on signing page; agreement not marked complete; error logged.

Contractor Payment (Pay Now) Failed

"Payment to \[Contractor Name\] failed. Please try again."

Payment processor declines or errors during "Pay Now".

User should retry "Pay Now" or use "Mark as Paid" if paid externally.

Display error toast; item remains in Overdue Payments with "Failed" status; retry available; error logged.

Void Action Failed

"Failed to void payment \[Number\]. Please try again."

Database update error or network issue during void.

User should retry the void action.

Display error toast; item remains in the list; error logged.

## **8\. Edge Cases**

**Edge Case**

**Expected Behavior**

User has no leads, tasks, or messages

Overview metrics display 0 for all cards; percentage changes show "N/A" or hidden; cards still clickable but redirect to empty pages.

User has not connected Stripe or not subscribed

Profit & Loss section displays locked state card: "Connect Stripe to view Profit & Loss analytics" with "Connect Stripe" button.

User clicks "Send Reminder" for contractor, then clicks again within 24 hours

Button is disabled with text "Sent X hours ago"; tooltip explains 24-hour rate limit; user cannot send another reminder until cooldown expires.

Contractor replies "yes" to SMS while user is viewing Reminders modal

Modal does not update in real-time; user must close and reopen modal to see updated status; contractor moved to Accepted tab on next modal open.

User selects multiple contractors in Pending tab, but SMS fails for some

Success message indicates how many reminders sent successfully (e.g., "SMS sent to 3 out of 5 contractors"); error message lists failed contractors; retry available for failed ones.

User disconnects Google Calendar after initial connection

"Manage Calendar Settings" button changes back to "Connect Google Calendar"; previously synced events may remain in Google Calendar but future events won't sync.

User completes Google Calendar OAuth but closes browser before redirect completes

OAuth tokens saved on backend; on next Dashboard load, button shows "Manage Calendar Settings" (connection successful despite browser close).

Event has 0 assigned contractors

"Reminder" button is hidden or disabled; tooltip explains: "No contractors assigned to this event."

User views Profit & Loss for "1 Year" but account is only 6 months old

Chart displays data for available period (6 months); X-axis adjusts to show 6 months instead of full year; no error message.

User clicks "View all" link, modal opens, but user closes modal without navigating

Modal closes; user remains on Dashboard; "View all" link still available for retry; no data lost.

Multiple pending counter-sign agreements for same project

All agreements listed separately in Pending Counter Sign section; user can counter-sign in any order; no enforced sequence.

User counter-signs agreement from mobile device

System supports mobile-responsive signing interface; signature capture works on touch devices; all functionality available.

Payment activity displays with $0 amount (edge case: payment correction or error)

Payment activity still displays in Activity feed; clicking redirects to Activity detail page showing $0 payment with explanation; no errors.

Questionnaire activity for deleted project

Activity item still displays in feed; clicking redirects to Questionnaire detail page; project name shows as "\[Deleted Project\]" or similar placeholder; questionnaire data still accessible.

User clicks "View Active Projects" but has no active projects

Project Listing page displays empty state: "No active projects"; filter shows "Active (0)"; user can create new project or change filter.

Contractors tab contains both Overdue and Failed items

Both types display together in one combined list, distinguished only by the Status badge ("Overdue" vs "Failed"); sorted by due date (most overdue first).

User clicks "Pay" → "Pay Now" on a Failed item but payment fails again

Item remains in Contractors tab; Status stays "Failed"; error message displayed; user can retry "Pay Now" or choose "Mark as Paid".

User clicks "Pay" → "Mark as Paid" for an item paid outside the platform

Item removed from Overdue Payments; status updated to "Paid (Manual)"; no payment processed through the system.

User voids a contractor payment that was actually already paid externally

System voids the item per user action; item removed from list; (PM Note: confirm whether void is reversible).

Contractors tab is empty (no overdue or failed contractor payments)

Tab displays empty state: "No overdue payments" with checkmark icon; Client tab remains unaffected.

## **9\. Acceptance Criteria**

### Functional Requirements

*   Dashboard loads successfully for Agency Owners who have completed all 8 setup steps.
*   Overview section displays four metric cards with accurate counts and percentage changes.
*   Pending Contractor Agreements section displays pending contractors; "Send Reminder" and "Send All" buttons functional; 24-hour rate limit enforced.
*   Pending Counter Sign section displays agreements awaiting counter-signature; "Counter Sign" button opens agreement; counter-signing workflow completes successfully; emails sent.
*   Profit & Loss section displays if subscribed and Stripe connected; locked state displayed otherwise; time period selector functional; chart updates dynamically.
*   New Leads section displays recent leads; "View all" link opens modal and navigates to Leads page.
*   Calendar widget displays upcoming events; "Connect Google Calendar" button initiates OAuth and saves tokens; "Connect Calendly" button initiates OAuth and saves tokens; buttons change to "Manage Settings" after connection.
*   Events section displays four filter tabs; filters work correctly; count badges accurate; "Reminder" button opens modal with Pending/Accepted tabs; SMS reminders sent successfully.
*   Activity feed displays Proposals, Contracts, Invoices, Payments, Questionnaires; clicking activity item redirects to Activity detail page; "View Active Projects" link redirects to Project Listing page; payment format shows client name, amount, invoice number.
*   Unread Messages section displays unread messages; "View" button opens modal; message marked as read after viewing.
*   Overdue Payments section displays Clients and Contractors tabs; data accurate; "View all payments" links navigate correctly.
*   Contractors tab displays a combined list of overdue unpaid invoices and failed payments, distinguished by a Status badge ("Overdue" / "Failed"), with columns: Status, Number, Due Date, Amount Due, Project Name, Action.
*   Contractors tab each row offers "Pay" and "Void" actions; clicking "Pay" presents "Pay Now" and "Mark as Paid" options; each action updates status and removes the item from the list on success.
*   Client tab remains unchanged (overdue client invoices only).
*   New Contractors section displays recent contractors; "Set Up User" button navigates to contractor profile.
*   Theme toggle functional; preference saved.
*   Greeting and quote display correctly; quote changes on page load.

### Data Consistency Rules

*   All metric counts and percentages calculated accurately from database queries.
*   Trial banner and promotional card NOT displayed for existing users (setup complete and/or subscribed).
*   Profit & Loss data sourced from Stripe API; matches financial records.
*   SMS reminder rate limit enforced (1 per contractor per 24 hours).
*   Contractor agreement reminder rate limit enforced (1 per contractor per 24 hours).
*   Google Calendar and Calendly OAuth tokens securely stored; connections persist across sessions.
*   Activity feed displays most recent activities first (reverse chronological order).
*   Payment activities include correct client name, amount, and invoice number.
*   Questionnaire activities link to correct Questionnaire detail page.

### User Actions and System Flow Validations

*   Clicking metric cards navigates to correct filtered detail pages.
*   Clicking "Send Reminder" sends email and disables button for 24 hours.
*   Clicking "Send All" sends batch emails and disables all buttons.
*   Clicking "Counter Sign" opens agreement; completing signature updates status and sends emails.
*   Selecting Profit & Loss time period updates chart without page refresh.
*   Clicking filter tabs in Events section updates table correctly.
*   Clicking "Reminder" in Events opens modal; selecting contractors and clicking "Resend SMS" sends SMS.
*   Clicking activity items redirects to Activity detail page (not just activity listing).
*   Clicking "View Active Projects" redirects to Project Listing page with active filter applied.
*   Clicking "Connect Google Calendar" and "Connect Calendly" initiates OAuth flows and saves tokens correctly.

## **10\. Manual Test Cases**

**Test Case File:** TestCases\_Dashboard\_Existing\_Users\_Agency\_Owner\_v2.xlsx

## **11\. Dependencies**

**Dependency Type**

**Description**

**Expected Behavior if Dependency Fails**

User Authentication Service

Verify user identity and session.

User redirected to login page; Dashboard does not load.

Database

Store and retrieve all Dashboard data.

Dashboard fails to load; error message displayed with retry option.

Stripe API

Retrieve Profit & Loss financial data; verify Stripe connection status.

Profit & Loss section displays error message or locked state; other sections function normally.

Email Service (SMTP)

Send contractor reminder emails.

Reminders fail to send; error message displayed; retry available.

SMS Gateway

Send SMS reminders to contractors.

SMS reminders fail; error message displayed; retry available.

Google Calendar API

Google Calendar OAuth and event sync.

Google Calendar connection fails; error message displayed; retry available; other features unaffected.

Calendly API

Calendly OAuth and event sync.

Calendly connection fails; error message displayed; retry available; other features unaffected.

Leads Module

Provide lead data for New Leads section.

New Leads section displays error or empty state; rest of Dashboard functions normally.

Tasks Module

Provide task data for Overdue Tasks metric.

Overdue Tasks metric displays 0 or error; other metrics function normally.

Email/Messages Module

Provide message data for Unread Messages section.

Unread Messages section displays error or empty state; rest of Dashboard functions.

Invoices Module

Provide invoice and payment data for Revenue metric, Overdue Payments, Activity feed.

Revenue metric, Overdue Payments, and Payment activities fail to load or show errors; other sections function.

Projects/Events Module

Provide event data for Events section and Calendar widget.

Events section and Calendar widget display errors or empty states; other sections function.

Contractors Module

Provide contractor data for Pending Contractor Agreements, New Contractors, Counter Sign sections.

Related sections display errors or empty states; other sections function.

Activity Logging Service

Track and display client-side activities (proposals, contracts, invoices, payments, questionnaires).

Activity feed displays error or empty state; other sections function normally.

Document Service

Load service agreements for counter-signing.

Counter-signing fails; error message displayed; user can retry.

Electronic Signature Service

Apply counter-signatures to agreements.

Signature fails; error message displayed; user remains on signing page.

## **12\. References**

### Figma Links

*   **Dashboard - Existing User (Owner):** Dashboard\_-\_Owner.png (uploaded screenshots: images 2-4)
*   **Questionnaire Detail Page:** 1774556598224\_image.png (uploaded screenshot: image 5)

### Meeting Transcript

*   **Dashboard Meeting - January 3, 2026:** Dashboard\_Jan\_3\_\_2026.pdf

### Related FRDs

*   **FRD #1:** Dashboard - New Users (Agency Owner Role)
*   **FRD #3:** Dashboard - Team Members (Admin & Project Manager)

**Document Version:** 2.2 (Updated)  
**Last Updated:** July 1, 2026  
**Author:** Business Analyst  
**Reviewers:** Product Manager, Lead Developer, QA Lead, UX Designer

**End of FRD - Dashboard - Existing Users (Agency Owner Role)**

3\. Dashboard - Other Roles (Admin & PM)

# **Functional Requirements Document (FRD)**

# **Dashboard - Team Members (Admin & Project Manager)**

## **1\. Module Overview**

### Module Name

Dashboard - Team Members (Admin & Project Manager)

### Purpose

The Dashboard provides a role-based operational view for Team Member users (Admin and Project Manager roles), displaying filtered data relevant to their assigned responsibilities. Both roles fall under the "Team Member" category but have different permission levels. Admins can monitor and manage operations within their assigned brands (excluding overall financial analytics), while Project Managers have visibility limited to their specifically assigned projects and attached contractors, enabling effective project oversight without exposing sensitive financial information.

### Business Goals

*   Enable Admins to manage operations for their assigned brands without access to sensitive financial analytics (profit & loss, overall revenue).
*   Allow Project Managers to monitor their assigned projects and attached contractors efficiently.
*   Maintain data security by restricting financial information access to Agency Owners only.
*   Provide actionable insights tailored to each role's responsibilities and scope.
*   Support collaborative workflows while preserving data privacy and role-based access control.
*   Facilitate contractor agreement counter-signing workflow for all team member roles.
*   Display total booked jobs metric to help team members track project commitments without exposing revenue data.
*   Reduce information overload by displaying only relevant data for each user's role and assignments.

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

### Roles with Access

*   **Admin** (Partial Access - Brand-Scoped Team Member)
*   **Project Manager** (Limited Access - Project-Scoped Team Member)

**Note:** Both Admin and Project Manager are classified as "Team Members" with different permission levels.

### Granular Permissions

**Permission Type**

**Admin**

**Project Manager**

View Dashboard

✅ Yes

✅ Yes

View Overview Metrics (Leads, Tasks, Messages, Booked Jobs)

✅ Yes (brand-scoped)

✅ Yes (project-scoped)

View Total Booked Jobs Metric

✅ Yes

✅ Yes

View Revenue Metric

❌ No

❌ No

View Profit & Loss Chart

❌ No

❌ No

View Pending Contractor Agreements

✅ Yes (brand-scoped)

✅ Yes (project-scoped)

Send Contractor Agreement Reminders

✅ Yes (brand-scoped)

✅ Yes (project-scoped)

View Pending Counter Sign

✅ Yes (assigned contracts)

✅ Yes (assigned contracts)

Counter-Sign Service Agreements

✅ Yes (if assigned)

✅ Yes (if assigned)

View New Leads Table

✅ Yes (brand-scoped)

✅ Yes (project-scoped)

View Calendar Widget

✅ Yes (brand-scoped)

✅ Yes (project-scoped)

View Events Section (All Filters)

✅ Yes (brand-scoped)

✅ Yes (project-scoped)

Send SMS Event Reminders

✅ Yes (brand-scoped)

✅ Yes (project-scoped)

View Activity Feed

✅ Yes (Proposals, Contracts, Invoices, Payments — brand-scoped)

✅ Yes (Proposals, Contracts, Invoices, Payments — project-scoped)

View Unread Messages

✅ Yes (brand-scoped)

✅ Yes (project-scoped)

View Overdue Payments

✅ Yes (brand-scoped)

❌ No

View New Contractors

✅ Yes (brand-scoped)

❌ No

View Trial Period Banner

❌ No

❌ No

View Setup Checklist

❌ No

❌ No

View Subscription Prompts

❌ No

❌ No

## **3\. User Flow**

### 3.1 Admin User Flow

3.1.1 **The Admin user logs into their account** and is redirected to the Dashboard page.

3.1.2 **The system loads the Dashboard** and filters all data to show only projects/events/contractors from the Admin's assigned brands.

3.1.3 **The system displays the Overview section** with four metric cards: New Leads, Overdue Tasks, Unread Messages, Total Booked Jobs.

3.1.4 **The user views metric cards** showing counts and percentage changes for their assigned brands only.

3.1.5 **The user views the Pending Contractor Agreements section** displaying contractors from assigned brands with unsigned agreements.

3.1.6 **The user clicks "Send Reminder"** to send email to a contractor.

3.1.7 **The system sends reminder email** and enforces 24-hour rate limit.

3.1.8 **The user views the Pending Counter Sign section** displaying service agreements requiring counter-signature.

3.1.9 **The user clicks "Counter Sign" button** next to an agreement they are assigned to counter-sign.

3.1.10 **The system opens the agreement document** for review and counter-signature.

3.1.11 **The user reviews the agreement** and clicks "Sign" to complete the counter-signature.

3.1.12 **The system applies the counter-signature** and marks the agreement as fully executed.

3.1.13 **The user views the New Leads table** showing leads from assigned brands only.

3.1.14 **The user views the Calendar widget** with events from assigned brands.

3.1.15 **The user views the Events section** with four filter tabs showing events from assigned brands only.

3.1.16 **The user clicks filter tabs** (All, Next 7 Days, Date Pending, Unassigned) to filter events.

3.1.17 **The user clicks "Reminder" button** on an event to view/send SMS reminders to contractors.

3.1.18 **The user views the Activity feed** showing client-side activities from assigned brands (Proposals, Contracts, Invoices, Payments).

3.1.19 **The user clicks on an activity item** to view details.

3.1.20 **The system redirects to the Activity detail page** showing complete activity information.

3.1.21 **The user clicks "View Active Projects" link** in the Activity section.

3.1.22 **The system redirects to the Project Listing page** with active projects from assigned brands.

3.1.23 **The user views Unread Messages** from clients/projects within assigned brands.

3.1.24 **The user views the Overdue Payments section** with Clients and Contractors tabs showing overdue payments from assigned brands' projects.

3.1.25 **The user clicks "View all payments"** and is redirected to Finance module with filters applied for assigned brands.

3.1.26 **The user views New Contractors section** showing contractors from assigned brands.

3.1.27 **The user navigates away** using the sidebar menu to access other modules.

### 3.2 Project Manager User Flow

3.2.1 **The Project Manager logs into their account** and is redirected to the Dashboard page.

3.2.2 **The system loads the Dashboard** and filters all data to show only the Project Manager's assigned projects.

3.2.3 **The system displays the Overview section** with four metric cards: New Leads, Overdue Tasks, Unread Messages, Total Booked Jobs from assigned projects only.

3.2.4 **The user views metric cards** showing counts for their assigned projects only.

3.2.5 **The user views the Pending Contractor Agreements section** displaying contractors from assigned projects with unsigned agreements.

3.2.6 **The user clicks "Send Reminder"** to send email to a contractor attached to their project.

3.2.7 **The system sends reminder email** and enforces 24-hour rate limit.

3.2.8 **The user views the Pending Counter Sign section** displaying service agreements they are assigned to counter-sign.

3.2.9 **The user counter-signs agreements** following the same workflow as Admin (steps 3.1.9-3.1.12).

3.2.10 **The user views the New Leads table** showing leads from assigned projects only.

3.2.11 **The user views the Calendar widget** with events from assigned projects only.

3.2.12 **The user views the Events section** with filter tabs showing events from assigned projects only.

3.2.13 **The user clicks filter tabs** to view events based on status.

3.2.14 **The user clicks "Reminder" button** to view/send SMS reminders for events in assigned projects.

3.2.15 **The user views the Activity feed** showing client-side activities from assigned projects only (Proposals, Contracts, Invoices, Payments).

3.2.16 **The user clicks on activity items** or "View Active Projects" link (same navigation as Admin).

3.2.17 **The user views Unread Messages** from assigned projects only.

3.2.18 **The Overdue Payments section is hidden** (Project Managers don't view payment data).

3.2.19 **The New Contractors section is hidden** (Project Managers don't view contractor onboarding).

3.2.20 **The user navigates away** using the sidebar menu.

## **4\. Functional Logic**

### 4.1 Role-Based Data Filtering

#### **4.1.1 Admin Data Scope**

*   All Dashboard data is filtered to show only information from the Admin's assigned brands.
*   Assigned brands are configured by the Agency Owner in the Admin's user profile settings.
*   The system queries the database with a brand filter applied to all data retrieval operations.
*   Admins can see all projects, events, leads, contractors, and messages within their assigned brands.
*   Admins cannot see data from brands they are not assigned to.
*   If an Admin is assigned to multiple brands, data from all assigned brands is aggregated and displayed.

#### **4.1.2 Project Manager Data Scope**

*   All Dashboard data is filtered to show only information from the Project Manager's assigned projects.
*   Assigned projects are configured by the Agency Owner or Admin when creating/editing the Project Manager's user account.
*   The system applies a project-level filter to all data queries.
*   Project Managers can only see leads, events, messages, and contractors related to their assigned projects.
*   Project Managers cannot see data from projects they are not assigned to.
*   If a Project Manager is assigned to multiple projects, data from all assigned projects is aggregated.

#### **4.1.3 Contractor Visibility Rules**

*   **Admin:** Can see all contractors from assigned brands, regardless of who invited them.
*   **Project Manager:** Can see contractors attached to their assigned projects (regardless of who invited them).
*   This ensures Project Managers have visibility into all contractors working on their projects for effective project management.

### 4.2 Overview Section - Role-Based Metrics

#### **4.2.1 Admin Overview**

*   Displays four metric cards: New Leads, Overdue Tasks, Unread Messages, Total Booked Jobs.
*   **Revenue card and Profit & Loss section are NOT displayed** (financial data restricted to Agency Owners).
*   Counts are calculated based on assigned brands only.
*   Percentage changes compare last 30 days vs. previous 30 days within assigned brands.
*   Each card is clickable and redirects to filtered detail pages (showing assigned brands only).
*   Total Booked Jobs shows the count of all confirmed/booked jobs for the current year within assigned brands.

#### **4.2.2 Project Manager Overview**

*   Displays four metric cards: New Leads, Overdue Tasks, Unread Messages, Total Booked Jobs.
*   **Revenue card and Profit & Loss section are NOT displayed.**
*   Counts are calculated based on assigned projects only.
*   Percentage changes compare last 30 days vs. previous 30 days within assigned projects.
*   Each card redirects to filtered detail pages (showing assigned projects only).
*   Total Booked Jobs shows the count of all confirmed/booked jobs for the current year within assigned projects.

#### **4.2.3 Total Booked Jobs Metric**

*   NEW metric visible to Admin and Project Manager only (NOT visible to Agency Owner).
*   Replaces the "2025 Revenue" card for team member roles.
*   Displays the total number of confirmed/booked jobs for the current year (2026 in this case).
*   Calculated by counting all projects/events with "Booked" or "Confirmed" status within the user's scope.
*   Helps team members track workload and commitments without exposing sensitive revenue data.
*   Includes a percentage change indicator comparing last 30 days vs. previous 30 days.
*   Card is clickable and redirects to a filtered project listing showing booked jobs.

### 4.3 Pending Contractor Agreements

#### **4.3.1 Admin Access**

*   The Pending Contractor Agreements section is visible to Admins.
*   Displays contractors from assigned brands who have not signed their service agreements.
*   Admins can send individual or batch reminder emails to pending contractors.
*   "Send Reminder" button sends email with 24-hour rate limit enforcement.
*   "Send All" button sends reminders to all pending contractors from assigned brands.
*   Functionality identical to Agency Owner (documented in FRD #2), but scoped to assigned brands.

#### **4.3.2 Project Manager Access**

*   **The Pending Contractor Agreements section IS visible** to Project Managers (UPDATED).
*   Displays contractors from assigned projects who have not signed their service agreements.
*   Project Managers can send individual reminder emails using "Send Reminder" button.
*   Project Managers can send batch reminders using "Send All" button.
*   Rate limit: 24 hours per contractor for both individual and batch reminders.
*   Only shows contractors attached to the Project Manager's assigned projects.
*   If a project has multiple contractors, only those with pending agreements are listed.

### 4.4 Pending Counter Sign Section (NEW)

#### **4.4.1 Section Purpose**

*   Displays service agreements that require counter-signature to become fully executed.
*   Appears after contractors sign their service agreements; the agency representative must counter-sign to complete the contract.
*   This section is separate from "Pending Contractor Agreements" which tracks unsigned contractor agreements.
*   Visible to Agency Owner, Admin, and Project Manager roles.

#### **4.4.2 Counter-Signer Assignment Logic**

*   **Auto-Send Agreements:** When service agreements are automatically sent to contractors, the counter-signer is automatically assigned to the Agency Owner.
*   **Manual Send Agreements:** When an agency representative manually sends a service agreement, the sender becomes the assigned counter-signer.
    *   If Agency Owner sends → Agency Owner assigned as counter-signer
    *   If Admin sends → Admin assigned as counter-signer
    *   If Project Manager sends → Project Manager assigned as counter-signer
*   This assignment is recorded in the database at the time the agreement is sent.

#### **4.4.3 Section Display Logic**

*   The Pending Counter Sign section is visible to all three roles (Owner, Admin, PM).
*   Each role sees only the agreements they are assigned to counter-sign OR agreements within their scope:
    *   **Agency Owner:** Sees all pending counter-sign agreements agency-wide (since auto-sent agreements default to Owner).
    *   **Admin:** Sees agreements from assigned brands that they are assigned to counter-sign OR that were auto-sent (Owner-assigned) within their brands.
    *   **Project Manager:** Sees agreements from assigned projects that they are assigned to counter-sign.
*   If there are no agreements awaiting counter-signature, the section displays an empty state: "No agreements awaiting your signature."

#### **4.4.4 Section Content**

*   Each agreement entry shows:
    *   Contractor name and profile picture/initials
    *   Project name the agreement is associated with
    *   Date the contractor signed the agreement
    *   Status indicator: "Awaiting Your Counter-Signature" or "Pending Counter Sign"
    *   "Counter Sign" button in the Action column
    *   Optional: "View Agreement" link to preview the document before signing
*   The section displays a maximum of 5 agreements; if more exist, a "View all" link is provided.

#### **4.4.5 Counter-Signing Workflow**

*   When the user clicks the "Counter Sign" button, the system opens the service agreement document for review.
*   The document may open in a modal overlay or redirect to a dedicated signing page (PM: confirm preferred approach).
*   The user reviews the agreement terms, contractor signature, and all contract details.
*   The user clicks "Sign" or "Apply Signature" to complete the counter-signature.
*   The system applies the user's electronic signature with timestamp and IP address logging.
*   The agreement status is updated to "Fully Executed" or "Complete" in the database.
*   The agreement is removed from the Pending Counter Sign section.
*   Both the contractor and the counter-signer receive email confirmation of the fully executed agreement.
*   The fully executed agreement is stored in the Documents module and linked to the project.

#### **4.4.6 Reminder Functionality**

*   Optional: "Send Reminder" button may be available if the agreement has been pending counter-signature for more than 48 hours.
*   Clicking "Send Reminder" sends an email notification to the assigned counter-signer reminding them to review and sign.
*   Rate limit: One reminder per agreement per 24 hours to prevent spam.

#### **4.4.7 Error Handling**

*   If the agreement document cannot be loaded, display error: "Unable to load agreement. Please try again or contact support."
*   If the signature submission fails, display error: "Failed to apply signature. Please try again."
*   If the user is no longer assigned as counter-signer (e.g., role changed), display: "You are not authorized to counter-sign this agreement."

### 4.5 Profit & Loss Section

*   **The Profit & Loss section is NOT displayed** to Admins or Project Managers.
*   Financial analytics (profit, loss, income, expenses) are restricted to Agency Owners only.
*   This section is completely hidden from the Dashboard for both Admin and Project Manager roles.
*   Even if Stripe is connected, these roles cannot view financial performance metrics.

### 4.6 New Leads Section

#### **4.6.1 Admin View**

*   Displays leads from assigned brands only.
*   Table columns: Lead Name, Created Date, Contact Information, Lead Source, Action.
*   Maximum 5-6 recent leads displayed.
*   "View all" link opens popup modal, then navigates to Leads page with brand filter applied.

#### **4.6.2 Project Manager View**

*   Displays leads from assigned projects only.
*   Same table structure as Admin.
*   "View all" link navigates to Leads page with project filter applied.

### 4.7 Calendar Widget

#### **4.7.1 Admin View**

*   Displays 3-5 upcoming events from assigned brands.
*   "Go to Calendar" link navigates to Calendar module with brand filter applied.
*   Google Calendar integration available (if configured by Agency Owner).

#### **4.7.2 Project Manager View**

*   Displays 3-5 upcoming events from assigned projects only.
*   "Go to Calendar" link navigates to Calendar module with project filter applied.

### 4.8 Events Section with Filters

#### **4.8.1 Admin View**

*   Four filter tabs: All, Next 7 Days, Date Pending, Unassigned.
*   All tabs display events from assigned brands only.
*   Count badges show filtered counts (e.g., "All 15" shows only assigned brands' events).
*   Unassigned tab shows events from assigned brands with at least one unassigned contractor role.
*   Tooltip on Unassigned tab explains filter criteria.

#### **4.8.2 Project Manager View**

*   Four filter tabs: All, Next 7 Days, Date Pending, Unassigned.
*   All tabs display events from assigned projects only.
*   Count badges reflect assigned projects only.
*   Unassigned tab shows events from assigned projects with unassigned roles.

### 4.9 SMS Reminder System

#### **4.9.1 Admin Access**

*   Admins can view and send SMS reminders for events within assigned brands.
*   "Reminder" button in Events table opens modal with Pending/Accepted tabs.
*   Can select contractors and resend SMS reminders (24-hour rate limit applies).
*   Functionality identical to Agency Owner (FRD #2), scoped to assigned brands.

#### **4.9.2 Project Manager Access**

*   Project Managers can view and send SMS reminders for events in assigned projects.
*   "Reminder" button functionality same as Admin, but scoped to assigned projects.
*   Can manage reminders for contractors assigned to their project events.

### 4.10 Activity Feed (UPDATED)

#### **4.10.1 Admin View**

*   Displays activities from assigned brands only.
*   **Shows client-side activities:** Proposals, Contracts, Invoices, and Payments (including payment schedules).
*   **No financial limitation:** Unlike the earlier restriction, the Admin activity feed now includes invoice and payment activity in full. Invoice activity covers the invoice lifecycle (created, sent, viewed, paid), and payment activity includes payments received and payment schedule updates.
*   **Excludes internal activities:** Task assignments, team member updates, system configuration changes (internal/system events are not shown, as these are not client activities).
*   Each activity entry shows:
    *   Icon representing the activity type (Proposal, Contract, Invoice, Payment)
    *   Description of the action (e.g., "Proposal sent to client", "Contract signed by client", "Invoice #1234 sent", "Payment received from \[Client\]")
    *   Related entity name (client name, project name)
    *   Timestamp (e.g., "2 hours ago", "Yesterday")
    *   Optional action button (e.g., "View Proposal", "Download Contract", "View Invoice", "View Payment")
*   Payment activity format: Client name, paid amount, and invoice number (e.g., "Payment received from John & Monica: $2,500 for Invoice #1234").
*   Maximum 5-7 activities displayed on Dashboard.
*   "View all" link at the bottom of the Activity section.

#### **4.10.2 Project Manager View**

*   Displays activities from assigned projects only (a PM may be assigned to projects across multiple brands, but the feed is scoped to their assigned projects, not the full brand).
*   **Shows client-side activities:** Proposals, Contracts, Invoices, and Payments (including payment schedules) — same activity types as the Admin view, with no financial limitation.
*   **Excludes internal activities** (same internal/system exclusions as Admin).
*   Same display format and functionality as Admin view, including payment activity format.
*   "View all" link navigates to activity history with project filter.

**Note:** Questionnaire activities are NOT shown in the Admin or Project Manager activity feed.

#### **4.10.3 Activity Item Interaction**

*   **Clicking on an activity item:** The system redirects the user to the Activity detail page showing complete information about that specific activity (proposal details, contract terms, invoice breakdown, etc.).
*   **Activity detail page** displays:
    *   Full activity description and context
    *   Related documents (PDF downloads, preview links)
    *   Associated project and client information
    *   Timeline of related activities
    *   Action buttons (e.g., "View Proposal", "Resend Email", "Download PDF")

#### **4.10.4 "View Active Projects" Link**

*   At the bottom of the Activity feed section, a "View Active Projects" link is displayed.
*   **Clicking this link:** The system redirects the user to the Project Listing page.
*   **Project Listing page** displays:
    *   **Admin:** All active projects from assigned brands with appropriate filters applied.
    *   **Project Manager:** All active projects the PM is assigned to.
    *   Projects are filtered by "Active" status (not completed, cancelled, or archived).
    *   Standard project list columns: Project Name, Client, Event Date, Status, Assigned Team, Actions.

#### **4.10.5 Empty State**

*   If there are no recent activities, the Activity feed displays: "No recent activity. Client interactions will appear here."
*   Empty state does not display a CTA button (this is a passive information section).

### 4.11 Unread Messages Section

#### **4.11.1 Admin View**

*   Displays unread messages from clients/projects within assigned brands.
*   Table: Project Name, From, Subject, Date Received, Action.
*   "View" button opens message modal with full content.
*   Messages limited to assigned brands only.

#### **4.11.2 Project Manager View**

*   Displays unread messages from assigned projects only.
*   Same table structure and functionality as Admin.
*   Messages scoped to assigned projects.

### 4.12 Overdue Payments Section

#### **4.12.1 Admin Access**

*   **The Overdue Payments section IS visible** to Admins.
*   Displays two tabs: "Clients" and "Contractors".
*   **Clients tab:** Shows overdue payments from clients to agency for projects within assigned brands (unchanged — overdue client invoices only).
*   **Contractors tab:** Shows contractor payments owed by the agency that are past due within assigned brands, covering two categories in a single combined list:
    *   **Overdue (unpaid) invoices:** Contractor invoices the agency owes and has not attempted to pay, where the due date has passed.
    *   **Failed payments (overdue):** Contractor payments the agency attempted to process but which failed, and where the due date has now passed.
    *   Both categories appear together in one list, distinguished by the **Status** column.
    *   **Table columns:** Status, Number, Due Date, Amount Due, Project Name, Action.
        *   **Status:** Badge showing **"Overdue"** (unpaid invoice past due) or **"Failed"** (attempted payment that failed and is now past due).
        *   **Number:** Contractor invoice/payment reference number (e.g., "DDD-CTR-1779270068"); clickable to payment detail page.
        *   **Due Date:** Date the payment was due (e.g., "Wed, 05/27/2026").
        *   **Amount Due:** Outstanding amount owed, currency formatted.
        *   **Project Name:** Associated project with event-type badge; scoped to assigned brands.
        *   **Action:** "Pay" and "Void" buttons.
    *   **Pay Action:** Clicking "Pay" presents two options — **Pay Now** (process/re-attempt payment via processor) and **Mark as Paid** (manually mark as paid for payments made outside the platform). On success, the item is removed from the list and status updated.
    *   **Void Action:** Clicking "Void" cancels the contractor invoice/payment; on confirmation, the item is removed from the list and status updated to "Voided".
*   All Contractors tab data is scoped to the Admin's assigned brands.
*   Admins can view payment status but **cannot see Profit & Loss or overall revenue metrics**.
*   "View all payments" links redirect to Finance module with brand filter applied.
*   This allows Admins to manage invoices and payments for their assigned brands without seeing overall financial performance.

#### **4.12.2 Project Manager Access**

*   **The Overdue Payments section is NOT displayed** to Project Managers.
*   Project Managers do not have permissions to view payment data.
*   This section is completely hidden for Project Manager role.

### 4.13 New Contractors Section

#### **4.13.1 Admin Access**

*   **The New Contractors section IS visible** to Admins.
*   Displays all contractors from assigned brands with pending setup.
*   Shows contractor name, role, location, and "Set Up User" button.
*   Admins can complete contractor onboarding for assigned brands.
*   Maximum 3-5 contractors displayed.
*   "View all" link navigates to full Contractors management page with brand filter.

#### **4.13.2 Project Manager Access**

*   **The New Contractors section is NOT displayed** to Project Managers.
*   Project Managers do not have access to contractor onboarding functionality.
*   This section is completely hidden for Project Manager role.
*   Note: Project Managers CAN see contractors in the Pending Contractor Agreements section (those attached to their projects), but NOT in the New Contractors onboarding section.

### 4.14 Hidden Sections for Team Member Roles

The following sections are **NOT displayed** to Admins or Project Managers:

*   Trial Period Banner (only Agency Owners see subscription status)
*   Setup Checklist ("Let's get you all set up" card)
*   Promotional Upgrade Cards (subscription prompts)
*   Email Verification Modal (handled at Agency Owner level)
*   Profit & Loss Section (financial analytics restricted to Owner)
*   2025 Revenue Card in Overview (replaced by Total Booked Jobs for team members)

### 4.15 Navigation and Interaction

*   Left sidebar menu accessible with role-based module visibility.
*   "Dashboard" menu item highlighted when viewing Dashboard.
*   Top navigation: search, notifications, Tasks icon, profile, theme toggle, "Create" button.
*   "Create" dropdown may have role-based options (e.g., Project Managers may not see "Create Contractor").
*   All "View all" links open popup modals first, then navigate with role-based filters applied.
*   **PM Note:** Confirm the exact content and structure of popup modals for "View all" links.
*   Data refreshes on page load, not in real-time.

### 4.16 Empty States

*   If an Admin has no assigned brands, all sections display empty states: "No data available. Contact your administrator."
*   If a Project Manager has no assigned projects, Dashboard shows empty states: "No projects assigned yet. Contact your administrator."
*   If assigned brands/projects have no data, respective sections show standard empty states (as documented in FRD #1).
*   Empty states for missing data include appropriate messaging without CTAs (e.g., "No recent activities" does not have a "Create Activity" button).

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

**Field Name**

**Field Type**

**Validation Rules**

New Leads Count

Calculated Number

System-calculated based on role scope (brand or project); display-only.

Overdue Tasks Count

Calculated Number

System-calculated based on role scope; display-only.

Unread Messages Count

Calculated Number

System-calculated based on role scope; display-only.

Total Booked Jobs

Calculated Number

System-calculated count of confirmed/booked jobs for current year within role scope; display-only.

Percentage Change

Calculated Percentage

Last 30 days vs previous 30 days within role scope; display-only.

Event Filter Tab

Tab Selection

All, Next 7 Days, Date Pending, Unassigned; default "All".

SMS Reminder Selection

Checkbox

Multiple selections allowed; scoped to role permissions.

Counter-Signer Assignment

System-Assigned

Auto: Agency Owner; Manual: Sender of agreement; stored in database.

**Note:** All metrics are automatically filtered by the system based on user role (Admin = assigned brands; Project Manager = assigned projects).

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

**Success Scenario**

**Success Message**

**Trigger Condition**

**Post-Success Action**

Contractor Reminder Sent (Admin/PM)

"Reminder email sent to \[Contractor Name\] successfully."

User sends reminder for contractor in scope.

Button disabled 24 hours; timestamp recorded.

Batch Reminders Sent (Admin/PM)

"Reminder emails sent to \[X\] contractors successfully."

User clicks "Send All" in scope.

All buttons disabled; status updated.

SMS Reminders Resent (Admin/PM)

"SMS reminders resent to \[X\] contractors successfully."

User resends SMS for events in scope.

Modal updated; 24-hour cooldown.

Event Date Set (Admin/PM)

"Event date set successfully for \[Event Name\]."

User sets date for Date Pending event in scope.

Event moved to date filter.

Counter-Signature Applied

"Agreement counter-signed successfully. \[Contractor Name\]'s service agreement is now fully executed."

User completes counter-signature.

Agreement removed from Pending Counter Sign; moved to executed agreements; email sent to contractor and counter-signer.

Contractor Payment Paid (Pay Now)

"Payment of \[Amount\] to \[Contractor Name\] processed successfully."

Admin clicks "Pay" → "Pay Now" in Contractors tab; payment processed.

Item removed from Overdue Payments; status updated to "Paid"; scoped to assigned brands.

Contractor Payment Marked as Paid

"Payment for \[Number\] marked as paid."

Admin clicks "Pay" → "Mark as Paid"; confirms manual payment.

Item removed from Overdue Payments; status updated to "Paid (Manual)".

Contractor Payment Voided

"Payment \[Number\] has been voided."

Admin clicks "Void"; confirms void.

Item removed from Overdue Payments; status updated to "Voided".

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

**Error Scenario**

**Error Message**

**Trigger Condition**

**Required Action**

**System Response**

No Assigned Brands/Projects

"No data available. Contact your administrator."

User has no brand/project assignments.

Contact Agency Owner to assign brands/projects.

Empty state displayed across all sections.

Reminder Email Failed

"Failed to send reminder email. Please try again."

SMTP error.

Retry; contact support.

Error toast; retry available.

SMS Reminder Failed

"Failed to send SMS reminder. Please try again."

SMS gateway error.

Retry; contact support.

Error toast; retry available.

Unauthorized Access

"You do not have permission to view this data."

User attempts to access out-of-scope data.

Contact administrator.

Redirect or error page.

Counter-Sign Document Load Failed

"Unable to load agreement. Please try again or contact support."

Agreement document fetch fails.

Retry or contact support.

Error toast; "Counter Sign" button remains clickable for retry.

Contractor Payment (Pay Now) Failed

"Payment to \[Contractor Name\] failed. Please try again."

Payment processor declines or errors during "Pay Now".

Retry "Pay Now" or use "Mark as Paid" if paid externally.

Error toast; item remains with "Failed" status; retry available.

Void Action Failed

"Failed to void payment \[Number\]. Please try again."

Database/network error during void.

Retry the void action.

Error toast; item remains in list; error logged.

Counter-Signature Submission Failed

"Failed to apply signature. Please try again."

Database update or API error during signing.

Retry signing process.

Error toast; user remains on signing page; agreement not marked complete.

Unauthorized Counter-Sign Attempt

"You are not authorized to counter-sign this agreement."

User not assigned as counter-signer or role changed.

Contact administrator or agreement sender.

Error modal; "Counter Sign" button disabled or hidden.

Network Error

"Unable to load Dashboard data. Please check connection."

Network failure.

Refresh; check connection.

Error message; retry option.

## **8\. Edge Cases**

**Edge Case**

**Expected Behavior**

Admin Contractors tab contains both Overdue and Failed items

Both types display together in one combined list (scoped to assigned brands), distinguished by Status badge ("Overdue" / "Failed").

Admin clicks "Pay" → "Pay Now" on a Failed item but payment fails again

Item remains in Contractors tab with "Failed" status; error message displayed; Admin can retry "Pay Now" or use "Mark as Paid".

Admin clicks "Pay" → "Mark as Paid" for item paid outside platform

Item removed from Overdue Payments; status updated to "Paid (Manual)"; no payment processed through the system.

Admin voids a contractor payment

Item removed from list; status updated to "Voided" (PM Note: confirm whether void is reversible).

PM attempts to access Contractors tab actions via URL

Access denied; Overdue Payments section is hidden from PM entirely; no Pay/Void actions available.

Admin assigned to 0 brands

All Dashboard sections show empty state: "No data available. Contact your administrator."

PM assigned to 0 projects

All Dashboard sections show empty state: "No projects assigned yet. Contact your administrator."

Admin's brand assignment removed while viewing Dashboard

Data remains visible until page refresh; after refresh, brand data hidden and empty state displayed.

PM's project assignment removed

Same behavior; data visible until refresh, then hidden with empty state.

Contractor attached to PM's project signs agreement

Contractor appears in PM's Pending Contractor Agreements section; PM can send reminders.

Admin views Overdue Payments but has no financial role

Can view client and contractor overdue payments for assigned brands; cannot see profit/loss or revenue totals.

PM attempts to access Overdue Payments via URL

System denies access; redirects to Dashboard or shows "Permission denied" error.

PM attempts to access New Contractors via URL

System denies access; redirects to Dashboard or shows "Permission denied" error.

Admin has brands with no events

Events section shows empty state: "No events yet."

Agreement auto-sent, then manually resent by Admin

Counter-signer remains as Agency Owner (first assignment takes precedence); Admin's resend does NOT reassign counter-signer.

Counter-signer role changed after assignment

Agreement remains assigned to original counter-signer; new counter-signer cannot sign; original counter-signer retains access even with changed role (until agreement is completed or reassigned by Owner).

Contractor signs agreement while counter-signer viewing Dashboard

Agreement appears in Pending Counter Sign section after page refresh; real-time notification optional (PM: confirm).

Multiple agreements pending for same project

All agreements listed separately in Pending Counter Sign section; user can counter-sign in any order.

User counter-signs agreement from mobile device

System supports mobile-responsive signing interface; signature capture works on touch devices; all functionality available.

Total Booked Jobs count is zero

Card displays "0" with N/A for percentage change (no historical data); card still clickable (redirects to empty project listing).

Activity feed has only old activities (>30 days)

Activities still displayed with timestamps; no artificial filtering by age; "View all" shows complete history.

## **9\. Acceptance Criteria**

### Functional Requirements

*   Dashboard loads successfully for Admin and Project Manager roles.
*   Overview section displays four metric cards: New Leads, Overdue Tasks, Unread Messages, **Total Booked Jobs** (no Revenue card for either role).
*   **Total Booked Jobs metric visible to Admin and PM** showing count of confirmed/booked jobs for current year within role scope.
*   **Profit & Loss section is NOT visible** to Admins or Project Managers.
*   **Pending Contractor Agreements section visible to BOTH Admin and PM** (scoped to assigned brands/projects); both can send reminders.
*   **Pending Counter Sign section visible to all three roles** (Owner, Admin, PM); displays agreements awaiting counter-signature; "Counter Sign" button functional.
*   Counter-signer assignment logic works correctly: auto-send → Owner, manual send → sender.
*   Counter-signing workflow completes successfully: document loads, signature applied, agreement marked executed, emails sent.
*   **Overdue Payments section visible to Admin** (scoped to assigned brands); **hidden from PM**.
*   **New Contractors section visible to Admin** (scoped to assigned brands); **hidden from PM**.
*   Admins see data from assigned brands only; all sections filtered correctly.
*   Project Managers see data from assigned projects only; all sections filtered correctly.
*   Project Managers see contractors attached to their assigned projects in Pending Contractor Agreements section.
*   **Activity feed shows client-side activities** (Proposals, Contracts, Invoices, Payments including payment schedules) for both roles; no financial limitation; excludes only internal/system activities. Questionnaires are not shown.
*   Clicking activity item redirects to Activity detail page; "View Active Projects" link redirects to Project Listing.
*   Events section with four filters works correctly with role-based scoping.
*   SMS reminder system functional for both roles within their scope.
*   Trial banner, setup checklist, subscription prompts NOT displayed to either role.
*   "View all" links navigate with appropriate filters (brand filter for Admin, project filter for PM).
*   Empty states displayed correctly when no assignments or no data.

### Data Consistency Rules

*   All data filtered by role scope (brand or project) before display.
*   Database queries include role-based filters to prevent unauthorized data access.
*   Contractor visibility enforced (Admin sees all brand contractors; PM sees contractors attached to assigned projects).
*   Financial data completely hidden from both roles (no profit/loss, no overall revenue).
*   Admin can view project-level payment status without seeing overall financial metrics.
*   Total Booked Jobs count accurately reflects confirmed/booked jobs within role scope.
*   Activity feed consistently excludes financial activities for all team member roles.
*   Counter-signer assignments persist correctly in database; original assignment not overwritten by resends.

### User Actions and System Flow Validations

*   Admins can send contractor agreement reminders; PMs can send contractor agreement reminders (both scoped).
*   Both roles can send SMS event reminders within their scope.
*   Both roles can counter-sign service agreements they are assigned to.
*   Navigation between modules maintains role-based filters.
*   Attempting to access out-of-scope data results in permission error.
*   Activity item clicks and "View Active Projects" navigations work correctly.

## **10\. Manual Test Cases**

**Test Case File:** TestCases\_Dashboard\_Team\_Members\_Admin\_PM.xlsx

## **11\. Dependencies**

**Dependency**

**Description**

**Failure Behavior**

Authentication Service

Verify user role and scope.

Redirect to login.

Role Assignment Data

Required to determine brand/project scope.

Empty state if no assignments.

Email Service (SMTP)

Send contractor reminders (Admin and PM).

Error message; retry available.

SMS Gateway

Send/receive SMS reminders.

Error message; reminders not sent.

Database

Store/retrieve role-scoped data.

Error; retry option.

Document Service

Load service agreements for counter-signing.

Error message; cannot counter-sign.

Electronic Signature Service

Apply counter-signatures to agreements.

Error message; signature fails.

Project Management Module

Calculate Total Booked Jobs count.

Metric shows 0 or error; cannot calculate.

Activity Logging Service

Track and display client-side activities.

Activity feed empty or shows error.

## **12\. References**

*   **Figma:** Dashboard\_-_Admin.png, Dashboard_\-\_PM.png (uploaded screenshots)
*   **Transcript:** Dashboard\_Jan\_3\_\_2026.pdf, Dashboard-d06b8a5b-37a7.json
*   **Related FRDs:** FRD #1 (New Users), FRD #2 (Existing Users - Agency Owner)

**Document Version:** 2.2 (Updated)  
**Last Updated:** July 1, 2026  
**Author:** Business Analyst

**End of FRD - Dashboard - Team Members (Admin & Project Manager)**