Chunks — 4. Brands

Brand Management

#

#

#

#

#

# **Brand Management**

**Functional Requirement Document**

**BA & Ideation: Deval Chauhan**

**Reviewed By: Keval Gajjar**

**Updated Date:31 December 2025  
Status:**

**Version: 1.0**

# **Brands Management Module - FRD Summary**

**Module:** Brands Management | **FRDs:** 7 | **Test Cases:** 228 | **Date:** December 31, 2024

## **FRD #1: Brand Listing**

*   Centralized brand overview under Settings → Brands
*   **Columns:** Brand Logo/Icon, Name, Creation Date, Projects, Upcoming Events, Contractors, Actions
*   **Actions:** Configure button navigates to Brand Settings
*   **Sorting:** All columns except Actions (ascending/descending); default = newest first
*   **Pagination:** 10/20/30/50/100 rows per page
*   **Empty State:** "No brands found" with "Setup Brand" button
*   **Access Control:**
    *   Agency Owner: View all, create brands (within subscription limit)
    *   Admin: View all, read-only (cannot create)
    *   Team Member: View assigned brands only, read-only
*   **Row Click:** Navigate to Brand Settings/Configuration page
*   **New Brand Button:** Only functional for Agency Owners; blocked for Admin/Team Member with permission error
*   **Subscription Limit Modal:** Triggers when brand limit reached; "Upgrade Plan" redirects to billing
*   **Brand Icons:** Secondary logo (square) if uploaded; else Main logo cropped to fit

## **FRD #2: Brand Setup / Create New Brand**

*   **5-Step Wizard:** Basic Information → Customize Appearance → Select Events → Business Information & Service Area → Social Media Links
*   **Entry Points:** Onboarding stepper, Settings → Brands → New Brand, Empty state, Module prompts
*   **First Brand Auto-Fill:** Business Name, Website, Phone Number from agency profile (editable)
*   **Subsequent Brands:** Empty fields, manual entry required
*   **No Skip:** Must complete steps sequentially; backward navigation allowed (data preserved)
*   **No Draft Save:** Exit without completion = all data lost

**Step 1 - Basic Information:**

*   Brand Name (1-100 chars, unique within agency, case-insensitive)
*   Website (URL format: https://, http://, [www](http://www).)
*   Phone Number (international formats supported)

**Step 2 - Customize Appearance:**

*   Main Logo: Mandatory, 5MB max, PNG/JPG/JPEG/WEBP, fixed aspect ratio crop (PM: confirm 3:1 or 4:1)
*   Secondary Logo: Optional, 5MB max, 1:1 square crop
*   Brand Color: Mandatory, HEX or RGB picker with live preview
*   Default Cover Photo: Mandatory, 15MB max, wide aspect ratio crop (PM: confirm 16:9); full image saved to Library + cropped as brand default

**Step 3 - Select Events:**

*   Default event types (PM: complete list needed - visible: Wedding, Corporate Event, Birthday)
*   Unlimited custom events (unique, non-blank)
*   At least 1 event required (default or custom)

**Step 4 - Business Information & Service Area:**

*   **Google Maps API:** Auto-fill Street Address, City, State, Country, Zip (all mandatory)
*   Editable fields: Street Address and Zip only; City/State/Country read-only after selection
*   API failure: Warning + manual fallback (PM: confirm if allowed)
*   **Service Areas:** Free-form text tags, min 1 required, no blanks/duplicates (case-insensitive)

**Step 5 - Social Media Links:**

*   8 platforms: Facebook, Instagram, LinkedIn, X, Pinterest, Vimeo, YouTube, TikTok (all optional)
*   URL validation: Must start with https:// or [www](http://www).
*   One link per platform max

**Completion:** "Finish" commits to database → Navigate to Brand Listing or Settings page

## **FRD #3: Brand Settings / Configuration**

*   **5 Sections:** Shooting Guide, General, Appearance, Business Information, Social Media
*   **Access:** Brand Listing → Configure button or row click

**Permissions:**

*   Agency Owner: Full edit access to all sections
*   Admin: Read-only (General, Appearance, Business Info); Full access (Shooting Guide, Social Media)
*   Team Member: Read-only all sections

**Shooting Guide Section:**

*   Upload per service type: Photo, Video, Content (separate PDFs)
*   File: PDF only, 15MB max
*   Replace: Old guide soft-deleted (user no access); new guide uploaded
*   Contractor Access: Download from Contractor Portal → Event Details tab (Developer: Follow Contractor Portal FRD)

**General Section:**

*   Brand Name (1-100 chars, unique within agency), Website (URL format), Phone Number (mandatory)
*   Changes propagate to: Brand Listing, Projects, Proposals, Packages, Lead Forms, Reports

**Appearance Section:**

*   Main/Secondary Logo: Change with re-cropping (same validations as setup)
*   Brand Color: HEX/RGB with live preview
*   Default Cover Photo: 15MB max; full to Library, cropped as default; applies to new projects only (existing unchanged)
*   Propagation: Logos → Proposals/Contracts/Packages/Emails; Color → Materials with "Use Brand Color"; Cover → New projects

**Business Information Section:**

*   Editable: Street Address and Zip (Owner only)
*   Read-only: City, State, Country (locked from Google Maps selection)
*   Propagation: Proposals, Contracts, Invoices, Lead Forms

**Social Media Section:**

*   Edit all 8 platforms; same URL validation as setup
*   Propagation: Email footers, Proposals, Client portals

## **FRD #4: Brand Domain Name Section**

*   **Default Subdomain:** Auto-generated from brand name (e.g., pixelstudios.pixelly.com); unique system-wide
*   **Change Limit:** Maximum 3 changes per brand
    *   Changes 1-2: Standard process
    *   Change 3: Warning modal: "This is your last attempt to modify the domain name..."
    *   After 3: "Edit" button → "Contact Support" link; domain locked
*   **Old Domains Preserved:** All previous subdomains work simultaneously forever (no grace period)
*   **Subdomain Validation:** 3-50 chars, lowercase letters/numbers/hyphens only, unique system-wide
*   **Custom Domain Connection:**
    *   CNAME DNS setup: Name = subdomain, Value = brandname.pixelly.com, TTL = 3600
    *   Dynamic instructions displayed to user
    *   DNS Verification: Immediate attempt → background checks every 15 min for 24 hours
    *   Success Email: "Custom Domain Connected Successfully" (PM: confirm subject/body)
    *   Failure Email: After 24 hours if CNAME not verified (PM: confirm timing and content)
*   **Simultaneous Access:** Default subdomain + custom domain both work (no interruption)
*   **Disconnection:** Confirmation modal; custom domain stops routing; reverts to default only
*   **Permissions:** Owner only; Admin/Team Member read-only

## **FRD #5: Client Portal Settings Section**

*   **Portal Link Display:** Complete URL (default or custom domain) with "Copy Link" button
*   **Auto-Include Toggle (Per Brand):**
    *   Default: ON (portal link included in all automated emails)
    *   OFF: Manual insertion required via copy-paste
    *   Affected emails (PM: complete list needed - captured: Contract sent, Proposal sent, Payment confirmation, Booking confirmation)
*   **Logo Selection:** Primary (wide) or Secondary (square) for portal header
*   **Portal Customization:**
    *   Title: Custom text (default: brand name, PM: confirm)
    *   Color: Separate from brand color or inherit
*   **Live Preview:** Real-time updates as user makes changes
*   **Permissions:** Owner and Admin full access; Team Member read-only

## **FRD #6: Events & Service Section**

**Events Management:**

*   Default events (PM: complete list needed) + unlimited custom events
*   Validation: Unique within brand (case-insensitive), non-blank
*   **Removal Impact Check:** Lead Forms, Packages, Automations, In-progress Projects
*   Warning modal shows affected items with links to modules
*   Removal affects future use only; existing data preserved

**Services Management:**

*   **3 Fixed Types:** Photo, Video, Content (min 1, max 3)
*   Additional offerings via A La Carte (not service types)
*   **Strict Dependency Blocking:** Cannot discontinue if used in:
    *   Packages, Active Proposals, Automations, Lead Forms, Contracts, Questionnaires, Active Projects, Contractors
*   **Error Modal:** Lists all blocking modules with clickable links to affected items
*   User must manually clear dependencies before discontinuation allowed
*   **Discontinuation:** Service hidden from future creation; retained in Reports with "Discontinued" label
*   **Historical Data:** Revenue/performance data preserved; completed projects display discontinued services (read-only)
*   **Re-adding:** Previously discontinued service becomes active again; packages/proposals must be manually recreated
*   **AI-Powered Warnings:** Generate comprehensive impact messages (Developer: Implement AI warning system)

## **FRD #7: Service Area Section**

*   **Free-Form Text Input:** No predefined dropdowns; users type geographic areas
*   **Display Format:** Exactly as entered (no auto-formatting/capitalization)
*   **Validation:** Not blank, not duplicate (case-insensitive), min 1 required
*   **Unlimited Additions:** No max limit on service areas per brand
*   **Tags/Chips Display:** Each area shown as removable tag with "X" icon
*   **Propagation (9+ Modules):**
    *   Project & Event Management, Lead Forms, Packages, Proposals
    *   Calendars & Availability, Automations, Contractor Management
    *   Reports, Brand Settings filters
*   **Removal Impact:**
    *   Affects future projects and dropdowns only
    *   Existing projects retain original service area (historical data)
    *   Lead Forms must be manually updated (not auto-removed)
*   **Permissions:** Owner and Admin full access; Team Member read-only

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

**Image Specifications:**

*   Main Logo aspect ratio (appears 3:1 or 4:1 from Figma)
*   Cover Photo aspect ratio (appears 16:9 from Figma)

**Default Event Types:**

*   Complete list of system default events (visible: Wedding, Corporate Event, Birthday)

**Client Portal Auto-Include:**

*   Complete list of automated emails where toggle applies (captured: Contract sent, Proposal sent, Payment confirmation, Booking confirmation)

**Domain Management:**

*   DNS verification exact wait time before failure email (24 hours suggested)
*   Success/failure email exact subject lines and body content

**Google Maps Fallback:**

*   Manual entry allowed if API fails repeatedly? (Currently shows error only)

**Portal Settings:**

*   Portal title default value (brand name or custom?)

## **Cross-Module Integration Points**

**Subscription Module:** Brand creation limits enforced per plan tier (Developer: Refer to Subscription Module FRD)

**Team Management Module:** Brand assignments for Team Members (view-only for non-assigned brands)

**Project Management:** Brand selection mandatory; brand data (logos, colors, cover photo) used in project headers

**Proposal Management:** Brand filter, brand colors/logos in proposals, business address on documents

**Package Management:** Brand-specific packages; brand appearance in package displays

**Lead Forms:** Service areas, events, services used in form targeting and dropdowns

**Contractor Management:** Service areas for matching; shooting guides accessible in Contractor Portal

**Invoice Management:** Business address, brand info on invoices/contracts

**Client Portal:** Custom domain routing, logo/color customization, portal link distribution

**Reports Module:** Service areas, events, discontinued services as filters; "Discontinued" labels displayed

**Total:** 7 FRDs | 12 Sections Each | 228 Test Cases | All Deliverables Complete

**Key Business Rules:**

*   Brand name unique within agency (case-insensitive), not system-wide
*   Default subdomains unique system-wide
*   First brand auto-fills from agency profile; subsequent brands empty
*   3-change domain limit strictly enforced
*   Old domains preserved forever (simultaneous access)
*   Service discontinuation requires clearing all dependencies first
*   Historical data always preserved (reports, completed projects)
*   Admin read-only for brand identity (General, Appearance, Business Info)
*   Team Members view only assigned brands

1\. Brand Listing

# **FRD #1: Brand Listing**

## **1\. Module Overview**

### 1.1 Module Name

Brand Listing

### 1.2 Purpose

The Brand Listing module provides agency owners and authorized users with a centralized view of all brands created under their agency account. This module serves as the primary entry point for brand management, allowing users to view brand details, access brand configuration settings, and initiate the creation of new brands.

### 1.3 Business Goals

*   Provide a comprehensive overview of all brands associated with the agency account
*   Enable quick access to brand configuration and settings
*   Display key metrics for each brand including projects, upcoming events, and contractors
*   Facilitate efficient brand management through intuitive navigation and sorting capabilities
*   Ensure proper access control based on user roles and brand assignments

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

**Role**

**View Listing**

**Access Brand Details**

**Create New Brand**

**Configure Brand Settings**

**Sort Columns**

Agency Owner

✅ Full Access

✅ All Brands

✅ Yes

✅ Full Access

✅ Yes

Admin

✅ Full Access

✅ All Brands

❌ No

✅ Read-Only (Limited)

✅ Yes

Team Member

✅ Restricted Access

✅ Assigned Brands Only

❌ No

❌ Read-Only

✅ Yes

### 2.1 Permission Details

**Agency Owner:**

*   Can view all brands created under the agency account
*   Can create new brands (subject to subscription plan limits)
*   Can access and edit all brand configuration settings
*   Can assign brands to team members
*   Has full administrative control over brand management

**Admin:**

*   Can view all brands created under the agency account
*   Cannot create new brands
*   Can view brand settings but cannot edit General, Appearance, Business Information sections or connect/disconnect custom domains
*   Can modify certain brand settings like Shooting Guides, Events & Services, Service Areas (with restrictions)
*   Has read-only access to sensitive brand information

**Team Member:**

*   Can view only brands assigned to them during team member invitation or through Team Management module
*   Cannot create new brands
*   Has read-only access to brand settings
*   Cannot modify any brand configurations
*   Can click on brand row to view brand details but cannot make changes

## **3\. User Flow**

### 3.1 Accessing Brand Listing Page

3.1 The user logs into the Pixelly system with valid credentials.

3.2 The system authenticates the user and displays the main dashboard.

3.3 The user clicks on the "Settings" option in the left sidebar navigation menu.

3.4 The system expands the Settings submenu and displays all available settings options.

3.5 The user clicks on "Brands" from the Settings submenu.

3.6 The system navigates to the Brands Management page and loads the brand listing.

### 3.2 Brand Listing Display (Populated State)

3.7 The system checks if any brands exist for the agency account.

3.8 The system retrieves all brands based on the user's role and brand assignments.

3.9 The system displays the "Brands Management" page with a table containing the following columns: Brand Logo/Icon, Name, Creation Date, Projects, Upcoming Events, Contractors, and Actions.

3.10 Each brand row displays the brand's circular icon or logo, brand name, creation date in DD MMM YYYY format, total number of projects, upcoming events count, contractors count, and a "Configure" button.

3.11 The system displays pagination controls at the bottom right showing "Rows per page: 10" with dropdown options and "1-10 of 10" with previous/next navigation arrows.

3.12 The system displays a "New Brand" button in yellow at the top right corner of the page.

### 3.3 Brand Listing Display (Empty State)

3.13 If no brands exist for the agency account, the system displays an empty state illustration with a briefcase icon.

3.14 The system displays the text "No brands found" as the heading.

3.15 The system displays the subtext "Kindly proceed to create one" below the heading.

3.16 The system displays a "Setup Brand" button in purple below the subtext.

### 3.4 Sorting Functionality

3.17 The user clicks on any column header (Name, Creation Date, Projects, Upcoming Events, or Contractors) to sort the table.

3.18 The system sorts the table in ascending order based on the selected column and displays an upward arrow icon next to the column name.

3.19 If the user clicks the same column header again, the system sorts the table in descending order and displays a downward arrow icon.

3.20 The Actions column does not have sorting functionality and clicking it produces no sorting action.

### 3.5 Pagination Navigation

3.21 The user clicks on the "Rows per page" dropdown to select the number of rows to display.

3.22 The system displays dropdown options (10, 20, 30, 50, 100) and the user selects a value.

3.23 The system reloads the table displaying the selected number of rows per page and resets to page 1.

3.24 The user clicks the right arrow (next) button to navigate to the next page of results.

3.25 The system loads the next page and updates the page counter display.

3.26 The user clicks the left arrow (previous) button to navigate to the previous page.

3.27 The system loads the previous page and updates the page counter display.

### 3.6 Accessing Brand Configuration

3.28 The user clicks the "Configure" button on any brand row.

3.29 The system navigates to the Brand Settings/Configuration page for the selected brand.

3.30 Alternatively, the user clicks anywhere on the brand row (except the Configure button).

3.31 The system navigates to the Brand Settings/Configuration page for the selected brand.

### 3.7 Creating New Brand

3.32 The user clicks the "New Brand" button at the top right of the page.

3.33 The system checks the user's role to verify if they have permission to create brands.

3.34 If the user is an Agency Owner, the system checks the subscription plan to verify the brand limit.

3.35 If the brand limit is not reached, the system navigates to the Brand Setup wizard (5-step process).

3.36 If the brand limit is reached, the system displays a modal prompting the user to upgrade their subscription plan.

3.37 If the user is not an Agency Owner (Admin or Team Member), the system displays an error message indicating insufficient permissions.

### 3.8 Empty State Brand Setup

3.38 From the empty state screen, the user clicks the "Setup Brand" button.

3.39 The system checks the user's role and subscription limits as described in steps 3.33-3.37.

3.40 If all validations pass, the system navigates to the Brand Setup wizard.

## **4\. Functional Logic**

### 4.1 Brand Listing Page Access and Display

*   The Brand Listing page is accessible from Settings > Brands in the left sidebar navigation menu.
*   Only users with appropriate roles (Agency Owner, Admin, Team Member with brand assignments) can access this page.
*   The page displays a table with brand information if brands exist, or an empty state if no brands are created.
*   The page title "Brands Management" is displayed prominently at the top left of the content area.
*   The "New Brand" button is displayed at the top right corner in yellow (#FFC107 or similar brand yellow).
*   The "Go Back" navigation link with a left arrow icon is displayed at the top left, allowing users to return to the Settings page.

### 4.2 Brand Listing Table Structure

*   The table displays the following columns from left to right: Brand Logo/Icon, Name, Creation Date, Projects, Upcoming Events, Contractors, and Actions.
*   Each brand row displays a circular brand icon or logo (40x40 pixels) at the far left, using the secondary logo if uploaded, or the main logo if only the main logo exists.
*   The Name column displays the brand name as text, left-aligned, with the ability to sort alphabetically.
*   The Creation Date column displays the date the brand was created in DD MMM YYYY format (e.g., "12 Aug 2025"), with the ability to sort chronologically.
*   The Projects column displays the total number of projects associated with the brand as a numeric value, with the ability to sort numerically.
*   The Upcoming Events column displays the count of upcoming events for the brand, with the ability to sort numerically.
*   The Contractors column displays the total number of contractors assigned to projects under the brand, with the ability to sort numerically.
*   The Actions column displays a "Configure" button in gray text with no background, right-aligned, with no sorting capability.

### 4.3 Brand Display Based on User Role

*   If the user is an Agency Owner, the system displays all brands created under the agency account without restriction.
*   If the user is an Admin, the system displays all brands created under the agency account without restriction.
*   If the user is a Team Member, the system displays only the brands assigned to them during invitation or through the Team Management module.
*   If a Team Member has no brands assigned, the system displays the empty state screen.

### 4.4 Sorting Functionality

*   Clicking on the Name column header sorts the brand list alphabetically in ascending order (A-Z) by default.
*   Clicking the Name column header again toggles the sort to descending order (Z-A).
*   Clicking on the Creation Date column header sorts the list chronologically from oldest to newest by default.
*   Clicking the Creation Date column header again toggles the sort to newest to oldest.
*   Clicking on the Projects, Upcoming Events, or Contractors column headers sorts numerically from lowest to highest by default.
*   Clicking the same numeric column header again toggles the sort to highest to lowest.
*   The system displays a small arrow icon (up or down) next to the active sorted column header to indicate the current sort direction.
*   Only one column can be sorted at a time; clicking a different column header resets the previous sort.
*   The Actions column header is not clickable and does not trigger any sorting action.

### 4.5 Pagination Logic

*   The system displays a pagination control at the bottom right of the table showing "Rows per page: \[dropdown\]" and a page counter showing "X-Y of Z" where X is the first row number, Y is the last row number on the current page, and Z is the total number of brands.
*   The "Rows per page" dropdown allows users to select from 10, 20, 30, 50, or 100 rows per page, with 10 as the default value.
*   Changing the rows per page value reloads the table, resets to page 1, and updates the page counter accordingly.
*   The previous (left arrow) and next (right arrow) navigation buttons allow users to navigate between pages.
*   The previous button is disabled when the user is on page 1 (grayed out and non-clickable).
*   The next button is disabled when the user is on the last page (grayed out and non-clickable).
*   Clicking the next button increments the page number and loads the next set of rows.
*   Clicking the previous button decrements the page number and loads the previous set of rows.

### 4.6 Row Click Behavior

*   Clicking anywhere on a brand row (except on the Configure button) navigates the user to the Brand Settings/Configuration page for that specific brand.
*   The row click area includes the brand icon, brand name, and all metric columns.
*   On hover, the entire row highlights with a light gray background (#F5F5F5 or similar) to indicate clickability.
*   The cursor changes to a pointer when hovering over the clickable row area.

### 4.7 Configure Button Behavior

*   The "Configure" button in the Actions column is displayed for each brand row.
*   Clicking the Configure button navigates the user to the Brand Settings/Configuration page for the selected brand.
*   The Configure button behaves identically to clicking the brand row itself (both actions lead to the same destination).
*   On hover, the Configure button text changes color to indicate interactivity (e.g., from gray to dark gray or blue).

### 4.8 New Brand Button Behavior

*   The "New Brand" button is displayed at the top right of the Brands Management page in yellow.
*   The button is visible to all user roles but only functional for Agency Owners.
*   When an Agency Owner clicks the "New Brand" button, the system first checks the subscription plan to verify the brand creation limit.
*   If the limit is not reached, the system navigates to the Brand Setup wizard (Step 1: Basic Information).
*   If the limit is reached, the system displays a modal dialog with the message "You have reached the maximum number of brands allowed for your subscription plan. Please upgrade to add more brands."
*   The modal includes a "Upgrade Plan" button that redirects to the Subscription/Billing page, and a "Cancel" button that closes the modal.
*   When an Admin or Team Member clicks the "New Brand" button, the system displays an error message "You do not have permission to create brands. Please contact your agency owner."
*   The error message is displayed as a toast notification or modal and disappears after 5 seconds or when dismissed.

### 4.9 Empty State Display Logic

*   If no brands exist for the agency account, the system displays an empty state screen instead of the brand listing table.
*   The empty state includes a briefcase icon illustration centered on the page.
*   The text "No brands found" is displayed in large, bold font below the icon.
*   The subtext "Kindly proceed to create one" is displayed in smaller font below the heading.
*   A "Setup Brand" button in purple is displayed below the subtext, centered on the page.
*   The "New Brand" button in yellow remains visible at the top right of the page header for Agency Owners.
*   Clicking the "Setup Brand" button triggers the same brand creation flow as clicking "New Brand" (subject to role and subscription validation).

### 4.10 Brand Icon Display Logic

*   If a brand has a secondary logo uploaded, the system displays the secondary logo in the circular brand icon column (40x40 pixels, cropped to fit).
*   If a brand has only a main logo uploaded (no secondary logo), the system displays the main logo in the circular brand icon column, cropped to fit a square/circle.
*   If a brand has no logos uploaded (edge case, should not occur due to mandatory main logo requirement), the system displays a placeholder icon with the first two initials of the brand name in uppercase.
*   The brand icon serves as a visual identifier in the listing table and is displayed consistently throughout the Pixelly system.

### 4.11 Brand Metrics Calculation

*   The Projects count displays the total number of projects created under the selected brand, including completed, in-progress, and upcoming projects.
*   The Upcoming Events count displays the number of events scheduled in the future (event date >= current date) associated with the brand.
*   The Contractors count displays the total number of unique contractors who have been invited to or assigned to projects under the selected brand.
*   All counts are calculated dynamically and updated in real-time when projects, events, or contractor assignments change.
*   If a count is zero, the system displays "0" in the respective column (not blank or dash).

### 4.12 Role-Based Access Enforcement

*   The system enforces role-based permissions on the Brand Listing page load.
*   If a user without appropriate permissions attempts to access the page via direct URL manipulation, the system redirects them to the dashboard with an error message "Access denied. You do not have permission to view this page."
*   Agency Owners and Admins can view all brands regardless of assignments.
*   Team Members see only brands assigned to them in the Team Management module or during contractor invitation.
*   If a Team Member's brand assignments are removed in Team Management, those brands immediately disappear from their Brand Listing view.

### 4.13 Search and Filter Functionality

*   The Brand Listing page does not include search or filter functionality as per the requirements.
*   Users rely on sorting and pagination to navigate through the brand list.
*   If the feature is requested in the future, it can be added as an enhancement.

### 4.14 Navigation and Breadcrumbs

*   The Brand Listing page is accessed via Settings > Brands in the sidebar navigation.
*   A "Go Back" link with a left arrow icon is displayed at the top left of the page, allowing users to return to the main Settings page.
*   Clicking "Go Back" navigates the user to the Settings page without saving any unsaved changes (as the listing page has no editable fields).
*   The sidebar menu highlights "Brands" as the active menu item while the user is on the Brand Listing page.

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

**Field Name**

**Field Type**

**Mandatory**

**Validation Rules**

**Error Message (if applicable)**

Brand Name (Display)

Text (Read-Only)

N/A

No validation (display only)

N/A

Creation Date (Display)

Date (Read-Only)

N/A

No validation (display only)

N/A

Projects (Display)

Numeric (Read-Only)

N/A

No validation (display only)

N/A

Upcoming Events (Display)

Numeric (Read-Only)

N/A

No validation (display only)

N/A

Contractors (Display)

Numeric (Read-Only)

N/A

No validation (display only)

N/A

Rows per page

Dropdown

No

Must select from predefined values: 10, 20, 30, 50, 100

N/A (Dropdown selection only)

Page Navigation

Button (Previous/Next)

No

Disabled when no previous/next page exists

N/A (UI control only)

**Note:** The Brand Listing page is a read-only display page with no editable fields requiring validation. All data is retrieved from the database and displayed as-is.

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

**Action**

**Success Message**

**Display Method**

**Duration**

**Post-Success Action**

Brand Listing Page Loaded

No message displayed

N/A

N/A

Display brand listing table or empty state

Sort Column Clicked

No message displayed

N/A

N/A

Table re-sorts based on selected column and direction

Pagination Changed

No message displayed

N/A

N/A

Table reloads with selected rows per page or page number

Brand Row Clicked

No message displayed

N/A

N/A

Navigate to Brand Settings/Configuration page

Configure Button Clicked

No message displayed

N/A

N/A

Navigate to Brand Settings/Configuration page

**Note:** The Brand Listing page does not display success messages as it is a navigation and display page without create, update, or delete actions.

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

**Error Scenario**

**Error Message**

**Trigger Condition**

**Display Method**

**User Action Required**

Unauthorized Access

"Access denied. You do not have permission to view this page."

User without appropriate role attempts to access Brand Listing page via direct URL

Toast notification (red) or redirect to dashboard with error banner

Contact agency owner for access

Brand Creation Permission Denied

"You do not have permission to create brands. Please contact your agency owner."

Admin or Team Member clicks "New Brand" or "Setup Brand" button

Modal dialog or toast notification

Dismiss message or contact agency owner

Subscription Limit Reached

"You have reached the maximum number of brands allowed for your subscription plan. Please upgrade to add more brands."

Agency Owner clicks "New Brand" or "Setup Brand" button when brand limit is reached

Modal dialog with "Upgrade Plan" and "Cancel" buttons

Click "Upgrade Plan" to navigate to subscription page, or click "Cancel" to dismiss

No Brands Assigned (Team Member)

Empty state displayed: "No brands found. Kindly proceed to create one."

Team Member with no brand assignments accesses Brand Listing page

Empty state screen

Contact agency owner to assign brands

Brand Data Load Failure

"Unable to load brand information. Please try again later."

System fails to retrieve brand data from database due to server error

Toast notification (red) at top of page

Refresh the page or contact support if error persists

Invalid Page Navigation

"Invalid page number. Redirecting to page 1."

User manipulates URL to access a non-existent page number

Toast notification (orange)

System auto-redirects to page 1

## **8\. Edge Cases**

**Edge Case**

**System Behavior**

**Expected Outcome**

**Notes**

No brands exist (First-time agency)

Display empty state with "No brands found" message and "Setup Brand" button

User can initiate brand creation from empty state

"Setup Brand" button triggers same validation as "New Brand" button

Team Member has no assigned brands

Display empty state with message "No brands found" but hide "Setup Brand" button (or disable it)

Team Member sees empty state but cannot create brands; must contact agency owner

**PM Note:** Confirm if "Setup Brand" button should be hidden or disabled for Team Members

Subscription allows 1 brand, 1 brand already created

"New Brand" button click triggers subscription limit error modal

User cannot create additional brands without upgrading subscription

System enforces subscription limits strictly

Admin clicks "New Brand" button

Error message displayed: "You do not have permission to create brands."

Admin is prevented from creating brands

Only Agency Owner can create brands

Brand has 0 projects, 0 events, 0 contractors

Display "0" in respective columns

Zero values are displayed instead of blank or dash

Ensures data consistency

Brand name exceeds display width

Truncate brand name with ellipsis (...) and show full name on hover tooltip

Long brand names display correctly without breaking table layout

**Developer Note:** Implement tooltip on hover for truncated text

Very large number of brands (100+)

Pagination controls allow efficient navigation through pages

System performance remains optimal

**Developer Note:** Implement server-side pagination and lazy loading if needed

User rapidly clicks sort column headers

System queues sort requests and processes them sequentially

No UI lag or duplicate sort operations

**Developer Note:** Implement debounce mechanism for sort clicks

User changes rows per page while on page 5

System resets to page 1 with new rows per page value

Prevents "out of range" page error

Expected behavior

Concurrent brand creation by multiple Agency Owners

Each brand creation is processed independently; subscription limit checked at creation time

No conflicts; subscription limit enforced correctly

System handles concurrent operations

Brand deleted by another user while current user is viewing listing

Brand disappears from listing on next page refresh or real-time update

User sees updated brand list

**PM Note:** Confirm if real-time updates via WebSocket are required or manual refresh is acceptable

User on page 3, another user deletes brands reducing total to 2 pages

System displays "Invalid page number" message and redirects to page 1 on next navigation attempt

User is redirected to valid page

Prevents navigation errors

## **9\. Acceptance Criteria**

### 9.1 Functional Requirements

*   ✅ Agency Owners can view all brands created under their agency account
*   ✅ Admins can view all brands but cannot create new brands
*   ✅ Team Members can view only brands assigned to them
*   ✅ Brand Listing table displays all required columns: Logo/Icon, Name, Creation Date, Projects, Upcoming Events, Contractors, Actions
*   ✅ All columns except Actions support ascending and descending sorting
*   ✅ Pagination controls allow users to select rows per page (10, 20, 30, 50, 100) and navigate between pages
*   ✅ Clicking a brand row or "Configure" button navigates to Brand Settings/Configuration page
*   ✅ "New Brand" button triggers brand creation wizard for Agency Owners with valid subscription
*   ✅ Empty state is displayed when no brands exist, with "Setup Brand" button
*   ✅ Subscription limits are enforced when Agency Owner attempts to create a new brand
*   ✅ Permission validation prevents non-owners from creating brands

### 9.2 Data Consistency

*   ✅ Brand metrics (Projects, Upcoming Events, Contractors) are calculated accurately and updated dynamically
*   ✅ Brand icons display secondary logo if available, otherwise main logo
*   ✅ Sorting maintains data integrity and displays results correctly
*   ✅ Pagination displays accurate row counts and page numbers

### 9.3 User Experience Validation

*   ✅ Page loads within 2 seconds for up to 100 brands
*   ✅ Sorting and pagination operations complete within 1 second
*   ✅ Error messages are clear, actionable, and user-friendly
*   ✅ Navigation flows are intuitive and consistent with Pixelly design standards
*   ✅ Hover states and click interactions provide visual feedback

### 9.4 Security & Access Control

*   ✅ Role-based permissions are enforced on page load and button clicks
*   ✅ Unauthorized users cannot access Brand Listing page via URL manipulation
*   ✅ Team Members see only assigned brands (no data leakage)
*   ✅ Subscription limits are enforced at the server level (not client-side only)

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

**Test cases for Brand Listing module are available in the separate Excel file:**

[1\_Brand\_Listing\_Test\_Cases.xlsx](https://docs.google.com/spreadsheets/d/1CrJk_qq0DDB0kJqTYsV7Eyxab8yi4iK2/edit?usp=drive_link&ouid=105170312247554220827&rtpof=true&sd=true)

## **11\. Dependencies**

**Dependency Type**

**Module/Service Name**

**Dependency Description**

**Impact if Unavailable**

**Mitigation**

Internal Module

Brand Setup Module

Brand creation wizard flow initiated from "New Brand" or "Setup Brand" button

Users cannot create new brands

Display error message and provide support contact

Internal Module

Brand Settings/Configuration Module

Navigation target when user clicks brand row or Configure button

Users cannot access brand settings

Display error message and disable navigation

Internal Module

Team Management Module

Brand assignments for Team Members retrieved from Team Management

Team Members may see incorrect brand list

Ensure data synchronization between modules

Internal Module

Subscription Module

Brand creation limits enforced based on subscription plan

Cannot validate brand creation limits

**Developer Note:** Refer to Subscription Module FRD for integration details

Internal Module

Project Management Module

Projects count retrieved from Project database

Projects column may display incorrect count

Display "N/A" or error icon if data unavailable

Internal Module

Event Management Module

Upcoming Events count retrieved from Event database

Upcoming Events column may display incorrect count

Display "N/A" or error icon if data unavailable

Internal Module

Contractor Management Module

Contractors count retrieved from Contractor database

Contractors column may display incorrect count

Display "N/A" or error icon if data unavailable

Database

Brands Table

Stores all brand information (name, creation date, logos, etc.)

Brand Listing page cannot load

Display error message: "Unable to load brand information. Please try again later."

Database

User Roles & Permissions Table

Retrieves user role and brand assignments

Cannot enforce role-based access

Deny access and display "Access denied" message

API

Brand Data Retrieval API

Fetches brand list and metrics for display

Page displays empty state or error

Display error message and provide retry option

## **12\. References**

### 12.1 Figma Designs: [Figma](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=29490-144766&t=hlJPZKI33RrWvjz0-0)

2\. Brand Setup / Create New Brand

# **FRD #2: Brand Setup / Create New Brand**

## **1\. Module Overview**

### 1.1 Module Name

Brand Setup / Create New Brand

### 1.2 Purpose

The Brand Setup module provides a guided, multi-step wizard for agency owners to create and configure new brands within the Pixelly system. This module is essential as brand creation is a mandatory prerequisite for performing key actions throughout the platform, including creating projects, inviting team members and contractors, creating packages, and generating proposals. The 5-step wizard ensures comprehensive brand configuration by collecting essential information about brand identity, appearance, services, business details, and social media presence.

### 1.3 Business Goals

*   Streamline the brand creation process through an intuitive, step-by-step wizard interface
*   Ensure all mandatory brand information is collected before brand activation
*   Reduce setup time for the first brand by auto-filling data from the agency profile
*   Enforce subscription plan limits to align brand creation with billing tiers
*   Provide immediate visual feedback through logo cropping and color selection tools
*   Enable brands to be fully operational upon wizard completion with all required configurations in place
*   Support multi-brand agency operations by allowing owners to create and manage multiple distinct brand identities

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

**Role**

**Access Brand Setup Wizard**

**Create First Brand**

**Create Additional Brands**

**Auto-Fill Benefit**

**Bypass Wizard**

Agency Owner

✅ Full Access

✅ Yes

✅ Yes (within subscription limit)

✅ Yes (first brand only)

❌ No

Admin

❌ No Access

❌ No

❌ No

❌ No

❌ No

Team Member

❌ No Access

❌ No

❌ No

❌ No

❌ No

### 2.1 Permission Details

**Agency Owner:**

*   Exclusive permission to create brands for the agency account
*   Can initiate brand setup from multiple entry points (onboarding stepper, Settings > Brands, empty state prompts)
*   First brand creation benefits from auto-filled data (business name, website, phone number) from agency profile
*   Subsequent brand creations require manual entry of all fields
*   Subject to subscription plan limits (e.g., Starter = 1 brand, Pro = 5 brands, Enterprise = unlimited)
*   Cannot skip wizard steps or bypass mandatory fields
*   Must complete all 5 steps sequentially to create a brand

**Admin:**

*   Cannot access Brand Setup wizard or create brands
*   Receives error message if attempting to click "New Brand" or "Setup Brand" buttons
*   Can view existing brands in Brand Listing but cannot modify brand creation settings

**Team Member:**

*   Cannot access Brand Setup wizard or create brands
*   Receives error message if attempting to click "New Brand" or "Setup Brand" buttons
*   Can view assigned brands in Brand Listing but has no brand creation privileges

## **3\. User Flow**

### 3.1 Entry Point 1: Onboarding Stepper (First-Time Agency Setup)

3.1 A new agency owner completes the sign-up process and logs into Pixelly for the first time.

3.2 The system displays an onboarding stepper showing multiple setup steps, one of which is "Set up your brand."

3.3 The system highlights the "Set up your brand" step as the current active step in the onboarding flow.

3.4 The user clicks "Continue" or "Set up your brand" on the onboarding stepper.

3.5 The system navigates to the Brand Setup wizard, starting at Step 1: Basic Information.

### 3.2 Entry Point 2: Settings > Brands > New Brand Button

3.6 The agency owner logs into Pixelly and navigates to Settings > Brands from the left sidebar menu.

3.7 The system displays the Brand Listing page.

3.8 The user clicks the "New Brand" button in yellow at the top right corner of the page.

3.9 The system validates the user's role to confirm they are an Agency Owner.

3.10 The system checks the subscription plan to verify the current number of brands against the allowed limit.

3.11 If validation passes, the system navigates to the Brand Setup wizard, starting at Step 1: Basic Information.

3.12 If the brand limit is reached, the system displays a subscription limit modal with "Upgrade Plan" and "Cancel" options.

### 3.3 Entry Point 3: Empty State "Setup Brand" Button

3.13 The agency owner navigates to Settings > Brands and sees the empty state (no brands exist yet).

3.14 The system displays an empty state illustration with the message "No brands found" and "Kindly proceed to create one."

3.15 The user clicks the "Setup Brand" button displayed in the empty state.

3.16 The system performs the same role and subscription validation as described in steps 3.9-3.12.

3.17 If validation passes, the system navigates to the Brand Setup wizard, starting at Step 1: Basic Information.

### 3.4 Entry Point 4: Module Prompts (Packages, Proposals, Questionnaires, etc.)

3.18 The user attempts to create a package, proposal, or perform any action requiring a brand to be configured.

3.19 The system detects that no brands exist for the agency.

3.20 The system displays a prompt or modal with the message "Please setup brand first" or similar.

3.21 The user clicks "Setup Brand" from the prompt.

3.22 The system navigates to the Brand Setup wizard, starting at Step 1: Basic Information.

### 3.5 Brand Setup Wizard - Step 1: Basic Information

3.23 The system displays the Brand Setup wizard with a step indicator showing "Step 1 of 5" or similar progress tracker.

3.24 The system displays the heading "Let's set up your brand" or similar welcoming message.

3.25 If this is the first brand being created, the system auto-fills the "Business Name," "Website," and "Phone Number" fields with data from the agency profile (fields fetched: Business Name → Brand Name, Company Website → Brand Website, Phone Number → Brand Phone Number).

3.26 If this is a subsequent brand (second, third, etc.), the system displays all three fields as empty, requiring manual entry.

3.27 The user enters or edits the brand name in the "Business Name" text input field (max 100 characters).

3.28 The user enters or edits the brand website URL in the "Website" text input field.

3.29 The user enters or edits the brand phone number in the "Phone Number" text input field.

3.30 The system validates that all three fields are filled and meet validation criteria before enabling the "Next" button.

3.31 The user clicks the "Next" button to proceed to Step 2.

3.32 The system saves the entered data temporarily (not committed to database) and navigates to Step 2: Customize Appearance.

### 3.6 Brand Setup Wizard - Step 2: Customize Appearance

3.33 The system displays the step indicator showing "Step 2 of 5" with the heading "Customize Appearance."

3.34 The system displays four configuration sections: Main Logo (mandatory), Secondary Logo (optional), Brand Color (mandatory), and Default Cover Photo (mandatory).

3.35 The user clicks "Upload" under the Main Logo section and selects an image file from their device.

3.36 The system validates the file format (PNG, JPG, JPEG, WEBP) and file size (max 5MB).

3.37 If validation passes, the system displays a cropping modal with the uploaded image and a fixed aspect ratio cropping tool.

3.38 The user adjusts the crop area to frame the desired portion of the logo.

3.39 The user clicks "Save" in the cropping modal.

3.40 The system saves the cropped logo and displays a preview in the Main Logo section.

3.41 Optionally, the user uploads and crops a Secondary Logo following the same process (square 1:1 aspect ratio).

3.42 The user clicks on the Brand Color picker and selects a color using the color gradient selector or enters a HEX code.

3.43 The system displays the selected color preview and updates the HEX, R, G, B values dynamically.

3.44 The user clicks "Upload" under the Default Cover Photo section and selects an image file (max 15MB).

3.45 The system displays the cropping modal with a wide aspect ratio cropping tool (PM Note: Confirm exact aspect ratio - appears to be 16:9).

3.46 The user adjusts the crop area and clicks "Save."

3.47 The system saves the full uncropped image to the user's Library and saves the cropped version as the brand's default cover photo.

3.48 The system validates that Main Logo, Brand Color, and Cover Photo are all provided before enabling the "Next" button.

3.49 The user clicks "Next" to proceed to Step 3.

3.50 The system saves the appearance data temporarily and navigates to Step 3: Select Events.

### 3.7 Brand Setup Wizard - Step 3: Select Events

3.51 The system displays the step indicator showing "Step 3 of 5" with the heading "Select all the event types you currently offer."

3.52 The system displays a list of default event types with checkboxes (e.g., Wedding, Corporate Event, Birthday - PM Note: Complete default event types list needed).

3.53 The system displays descriptive text explaining that selecting event types helps customize the platform and populates contact forms automatically.

3.54 The user selects one or more event types by clicking the corresponding checkboxes.

3.55 Optionally, the user clicks "Add Custom Event" or a similar option to create a new event type.

3.56 The system displays a text input field for entering a custom event name.

3.57 The user enters the custom event name and clicks "Add" or presses Enter.

3.58 The system adds the custom event to the list with its checkbox automatically selected.

3.59 The user can add multiple custom events by repeating steps 3.55-3.58.

3.60 The system validates that at least one event type (default or custom) is selected before enabling the "Next" button.

3.61 The user clicks "Next" to proceed to Step 4.

3.62 The system saves the selected event types temporarily and navigates to Step 4: Business Information & Service Area.

### 3.8 Brand Setup Wizard - Step 4: Business Information & Service Area

3.63 The system displays the step indicator showing "Step 4 of 5" with two main sections: Business Information and Service Area.

3.64 Under Business Information, the system displays fields for Street Address, City, State/Province, Country, and Zip/Postal Code.

3.65 The user starts typing in the Street Address field, which triggers the Google Maps API autocomplete.

3.66 The system displays address suggestions from Google Maps as the user types.

3.67 The user selects an address from the suggestions dropdown.

3.68 The system auto-fills Street Address, City, State/Province, Country, and Zip/Postal Code fields based on the selected Google Maps result.

3.69 If the Google Maps API returns incorrect data or the user wants to modify, they can manually edit the Street Address and Zip/Postal Code fields (City, State/Province, and Country are not editable after Google Maps selection).

3.70 If Google Maps API fails or returns no results, the system displays a warning message: "Unable to fetch address. Please try again later or contact support." (PM Note: Suggest allowing manual entry of all fields as fallback if API fails repeatedly).

3.71 Under Service Area, the system displays a free-form text input field for entering service areas.

3.72 The user types a service area name (e.g., "New York, NY") and presses Enter or clicks "Add."

3.73 The system adds the entered service area as a tag or chip below the input field.

3.74 The system validates that the service area is not blank and not a duplicate of an existing entry.

3.75 The user can add multiple service areas by repeating steps 3.72-3.74.

3.76 The user can remove a service area by clicking the "X" icon on its tag/chip.

3.77 The system validates that all Business Information fields are filled and at least one service area is added before enabling the "Next" button.

3.78 The user clicks "Next" to proceed to Step 5.

3.79 The system saves the business information and service area data temporarily and navigates to Step 5: Social Media Links.

### 3.9 Brand Setup Wizard - Step 5: Social Media Links

3.80 The system displays the step indicator showing "Step 5 of 5" with the heading "Connect Social Media Links."

3.81 The system displays input fields for social media platforms: Facebook, Instagram, LinkedIn, X (Twitter), Pinterest, Vimeo, YouTube, and TikTok.

3.82 Each field displays the platform icon and a text input box for entering the profile URL.

3.83 The user enters social media URLs in the desired fields (all fields are optional).

3.84 The system validates that entered URLs are in proper format (must include https:// or [www](http://www).).

3.85 If a URL is invalid (e.g., "abc123" or "instagram.com/profile" without https://), the system displays an inline error message below the field: "Please enter a valid URL (must start with https:// or [www](http://www).)."

3.86 The user can leave fields blank for platforms they do not use.

3.87 Once at least one valid URL is entered or the user chooses to skip all (Step 5 has no mandatory fields), the "Finish" or "Complete Setup" button is enabled.

3.88 The user clicks "Finish" to complete the brand setup.

3.89 The system validates all data from all 5 steps, commits the brand to the database, and displays a success message.

3.90 The system navigates the user to the Brand Listing page or Brand Settings/Configuration page showing the newly created brand.

### 3.10 Navigation Between Steps (Backward Navigation)

3.91 At any step in the wizard (Steps 2-5), the user can click the "Back" button to return to the previous step.

3.92 The system navigates to the previous step and displays the previously entered data pre-filled in all fields.

3.93 The user can edit any previously entered data.

3.94 The user clicks "Next" again to re-validate and proceed forward.

3.95 The system allows free backward navigation without losing entered data.

### 3.11 Wizard Closure Without Completion

3.96 If the user closes the wizard or navigates away before clicking "Finish" on Step 5, the system does not save any data.

3.97 If the user returns to the Brand Setup wizard later, all fields are reset to their initial state (auto-fill for first brand, empty for subsequent brands).

3.98 No draft or partial brand data is saved.

## **4\. Functional Logic**

### 4.1 Brand Setup Wizard Entry Points and Access Control

*   The Brand Setup wizard can be accessed from four entry points: onboarding stepper, Settings > Brands > New Brand button, empty state "Setup Brand" button, and module prompts when no brand exists.
*   Only Agency Owners can access the Brand Setup wizard; Admins and Team Members are blocked with appropriate error messages.
*   When a non-owner attempts to create a brand, the system displays: "You do not have permission to create brands. Please contact your agency owner."
*   The system validates the user's role before allowing access to the wizard from any entry point.

### 4.2 Subscription Plan Validation

*   Before allowing brand creation, the system checks the agency's subscription plan to retrieve the maximum number of brands allowed (Developer Note: Refer to Subscription Module FRD for brand limit logic).
*   The system queries the database to count existing brands for the agency and compares against the subscription limit.
*   If the limit is reached, the system displays a modal: "You have reached the maximum number of brands allowed for your subscription plan. Please upgrade to add more brands."
*   The modal includes an "Upgrade Plan" button that redirects to the Subscription/Billing page and a "Cancel" button that closes the modal and returns the user to the Brand Listing page.
*   If the limit is not reached, the system proceeds to open the Brand Setup wizard.
*   Subscription validation occurs before Step 1 is displayed, ensuring users do not waste time entering data only to be blocked at the end.

### 4.3 First Brand Auto-Fill Logic

*   When an agency owner creates their first brand, the system checks if any brands exist for the agency account (count = 0).
*   If no brands exist, the system retrieves data from the agency profile: Business Name field → Brand Name, Company Website field → Brand Website, Phone Number field → Brand Phone Number.
*   The system pre-fills the Step 1 fields with this data, allowing the user to accept as-is or edit before proceeding.
*   Auto-fill only applies to the first brand; all subsequent brands (second, third, etc.) display empty fields requiring manual entry.
*   The auto-fill mechanism reduces setup time for single-brand agencies and ensures consistency between agency and brand identity.

### 4.4 Wizard Structure and Step Progression

*   The Brand Setup wizard consists of 5 sequential steps that must be completed in order: Step 1 (Basic Information), Step 2 (Customize Appearance), Step 3 (Select Events), Step 4 (Business Information & Service Area), Step 5 (Social Media Links).
*   A visual step indicator (e.g., "Step 1 of 5" or progress dots) is displayed at the top of the wizard, showing the user their current position and overall progress.
*   Users cannot skip ahead to future steps; the "Next" button only becomes enabled when all mandatory fields in the current step are completed and validated.
*   Users can navigate backward to previous steps freely by clicking the "Back" button, and previously entered data is preserved and displayed for editing.
*   If a user navigates backward and changes data in a previous step, the system re-validates that step when "Next" is clicked.

### 4.5 Step 1: Basic Information - Field Logic

*   Step 1 displays three mandatory fields: Business Name (max 100 characters, allows special characters, must be unique within the agency), Website (URL format, must start with https:// or http:// or [www](http://www).), and Phone Number (accepts international formats, no strict regex, displays as entered).
*   For the first brand, these fields are auto-filled from the agency profile (Business Name, Company Website, Phone Number) and are editable.
*   For subsequent brands, all fields are empty and require manual entry.
*   The system performs real-time validation as the user types, displaying inline error messages below invalid fields.
*   The "Next" button remains disabled (grayed out) until all three fields are filled and valid.
*   Once all fields pass validation, the "Next" button becomes enabled (bright yellow or brand color) and clickable.

### 4.6 Step 1: Validation Rules

*   Business Name: Mandatory, 1-100 characters, allows letters, numbers, spaces, and special characters (e.g., &, -, ', "), must be unique within the agency (case-insensitive).
*   Website: Mandatory, must match URL format (e.g., [https://example.com](https://example.com), [http://example.com](http://example.com), [www.example.com](http://www.example.com)), accepts subdomains and paths (e.g., [https://photography.example.com/about](https://photography.example.com/about)).
*   Phone Number: Mandatory, accepts numeric input with optional +, -, (), spaces (e.g., +1 (555) 123-4567, 555-123-4567, +44 20 1234 5678), no strict format enforcement to support international numbers.
*   If Business Name already exists for another brand under the same agency, the system displays: "This brand name already exists. Please choose a different name."
*   If Website URL is invalid, the system displays: "Please enter a valid website URL (e.g., [https://example.com](https://example.com))."
*   If Phone Number is left blank, the system displays: "Phone number is required."

### 4.7 Step 2: Customize Appearance - Main Logo Upload

*   Main Logo is mandatory; Step 2 cannot be completed without uploading a main logo.
*   The user clicks "Upload" under the Main Logo section, which opens the system file browser.
*   The system accepts image files in PNG, JPG, JPEG, or WEBP format only; other formats trigger an error: "Invalid file format. Please upload PNG, JPG, JPEG, or WEBP."
*   Maximum file size for Main Logo is 5MB; files larger than 5MB trigger an error: "File size exceeds 5MB. Please upload a smaller image."
*   After a valid image is selected, the system displays a cropping modal with the image loaded in a fixed aspect ratio cropping tool (PM Note: Confirm exact aspect ratio - appears to be 3:1 or 4:1 for horizontal logos).
*   The cropping modal includes a draggable crop area, zoom controls, and rotation options (if applicable).
*   The user adjusts the crop area to frame the desired portion of the logo and clicks "Save."
*   The system processes the crop, generates a preview thumbnail, and displays the cropped logo in the Main Logo section.
*   The user can re-upload or re-crop the Main Logo by clicking "Change" or "Upload New" before proceeding to Step 3.

### 4.8 Step 2: Customize Appearance - Secondary Logo Upload (Optional)

*   Secondary Logo is optional; users can skip this section and proceed without uploading a secondary logo.
*   If uploaded, the Secondary Logo follows the same file format (PNG, JPG, JPEG, WEBP) and size (max 5MB) validation as the Main Logo.
*   The cropping tool for Secondary Logo enforces a 1:1 square aspect ratio, ensuring the logo fits circular icon displays throughout the system.
*   If no Secondary Logo is uploaded, the system uses the Main Logo for all icon placements (cropped to fit circular/square shapes).
*   The Secondary Logo is used in Brand Listing icons, dropdown selections, and other small UI elements where a square logo is preferable.

### 4.9 Step 2: Customize Appearance - Brand Color Selection

*   Brand Color is mandatory; the user must select a color before proceeding to Step 3.
*   The system displays a color picker with a gradient selector, allowing users to choose any color visually.
*   The system also displays input fields for HEX code, R (Red), G (Green), and B (Blue) values, which update dynamically as the user adjusts the color picker.
*   Users can manually enter a HEX code (e.g., #E89623) or RGB values (e.g., R: 232, G: 150, B: 35) to select a precise color.
*   The system validates that HEX codes are in valid format (#RRGGBB or #RGB) and RGB values are within 0-255 range.
*   A color preview swatch displays the currently selected color in real-time.
*   The selected Brand Color is used throughout the platform when "Use Brand Color" option is enabled in proposals, packages, forms, and other brand-specific materials.

### 4.10 Step 2: Customize Appearance - Default Cover Photo Upload

*   Default Cover Photo is mandatory; the user must upload a cover photo to complete Step 2.
*   The system accepts image files in PNG, JPG, JPEG, or WEBP format with a maximum file size of 15MB.
*   After the user selects a cover photo, the system displays a cropping modal with a wide aspect ratio cropping tool (PM Note: Confirm exact aspect ratio - appears to be 16:9 for headers).
*   The user adjusts the crop area and clicks "Save."
*   The system saves the full uncropped image to the user's Library (accessible in Projects, Proposals, etc. for future use) and saves the cropped version as the brand's default cover photo.
*   The default cover photo appears at the top of project pages, client portals, proposals, and questionnaires as the header image.
*   Users can override the default cover photo on a per-project basis, but the brand's default is used for all new projects unless changed.
*   A preview of the cropped cover photo is displayed in the Step 2 interface after saving.

### 4.11 Step 2: Next Button Enablement Logic

*   The "Next" button in Step 2 is disabled until all three mandatory elements are uploaded and validated: Main Logo, Brand Color, and Default Cover Photo.
*   Secondary Logo is not required for "Next" button enablement.
*   The system performs client-side validation to check for the presence of all three required elements before enabling the button.
*   If any mandatory element is missing, the system displays a message below the "Next" button: "Please complete all required fields to proceed (Main Logo, Brand Color, Cover Photo)."

### 4.12 Step 3: Select Events - Default Event Types

*   The system displays a list of default event types with checkboxes (PM Note: Complete default event types list needed - visible types include Wedding, Corporate Event, Birthday).
*   Default event types are pre-configured in the system and available to all users.
*   Users can select one or multiple default event types by clicking the checkboxes.
*   The system does not enforce a maximum limit on the number of event types that can be selected.
*   Selected event types are used to populate dropdown options in Projects, Lead Forms, Packages, Proposals, and Contractor Assignments.

### 4.13 Step 3: Select Events - Custom Event Types

*   Users can create custom event types during brand setup by clicking "Add Custom Event" or entering text in a custom event input field.
*   The user types the custom event name (e.g., "Engagement Shoot," "Product Launch," "Charity Gala") and presses Enter or clicks "Add."
*   The system validates that the custom event name is not blank and not a duplicate of an existing default or custom event for this brand.
*   If the event name is blank, the system displays: "Event name cannot be empty."
*   If the event name is a duplicate, the system displays: "This event type already exists."
*   Upon successful addition, the custom event appears in the list with its checkbox automatically selected.
*   Custom event types are saved and behave identically to default event types throughout the platform.
*   There is no limit to the number of custom events that can be created during setup.

### 4.14 Step 3: Validation and Next Button Enablement

*   At least one event type (default or custom) must be selected before the "Next" button is enabled.
*   If no event types are selected, the system displays a message below the "Next" button: "Please select at least one event type to proceed."
*   The system performs real-time validation as the user selects/deselects checkboxes or adds custom events.
*   Once at least one event is selected, the "Next" button becomes enabled.

### 4.15 Step 4: Business Information - Google Maps API Integration

*   The Business Address section integrates with the Google Maps API to provide autocomplete functionality for address entry.
*   As the user types in the Street Address field, the system sends requests to the Google Maps API and displays address suggestions in a dropdown.
*   The user can select an address from the suggestions, which auto-fills all five address fields: Street Address, City, State/Province, Country, and Zip/Postal Code.
*   After an address is selected from Google Maps, the user can manually edit only the Street Address and Zip/Postal Code fields.
*   City, State/Province, and Country fields become read-only after a Google Maps selection to ensure data consistency.
*   If the Google Maps API fails to return results or encounters an error, the system displays: "Unable to fetch address. Please try again later." (PM Note: Suggest allowing manual entry of all fields if API fails repeatedly for better UX).

### 4.16 Step 4: Business Information - Manual Address Entry Fallback

*   If Google Maps API is unavailable or returns no results, users should be able to manually enter all five address fields: Street Address, City, State/Province, Country, and Zip/Postal Code (PM Note: Confirm if manual entry of all fields is allowed as fallback or if Google Maps is strictly required).
*   All five fields are mandatory and cannot be left blank.
*   The system validates that each field contains at least 1 character before enabling the "Next" button.
*   Address information is displayed on client-facing materials like Proposals, Contracts, and Invoices, so accuracy is critical.

### 4.17 Step 4: Service Area - Free-Form Text Input

*   The Service Area section allows users to enter the geographic regions where the brand operates (e.g., "New York, NY," "Los Angeles," "Washington, D.C.," "California").
*   The input is free-form text with no predefined dropdown options, giving users full flexibility in how they define service areas.
*   Users type a service area name and press Enter or click an "Add" button to add it to the list.
*   Each service area is displayed as a tag or chip below the input field, with an "X" icon to remove it.
*   The system validates that service areas are not blank and not duplicates (case-insensitive comparison).
*   If a blank service area is entered, the system displays: "Service area cannot be empty."
*   If a duplicate service area is entered, the system displays: "This service area has already been added."
*   At least one service area must be added before the "Next" button is enabled.
*   Service areas are used in filters, dropdowns, and forms throughout the platform (impacted modules: Project & Event Management, Lead Forms, Packages, Proposals, Calendars & Availability, Automations, Contractor Management, Reports).

### 4.18 Step 4: Validation and Next Button Enablement

*   The "Next" button in Step 4 is disabled until all five Business Information fields are filled and at least one Service Area is added.
*   The system performs real-time validation as the user enters data in address fields and adds service areas.
*   If any required field is missing, the system displays a message below the "Next" button: "Please complete all required fields (Business Address and at least one Service Area)."
*   Once all validations pass, the "Next" button becomes enabled.

### 4.19 Step 5: Social Media Links - Platform Fields

*   Step 5 displays input fields for eight social media platforms: Facebook, Instagram, LinkedIn, X (Twitter), Pinterest, Vimeo, YouTube, and TikTok.
*   Each field displays the platform's icon and a text input box for entering the profile URL.
*   All social media fields are optional; users can leave fields blank for platforms they do not use.
*   The system allows users to add one link per platform (no multiple links for the same platform).
*   Social media links are used in email footers, proposals, client portals, and other brand communications.

### 4.20 Step 5: URL Format Validation

*   The system validates that entered URLs are in proper format, requiring them to start with https:// or [www](http://www).
*   Valid examples: [https://facebook.com/brandname](https://facebook.com/brandname), [https://www.instagram.com/brandname](https://www.instagram.com/brandname), [www.linkedin.com/company/brandname](http://www.linkedin.com/company/brandname)
*   Invalid examples: facebook.com/brandname (missing https:// or [www](http://www).), abc123 (not a URL), instagram/brandname (incomplete URL)
*   If an invalid URL is entered, the system displays an inline error message below the field: "Please enter a valid URL (must start with https:// or [www](http://www).)."
*   The error message appears in real-time as the user types or when the field loses focus (on blur).
*   URLs are not validated for existence or reachability; the system only checks format.

### 4.21 Step 5: Completion and Brand Creation

*   Step 5 has no mandatory fields; users can complete brand setup without adding any social media links.
*   The "Finish" or "Complete Setup" button is always enabled in Step 5, regardless of whether social media links are entered.
*   When the user clicks "Finish," the system performs final validation on all data collected across all 5 steps.
*   If all validations pass, the system commits the brand data to the database, creating a new brand record.
*   The system associates the brand with the agency account and assigns the agency owner as the brand creator.
*   A success message is displayed: "Brand created successfully! You can now start creating projects and inviting team members."
*   The system navigates the user to the Brand Listing page (showing the newly created brand in the table) or to the Brand Settings/Configuration page (to allow immediate further customization).

### 4.22 Backward Navigation Between Steps

*   At any step (Steps 2-5), users can click a "Back" button to return to the previous step.
*   Clicking "Back" from Step 2 returns to Step 1, from Step 3 returns to Step 2, etc.
*   All data entered in previous steps is preserved and displayed when the user navigates backward.
*   Users can edit data in any previous step, and the system re-validates that step when "Next" is clicked again.
*   Backward navigation does not trigger any warnings or data loss; it is a seamless editing experience.
*   Step 1 does not have a "Back" button (it is the first step); instead, it may display a "Cancel" button to exit the wizard.

### 4.23 Wizard Exit Without Completion

*   If the user closes the wizard browser tab, clicks a "Cancel" button, or navigates away using the sidebar menu before completing Step 5, no data is saved.
*   The system does not save draft or partial brand data at any point during the wizard.
*   If the user returns to the Brand Setup wizard later, all fields are reset to their initial state (auto-fill for first brand, empty for subsequent brands).
*   A confirmation modal may be displayed if the user attempts to exit mid-wizard: "Are you sure you want to exit? All entered data will be lost." with "Exit" and "Stay" buttons (PM Note: Confirm if exit confirmation is required or if users can exit freely without warning).

### 4.24 Data Persistence and Temporary Storage

*   During the wizard, all entered data is stored temporarily in the browser's session storage or client-side state management (e.g., React state, Vuex store).
*   Data is not committed to the database until the user clicks "Finish" on Step 5 and all validations pass.
*   If the browser crashes or the user loses connection mid-wizard, all data is lost and cannot be recovered.
*   This design ensures that incomplete brands do not clutter the database and that only fully configured brands are created.

### 4.25 Brand Name Uniqueness Validation

*   The system enforces that each brand name must be unique within the agency account (case-insensitive).
*   When the user enters a brand name in Step 1 and clicks "Next," the system queries the database to check if a brand with the same name already exists for the agency.
*   If a duplicate brand name is found, the system displays an error: "This brand name already exists. Please choose a different name."
*   The "Next" button is disabled until the user enters a unique brand name.
*   Brand names can be identical across different agencies (e.g., Agency A and Agency B can both have a brand named "Pixel Studio"), but not within the same agency.

### 4.26 Image Upload and Cropping UX

*   All image uploads (Main Logo, Secondary Logo, Cover Photo) open a cropping modal immediately after the user selects a file.
*   The cropping modal displays the uploaded image with a draggable crop area, zoom controls, and a "Cancel" button to discard the upload.
*   Users must save the crop before the image is accepted; simply uploading a file without cropping does not complete the upload.
*   The cropping modal includes a "Save" button to confirm the crop and a "Cancel" button to discard and revert to the previous state.
*   After saving, the cropped image preview is displayed in the respective section (Main Logo, Secondary Logo, or Cover Photo).
*   Users can re-upload or re-crop at any time before completing the wizard by clicking "Change" or "Upload New" buttons.

### 4.27 Real-Time Validation and User Feedback

*   All form fields in the wizard provide real-time validation feedback as the user types or interacts with inputs.
*   Error messages appear inline below the field when validation fails (e.g., "Business name is required," "Invalid URL format").
*   Success indicators (e.g., green checkmark icon) appear when fields pass validation.
*   The "Next" button provides visual feedback on its enabled/disabled state through color changes (disabled = gray, enabled = yellow/brand color).
*   Hover states and focus states provide additional visual cues to guide the user through the wizard.

### 4.28 Responsive Design and Mobile Support

*   The Brand Setup wizard is fully responsive and adapts to different screen sizes (desktop, tablet, mobile).
*   On mobile devices, the wizard displays as a full-screen modal or takes up the entire viewport to maximize usable space.
*   Image cropping tools are touch-enabled with pinch-to-zoom gestures on mobile devices.
*   Step indicators are optimized for small screens, potentially displaying as dots or a simplified progress bar.
*   All buttons and input fields meet accessibility standards for touch target sizes (minimum 44x44 pixels).

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

**Field Name**

**Field Type**

**Mandatory**

**Max Length**

**Validation Rules**

**Error Message**

**Step 1: Basic Information**

Business Name

Text Input

Yes

100 characters

1-100 characters, allows letters, numbers, spaces, special characters (&, -, ', "), must be unique within agency (case-insensitive)

"Business name is required" / "Business name must be between 1-100 characters" / "This brand name already exists. Please choose a different name."

Website

URL Input

Yes

255 characters

Must match URL format (https://, http://, [www](http://www).), accepts subdomains and paths

"Website is required" / "Please enter a valid website URL (e.g., [https://example.com](https://example.com))"

Phone Number

Tel Input

Yes

20 characters

Accepts numeric input with optional +, -, (), spaces; no strict format enforcement

"Phone number is required"

**Step 2: Customize Appearance**

Main Logo

File Upload (Image)

Yes

5MB

File format: PNG, JPG, JPEG, WEBP; Max size: 5MB; Must be cropped before saving

"Main logo is required" / "Invalid file format. Please upload PNG, JPG, JPEG, or WEBP" / "File size exceeds 5MB. Please upload a smaller image"

Secondary Logo

File Upload (Image)

No

5MB

File format: PNG, JPG, JPEG, WEBP; Max size: 5MB; Must be cropped in 1:1 aspect ratio

"Invalid file format. Please upload PNG, JPG, JPEG, or WEBP" / "File size exceeds 5MB. Please upload a smaller image"

Brand Color

Color Picker

Yes

N/A

Valid HEX code (#RRGGBB or #RGB) or RGB values (0-255 range)

"Brand color is required" / "Invalid HEX code format" / "RGB values must be between 0-255"

Default Cover Photo

File Upload (Image)

Yes

15MB

File format: PNG, JPG, JPEG, WEBP; Max size: 15MB; Must be cropped before saving

"Cover photo is required" / "Invalid file format. Please upload PNG, JPG, JPEG, or WEBP" / "File size exceeds 15MB. Please upload a smaller image"

**Step 3: Select Events**

Default Event Types

Checkbox (Multiple Select)

Yes (at least 1)

N/A

At least one event type must be selected (default or custom)

"Please select at least one event type to proceed"

Custom Event Name

Text Input

No

50 characters

Not blank, not duplicate of existing event for this brand

"Event name cannot be empty" / "This event type already exists"

**Step 4: Business Information & Service Area**

Street Address

Text Input (with Google Maps Autocomplete)

Yes

255 characters

Not blank; fetched from Google Maps or manually entered; editable after selection

"Street address is required"

City

Text Input (Auto-filled from Google Maps)

Yes

100 characters

Auto-filled from Google Maps; read-only after selection (PM Note: Confirm if manual entry allowed if API fails)

"City is required"

State/Province

Text Input (Auto-filled from Google Maps)

Yes

100 characters

Auto-filled from Google Maps; read-only after selection

"State/Province is required"

Country

Text Input (Auto-filled from Google Maps)

Yes

100 characters

Auto-filled from Google Maps; read-only after selection

"Country is required"

Zip/Postal Code

Text Input

Yes

20 characters

Fetched from Google Maps or manually entered; editable after selection

"Zip/Postal Code is required"

Service Area

Free-Form Text Input (Multiple Tags)

Yes (at least 1)

100 characters per area

Not blank, not duplicate (case-insensitive), at least one service area required

"Service area cannot be empty" / "This service area has already been added" / "Please add at least one service area to proceed"

**Step 5: Social Media Links**

Facebook URL

URL Input

No

255 characters

Must start with https:// or [www](http://www). if entered; can be left blank

"Please enter a valid URL (must start with https:// or [www](http://www).)"

Instagram URL

URL Input

No

255 characters

Must start with https:// or [www](http://www). if entered; can be left blank

"Please enter a valid URL (must start with https:// or [www](http://www).)"

LinkedIn URL

URL Input

No

255 characters

Must start with https:// or [www](http://www). if entered; can be left blank

"Please enter a valid URL (must start with https:// or [www](http://www).)"

X (Twitter) URL

URL Input

No

255 characters

Must start with https:// or [www](http://www). if entered; can be left blank

"Please enter a valid URL (must start with https:// or [www](http://www).)"

Pinterest URL

URL Input

No

255 characters

Must start with https:// or [www](http://www). if entered; can be left blank

"Please enter a valid URL (must start with https:// or [www](http://www).)"

Vimeo URL

URL Input

No

255 characters

Must start with https:// or [www](http://www). if entered; can be left blank

"Please enter a valid URL (must start with https:// or [www](http://www).)"

YouTube URL

URL Input

No

255 characters

Must start with https:// or [www](http://www). if entered; can be left blank

"Please enter a valid URL (must start with https:// or [www](http://www).)"

TikTok URL

URL Input

No

255 characters

Must start with https:// or [www](http://www). if entered; can be left blank

"Please enter a valid URL (must start with https:// or [www](http://www).)"

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

**Action**

**Success Message**

**Display Method**

**Duration**

**Post-Success Action**

Step 1 Completed (Next Clicked)

No message displayed

N/A

N/A

Navigate to Step 2

Step 2 Completed (Next Clicked)

No message displayed

N/A

N/A

Navigate to Step 3

Step 3 Completed (Next Clicked)

No message displayed

N/A

N/A

Navigate to Step 4

Step 4 Completed (Next Clicked)

No message displayed

N/A

N/A

Navigate to Step 5

Main Logo Uploaded & Cropped

"Logo uploaded successfully"

Toast notification (green)

3 seconds

Display logo preview in Main Logo section

Secondary Logo Uploaded & Cropped

"Secondary logo uploaded successfully"

Toast notification (green)

3 seconds

Display logo preview in Secondary Logo section

Cover Photo Uploaded & Cropped

"Cover photo uploaded successfully"

Toast notification (green)

3 seconds

Display cover photo preview; save full image to Library

Custom Event Added

"Custom event '\[Event Name\]' added successfully"

Toast notification (green)

3 seconds

Add event to list with checkbox selected

Service Area Added

"Service area '\[Area Name\]' added successfully"

Toast notification (green) or inline confirmation

2 seconds

Display service area as tag/chip

Brand Created Successfully (Finish Clicked)

"Brand created successfully! You can now start creating projects and inviting team members."

Modal or toast notification (green)

5 seconds or until dismissed

Navigate to Brand Listing page or Brand Settings/Configuration page

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

**Error Scenario**

**Error Message**

**Trigger Condition**

**Display Method**

**User Action Required**

**Access & Permission Errors**

Non-Owner Attempts Brand Creation

"You do not have permission to create brands. Please contact your agency owner."

Admin or Team Member clicks "New Brand" or "Setup Brand" button

Modal or toast notification (red)

Dismiss message; contact agency owner

Subscription Limit Reached

"You have reached the maximum number of brands allowed for your subscription plan. Please upgrade to add more brands."

Agency Owner clicks "New Brand" when limit reached

Modal with "Upgrade Plan" and "Cancel" buttons

Click "Upgrade Plan" to navigate to Subscription page, or "Cancel" to dismiss

**Step 1 Validation Errors**

Business Name Empty

"Business name is required"

User clicks "Next" without entering brand name

Inline error below field (red text)

Enter a valid brand name (1-100 characters)

Business Name Too Long

"Business name must be between 1-100 characters"

User enters >100 characters

Inline error below field (red text)

Shorten brand name to 100 characters or less

Business Name Duplicate

"This brand name already exists. Please choose a different name."

User enters brand name that already exists for this agency (case-insensitive match)

Inline error below field (red text)

Enter a unique brand name

Website Empty

"Website is required"

User clicks "Next" without entering website URL

Inline error below field (red text)

Enter a valid website URL

Website Invalid Format

"Please enter a valid website URL (e.g., [https://example.com](https://example.com))"

User enters URL without https://, http://, or [www](http://www).

Inline error below field (red text)

Correct URL format (e.g., [https://example.com](https://example.com))

Phone Number Empty

"Phone number is required"

User clicks "Next" without entering phone number

Inline error below field (red text)

Enter a valid phone number

**Step 2 Validation Errors**

Main Logo Not Uploaded

"Main logo is required"

User clicks "Next" without uploading main logo

Inline error below upload section (red text)

Upload a main logo (PNG, JPG, JPEG, WEBP, max 5MB)

Invalid Logo File Format

"Invalid file format. Please upload PNG, JPG, JPEG, or WEBP"

User uploads unsupported file type (e.g., .svg, .gif, .bmp)

Modal or toast notification (red)

Upload image in supported format

Logo File Size Exceeds Limit

"File size exceeds 5MB. Please upload a smaller image"

User uploads logo >5MB

Modal or toast notification (red)

Compress image or upload smaller file

Brand Color Not Selected

"Brand color is required"

User clicks "Next" without selecting a brand color

Inline error below color picker (red text)

Select a brand color using picker or HEX/RGB input

Invalid HEX Code Format

"Invalid HEX code format"

User manually enters invalid HEX code (e.g., #GGGGGG, #12)

Inline error below HEX input (red text)

Enter valid HEX code (#RRGGBB or #RGB)

RGB Values Out of Range

"RGB values must be between 0-255"

User enters RGB value <0 or >255

Inline error below RGB input (red text)

Enter RGB values within 0-255 range

Cover Photo Not Uploaded

"Cover photo is required"

User clicks "Next" without uploading cover photo

Inline error below upload section (red text)

Upload a cover photo (PNG, JPG, JPEG, WEBP, max 15MB)

Cover Photo File Size Exceeds Limit

"File size exceeds 15MB. Please upload a smaller image"

User uploads cover photo >15MB

Modal or toast notification (red)

Compress image or upload smaller file

**Step 3 Validation Errors**

No Event Type Selected

"Please select at least one event type to proceed"

User clicks "Next" without selecting any event type

Inline error below event list (red text)

Select at least one default or custom event type

Custom Event Name Empty

"Event name cannot be empty"

User clicks "Add" for custom event without entering name

Inline error below custom event input (red text)

Enter a custom event name

Custom Event Name Duplicate

"This event type already exists"

User enters custom event name that matches existing event (case-insensitive)

Inline error below custom event input (red text)

Enter a unique custom event name

**Step 4 Validation Errors**

Google Maps API Failure

"Unable to fetch address. Please try again later."

Google Maps API returns error or no results

Modal or toast notification (orange/yellow)

Retry address entry or contact support (PM Note: Suggest manual fallback)

Street Address Empty

"Street address is required"

User clicks "Next" without entering street address

Inline error below field (red text)

Enter a valid street address

City Empty

"City is required"

City field is blank after Google Maps fetch or manual entry

Inline error below field (red text)

Select address from Google Maps or enter city manually

State/Province Empty

"State/Province is required"

State field is blank after Google Maps fetch or manual entry

Inline error below field (red text)

Select address from Google Maps or enter state manually

Country Empty

"Country is required"

Country field is blank after Google Maps fetch or manual entry

Inline error below field (red text)

Select address from Google Maps or enter country manually

Zip/Postal Code Empty

"Zip/Postal Code is required"

Zip field is blank after Google Maps fetch or manual entry

Inline error below field (red text)

Enter a valid zip/postal code

Service Area Empty

"Service area cannot be empty"

User clicks "Add" for service area without entering text

Inline error below service area input (red text)

Enter a service area name

Service Area Duplicate

"This service area has already been added"

User enters service area that matches existing one (case-insensitive)

Inline error below service area input (red text)

Enter a unique service area

No Service Area Added

"Please add at least one service area to proceed"

User clicks "Next" without adding any service area

Inline error below service area section (red text)

Add at least one service area

**Step 5 Validation Errors**

Invalid Social Media URL Format

"Please enter a valid URL (must start with https:// or [www](http://www).)"

User enters URL without https:// or [www](http://www). (e.g., facebook.com/brandname)

Inline error below field (red text)

Correct URL format (e.g., [https://facebook.com/brandname](https://facebook.com/brandname))

**General Wizard Errors**

Wizard Data Submission Failure

"Unable to create brand. Please try again later or contact support."

Server error during brand creation on "Finish" click

Modal or toast notification (red)

Retry wizard or contact support

Network Connection Lost

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

User loses internet connection mid-wizard

Modal or toast notification (orange)

Restore internet connection and retry

## **8\. Edge Cases**

**Edge Case**

**System Behavior**

**Expected Outcome**

**Notes**

User closes wizard mid-process (e.g., at Step 3)

No data is saved; user must restart from Step 1 if they return

All entered data is lost; wizard resets to initial state

(PM Note: Confirm if exit confirmation modal is required)

User navigates backward from Step 5 to Step 1 and changes brand name

System preserves all data from Steps 2-5 and re-validates Step 1 when "Next" is clicked

User can edit Step 1 data without losing progress in later steps

Expected behavior

User uploads 10MB cover photo (exceeds 15MB limit)

System displays error: "File size exceeds 15MB. Please upload a smaller image"

Upload is rejected; user must compress or select smaller file

Hard limit enforcement

User enters brand name "Test Brand" and another brand "test brand" already exists

System displays error: "This brand name already exists. Please choose a different name." (case-insensitive match)

User must enter a different brand name

Prevents confusion with similar brand names

Google Maps API is down or returns no results

System displays: "Unable to fetch address. Please try again later."

(PM Note: Confirm if manual entry fallback is allowed or if user is blocked)

API dependency risk

User manually enters address without using Google Maps (if fallback allowed)

All five address fields must be manually entered and validated

User completes Step 4 with manually entered address

Fallback UX for API failure

User selects 15 default event types and adds 10 custom events (25 total)

All 25 event types are saved and available throughout the platform

No limit on number of event types selected

Expected behavior

User adds 20 service areas in Step 4

All 20 service areas are saved and propagated to all dependent modules

No limit on number of service areas

Expected behavior

User enters HEX code "#GGGGGG" (invalid characters)

System displays error: "Invalid HEX code format"

User must enter valid HEX code (#RRGGBB or #RGB)

Input validation

User enters RGB values R: 300, G: 150, B: 35 (R out of range)

System displays error: "RGB values must be between 0-255"

User must correct R value to 0-255 range

Input validation

User uploads .svg logo file (unsupported format)

System displays error: "Invalid file format. Please upload PNG, JPG, JPEG, or WEBP"

Upload is rejected; user must convert file or upload supported format

Format restriction

User crops main logo but clicks "Cancel" in cropping modal

Crop is discarded; Main Logo section remains empty/unchanged

User must re-upload or adjust existing logo

Expected behavior

User completes Step 5 without entering any social media links

Brand is created successfully with no social media links; fields remain empty in Brand Settings

Optional fields; no errors

Expected behavior

First brand auto-fill fetches empty website from agency profile

Website field is empty in Step 1; user must manually enter website

Auto-fill only works if agency profile has data

Graceful handling of missing data

User enters phone number "+44 20 1234 5678" (international format)

Phone number is accepted and saved as entered

System supports international phone formats

Expected behavior

User adds custom event "WEDDING" when default event "Wedding" exists

System displays error: "This event type already exists" (case-insensitive duplicate check)

User must enter a different custom event name

Prevents duplicates

User adds service area "New York" then "new york"

System displays error: "This service area has already been added" (case-insensitive duplicate check)

User must enter a unique service area

Prevents duplicates

Agency Owner has 4 brands, subscription allows 5, creates 5th brand successfully

5th brand is created; "New Brand" button continues to function for future attempts until limit reached

Subscription limit enforced dynamically

Expected behavior

Agency Owner creates 5th brand (limit reached), then clicks "New Brand" again

Subscription limit modal displayed with "Upgrade Plan" button

User cannot create 6th brand without upgrading

Hard subscription enforcement

User rapidly clicks "Next" button multiple times on Step 1

System debounces clicks; only one "Next" action is processed

No duplicate step progression or data submission

UX safeguard

User uploads 4.9MB main logo and 14.8MB cover photo (both within limits)

Both uploads succeed; images are cropped and saved

File size limits enforced per image, not total

Expected behavior

User navigates to Step 5 and clicks "Finish," but server is down

System displays error: "Unable to create brand. Please try again later or contact support."

Brand is not created; user must retry later

Server error handling

User loses internet connection while uploading cover photo

Upload fails; system displays: "Network connection lost. Please check your internet connection and try again."

User must restore connection and retry upload

Network error handling

Browser crashes during Step 3

All wizard data is lost (stored in session storage or client state)

User must restart wizard from Step 1

Data not persisted until "Finish"

User completes wizard and clicks "Finish," but changes mind and wants to edit

User must navigate to Brand Settings/Configuration page to edit brand after creation

Wizard does not allow post-creation editing

Expected behavior

## **9\. Acceptance Criteria**

### 9.1 Functional Requirements

*   ✅ Only Agency Owners can access and complete the Brand Setup wizard
*   ✅ Admins and Team Members are blocked from creating brands with appropriate error messages
*   ✅ Subscription plan limits are enforced before wizard access; users at limit see upgrade modal
*   ✅ First brand auto-fills Business Name, Website, and Phone Number from agency profile
*   ✅ Subsequent brands display empty fields requiring manual entry
*   ✅ All 5 steps display correct step indicators and progress tracking
*   ✅ Step 1 validates Business Name (1-100 chars, unique within agency), Website (URL format), and Phone Number (required)
*   ✅ Step 2 validates Main Logo (mandatory, PNG/JPG/JPEG/WEBP, max 5MB, cropped), Secondary Logo (optional, same validations), Brand Color (mandatory, valid HEX or RGB), and Cover Photo (mandatory, max 15MB, cropped, saved to Library)
*   ✅ Step 3 requires at least one event type (default or custom) to be selected
*   ✅ Custom events can be added with validation for blank and duplicate names
*   ✅ Step 4 integrates Google Maps API for address autocomplete and validation
*   ✅ Step 4 requires all five address fields (Street, City, State, Country, Zip) to be filled
*   ✅ Step 4 requires at least one service area to be added with duplicate and blank validation
*   ✅ Step 5 validates social media URLs (must start with https:// or [www](http://www).) if entered
*   ✅ Step 5 allows completion without entering any social media links (all optional)
*   ✅ Users can navigate backward freely; data is preserved in previous steps
*   ✅ "Next" button is disabled until all mandatory fields in current step are valid
*   ✅ Clicking "Finish" in Step 5 creates brand record in database and displays success message
*   ✅ Exiting wizard before completion does not save any data; all progress is lost

### 9.2 Data Consistency

*   ✅ Brand name uniqueness is enforced within agency (case-insensitive)
*   ✅ Brand name can be identical across different agencies
*   ✅ Auto-filled data from agency profile matches exactly in Step 1 for first brand
*   ✅ Cropped logos and cover photo are saved correctly in database
*   ✅ Full uncropped cover photo is saved to user's Library
*   ✅ Brand color HEX and RGB values are stored accurately
*   ✅ Selected event types (default and custom) are associated with brand
*   ✅ Business address fields are populated correctly from Google Maps or manual entry
*   ✅ Service areas are saved as separate records and propagated to dependent modules
*   ✅ Social media links are stored with correct platform associations

### 9.3 Validation & Error Handling

*   ✅ All mandatory fields display clear error messages when empty or invalid
*   ✅ File upload errors (format, size) display immediately after file selection
*   ✅ URL format errors display in real-time or on field blur
*   ✅ Duplicate brand name error prevents progression to Step 2
*   ✅ Duplicate event name and service area errors prevent adding duplicates
*   ✅ Google Maps API failure displays appropriate error message
*   ✅ Network connection errors display during image uploads
*   ✅ Server errors on brand creation display with retry option

### 9.4 User Experience Validation

*   ✅ Wizard loads within 2 seconds on initial access
*   ✅ Step transitions are smooth with no lag or flash of unstyled content
*   ✅ Image cropping tools are intuitive and responsive
*   ✅ Color picker provides real-time preview of selected color
*   ✅ Google Maps autocomplete displays suggestions within 1 second of typing
*   ✅ Success message displays immediately after brand creation
*   ✅ Navigation to Brand Listing or Settings page occurs within 1 second of success message
*   ✅ Wizard is fully responsive on desktop, tablet, and mobile devices
*   ✅ All interactive elements (buttons, inputs) are accessible via keyboard navigation

### 9.5 Integration & Dependencies

*   ✅ Subscription module correctly provides brand limits for validation
*   ✅ Agency profile data is retrieved accurately for first brand auto-fill
*   ✅ Google Maps API integration fetches and populates address fields correctly
*   ✅ Brand creation triggers updates in dependent modules (Projects, Packages, Lead Forms, etc.)
*   ✅ Brand data is immediately available in Brand Listing page after creation
*   ✅ Brand Settings/Configuration page displays newly created brand correctly

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

**Test cases for Brand Setup / Create New Brand module are available in the separate Excel file:**

[2\_Brand\_Setup\_Create\_New\_Brand\_Test\_Cases.xlsx](https://docs.google.com/spreadsheets/d/1H-GTRkXLdyG3GqoVvMlGYJelUe1SdRNx/edit?usp=drive_link&ouid=105170312247554220827&rtpof=true&sd=true)

## **11\. Dependencies**

**Dependency Type**

**Module/Service Name**

**Dependency Description**

**Impact if Unavailable**

**Mitigation**

Internal Module

Subscription Module

Brand creation limits retrieved based on agency's subscription plan

Cannot enforce brand limits; users may create unlimited brands or be incorrectly blocked

**Developer Note:** Refer to Subscription Module FRD for integration details; implement fallback limit (e.g., default to 1 brand) if module unavailable

Internal Module

Agency Profile Module

First brand auto-fill retrieves Business Name, Company Website, and Phone Number from agency profile

First brand fields are empty; user must manually enter data (no auto-fill benefit)

Gracefully handle missing data; display empty fields if agency profile is incomplete

Internal Module

Brand Listing Module

Newly created brand displayed in Brand Listing table after wizard completion

User cannot view created brand in listing; must access via direct navigation

Display success message with link to Brand Settings page; ensure brand is saved in database

Internal Module

Brand Settings/Configuration Module

Navigation target after brand creation (alternative to Brand Listing)

User cannot access brand settings immediately after creation

Redirect to Brand Listing page instead; ensure user can access settings later

Internal Module

Project Management Module

Brand is used in project creation and filtering

Projects cannot be created without brand; module blocks user

Enforce brand setup before allowing project creation; display prompt

Internal Module

Package Management Module

Brand is required for package creation

Packages cannot be created without brand

Enforce brand setup before allowing package creation

Internal Module

Proposal Management Module

Brand is required for proposal generation

Proposals cannot be created without brand

Enforce brand setup before allowing proposal creation

Internal Module

Lead Form Module

Brand is used in lead form creation and filtering

Lead forms cannot be created without brand

Enforce brand setup before allowing lead form creation

Internal Module

Library Module

Cover photo (full uncropped) is saved to user's Library

Full cover photo not available in Library; only cropped version saved

Save cropped version to brand; inform user that full image was not saved

External API

Google Maps API

Provides address autocomplete and validation in Step 4

Address autocomplete unavailable; user cannot easily enter address

Display error message; (PM Note: Confirm if manual entry fallback allowed) or block Step 4 progression until API is restored

Database

Brands Table

Stores all brand information (name, logos, colors, settings, etc.)

Brand creation fails; wizard cannot complete

Display error: "Unable to create brand. Please try again later or contact support."

Database

Events Table

Stores selected event types (default and custom) associated with brand

Event types not saved; brand created without event associations

Display warning; allow user to add events later in Brand Settings

Database

Service Areas Table

Stores service areas associated with brand

Service areas not saved; brand created without service area associations

Display warning; allow user to add service areas later in Brand Settings

File Storage

Image Storage Service (e.g., AWS S3, Cloudinary)

Stores uploaded logos and cover photos

Image uploads fail; wizard cannot complete Step 2

Display error: "Image upload failed. Please try again later."; ensure images are uploaded before proceeding

Session Storage / Client State

Browser Session Storage or State Management (React, Vue, etc.)

Temporarily stores wizard data during multi-step process

Wizard cannot retain data between steps; user must re-enter data

Implement robust client-side state management; test across browsers

## **12\. References**

### 12.1 Figma Designs: [Figma](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=13406-338056&t=ER8XqMIaN9iUXWJy-0)

### 12.2 PM Notes for Clarification

**The following items require Product Manager confirmation before development:**

1.  **Image Aspect Ratios:**
    *   Main Logo: Confirm exact aspect ratio (appears to be 3:1 or 4:1 for horizontal logos from Figma)
    *   Secondary Logo: 1:1 square aspect ratio (confirmed)
    *   Cover Photo: Confirm exact aspect ratio (appears to be 16:9 for headers from Figma)
2.  **Default Event Types List:**
    *   Visible event types in Figma: Wedding, Corporate Event, Birthday
    *   **PM Note:** Provide complete list of default event types available in Step 3
3.  **Google Maps API Fallback:**
    *   Current design: Display error message if API fails
    *   **PM Note:** Confirm if manual entry of all address fields should be allowed as fallback when API is unavailable
4.  **Wizard Exit Confirmation:**
    *   Current design: No data saved if user exits mid-wizard
    *   **PM Note:** Confirm if exit confirmation modal ("Are you sure? All data will be lost") is required or if users can exit freely
5.  **Social Media URL Validation:**
    *   Current design: URLs must start with https:// or [www](http://www).
    *   **PM Note:** Confirm if URLs like "facebook.com/brandname" (no prefix) should be auto-corrected to "[https://facebook.com/brandname](https://facebook.com/brandname)" or strictly rejected
6.  **Post-Creation Navigation:**
    *   Current design: Navigate to Brand Listing page or Brand Settings page
    *   **PM Note:** Confirm which page is the default destination after brand creation

3\. Brand Settings / Configuration

# **FRD #3: Brand Settings / Configuration**

## **1\. Module Overview**

### 1.1 Module Name

Brand Settings / Configuration

### 1.2 Purpose

The Brand Settings/Configuration module provides a comprehensive interface for agency owners and authorized users to manage and update brand information after initial brand creation. This module encompasses five major sections: Shooting Guide, General, Appearance, Business Information, and Social Media. All changes made in this module propagate automatically to dependent modules including Projects, Proposals, Packages, Lead Forms, Contractor Management, and Reports.

### 1.3 Business Goals

*   Provide centralized brand management for post-creation modifications
*   Enable dynamic updates to brand appearance with live preview functionality
*   Support service-specific shooting guide uploads for contractor quality control
*   Allow flexible business information updates while maintaining data integrity
*   Facilitate social media integration for comprehensive brand communication
*   Ensure brand changes propagate correctly across all platform modules
*   Maintain role-based access control for sensitive brand configurations

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

**Role**

**View Settings**

**Edit General**

**Edit Appearance**

**Edit Business Info**

**Upload Shooting Guides**

**Edit Social Media**

Agency Owner

✅ Full Access

✅ Yes

✅ Yes

✅ Yes

✅ Yes

✅ Yes

Admin

✅ Full Access

❌ Read-Only

❌ Read-Only

❌ Read-Only

✅ Yes

✅ Yes

Team Member

✅ Restricted

❌ Read-Only

❌ Read-Only

❌ Read-Only

❌ Read-Only

❌ Read-Only

### 2.1 Permission Details

**Agency Owner:**

*   Full read/write access to all brand settings sections
*   Can modify brand name, website, phone number, logos, colors, cover photos, business address, and social media links
*   Can upload, replace, and delete shooting guides for all service types
*   All modifications are immediately saved and propagated

**Admin:**

*   Read-only access to General, Appearance, and Business Information sections (cannot edit brand identity or address)
*   Full access to upload and manage Shooting Guides
*   Full access to edit Social Media links
*   Can view all brand settings but cannot modify core brand identity

**Team Member:**

*   Read-only access to brand settings for assigned brands only
*   Cannot modify any configurations
*   Can view but not download shooting guides

## **3\. User Flow**

### 3.1 Accessing Brand Settings Page

3.1 The user logs into Pixelly and navigates to Settings > Brands from the left sidebar menu.

3.2 The system displays the Brand Listing page with all brands in a table format.

3.3 The user clicks the "Configure" button on the desired brand row or clicks anywhere on the brand row.

3.4 The system navigates to the Brand Settings/Configuration page for the selected brand.

3.5 The system displays the brand settings interface with multiple sections/tabs based on the Figma design.

### 3.2 Shooting Guide Section - Accessing and Viewing

3.6 The user navigates to the Shooting Guide section (tab or accordion) within Brand Settings.

3.7 The system displays service types available for the brand (Photo, Video, Content) with upload options for each.

3.8 If a shooting guide is already uploaded for a service, the system displays the PDF file name with a "Download" and "Replace" option.

3.9 If no shooting guide exists for a service, the system displays an "Upload" button.

### 3.3 Shooting Guide Section - Uploading Shooting Guide

3.10 The user clicks "Upload" for a specific service type (e.g., Photo).

3.11 The system opens the file browser for PDF selection.

3.12 The user selects a PDF file from their device.

3.13 The system validates the file format (PDF only) and file size (max 15MB).

3.14 If validation passes, the system uploads the PDF and displays a success message.

3.15 The system displays the uploaded PDF file name with "Download" and "Replace" options.

3.16 The shooting guide becomes accessible to contractors in the Contractor Portal under Event Details tab (Developer Note: Follow Contractor Portal FRD for exact placement).

### 3.4 Shooting Guide Section - Replacing Existing Shooting Guide

3.17 The user clicks "Replace" next to an existing shooting guide.

3.18 The system opens the file browser for PDF selection.

3.19 The user selects a new PDF file.

3.20 The system validates the file and uploads it.

3.21 The system replaces the old shooting guide with the new one (old file is soft-deleted from database but user has no access).

3.22 The system displays a success message: "Shooting guide updated successfully."

### 3.5 General Section - Viewing and Editing

3.23 The user navigates to the General section within Brand Settings.

3.24 The system displays three fields: Brand Name, Website, and Phone Number with current values pre-filled.

3.25 If the user is an Agency Owner, all fields are editable.

3.26 If the user is an Admin or Team Member, all fields are displayed as read-only (grayed out or disabled).

3.27 The Agency Owner clicks into a field (e.g., Brand Name) and modifies the value.

3.28 The user clicks "Save" or "Update" button.

3.29 The system validates the changes (Brand Name uniqueness, Website URL format, Phone Number not blank).

3.30 If validation passes, the system saves the changes and displays a success message: "Brand information updated successfully."

3.31 The updated brand information propagates to all modules where the brand is referenced.

### 3.6 Appearance Section - Viewing Current Settings

3.32 The user navigates to the Appearance section within Brand Settings.

3.33 The system displays current Main Logo, Secondary Logo (if uploaded), Brand Color (with HEX and RGB values), and Default Cover Photo.

3.34 Each element displays a preview (logos as images, color as swatch, cover photo as image).

3.35 If the user is an Agency Owner, "Change" or "Upload New" buttons are displayed for each element.

3.36 If the user is an Admin or Team Member, elements are displayed as read-only with no edit options.

### 3.7 Appearance Section - Updating Main Logo

3.37 The Agency Owner clicks "Change" under Main Logo.

3.38 The system opens the file browser.

3.39 The user selects a new logo image file (PNG, JPG, JPEG, WEBP, max 5MB).

3.40 The system displays the cropping modal with the new image.

3.41 The user adjusts the crop area and clicks "Save."

3.42 The system replaces the old main logo with the new cropped version and updates the preview.

3.43 The system displays a success message: "Main logo updated successfully."

3.44 The new logo propagates to all brand-associated documents, proposals, packages, and projects.

### 3.8 Appearance Section - Updating Brand Color

3.45 The Agency Owner clicks on the Brand Color picker.

3.46 The system displays the color selection interface (gradient selector and HEX/RGB inputs).

3.47 The user selects a new color visually or enters a new HEX/RGB value.

3.48 The system updates the color preview in real-time.

3.49 The user clicks "Save" or "Update."

3.50 The system saves the new brand color and displays a success message.

3.51 The new color propagates to all materials using "Use Brand Color" option (proposals, packages, forms).

### 3.9 Appearance Section - Updating Default Cover Photo

3.52 The Agency Owner clicks "Change" under Default Cover Photo.

3.53 The system opens the file browser.

3.54 The user selects a new cover photo image (PNG, JPG, JPEG, WEBP, max 15MB).

3.55 The system displays the cropping modal with a wide aspect ratio tool.

3.56 The user adjusts the crop and clicks "Save."

3.57 The system saves the full uncropped image to the Library and sets the cropped version as the brand's new default cover photo.

3.58 The system updates the preview and displays a success message.

3.59 The new default cover photo is used for all new projects created under this brand (existing projects retain their original cover photos unless manually updated).

### 3.10 Business Information Section - Viewing and Editing Address

3.60 The user navigates to the Business Information section.

3.61 The system displays five address fields: Street Address, City, State/Province, Country, and Zip/Postal Code with current values pre-filled.

3.62 If the user is an Agency Owner, the Street Address and Zip/Postal Code fields are editable; City, State, and Country are read-only (as per original Google Maps integration logic).

3.63 If the user is an Admin or Team Member, all fields are read-only.

3.64 The Agency Owner modifies the Street Address or Zip/Postal Code.

3.65 The user clicks "Save" or "Update."

3.66 The system validates that all fields are not blank.

3.67 The system saves the updated address and displays a success message.

3.68 The updated address propagates to Proposals, Contracts, Invoices, Lead Forms, and Project creation interfaces.

### 3.11 Social Media Section - Viewing and Editing Links

3.69 The user navigates to the Social Media section.

3.70 The system displays input fields for all 8 social media platforms: Facebook, Instagram, LinkedIn, X, Pinterest, Vimeo, YouTube, and TikTok with current values pre-filled (or empty if not set).

3.71 If the user is an Agency Owner or Admin, all fields are editable.

3.72 If the user is a Team Member, all fields are read-only.

3.73 The user enters or modifies a social media URL.

3.74 The user clicks "Save" or "Update."

3.75 The system validates that entered URLs start with https:// or [www](http://www).

3.76 If validation passes, the system saves the changes and displays a success message.

3.77 The updated social media links are used in email footers, proposals, and client portals.

### 3.12 Social Media Section - Removing a Link

3.78 The user clears a social media URL field (deletes the existing URL).

3.79 The user clicks "Save" or "Update."

3.80 The system saves the empty field and removes the social media link from brand communications.

## **4\. Functional Logic**

### 4.1 Brand Settings Page Structure and Navigation

*   The Brand Settings/Configuration page is accessed from the Brand Listing page by clicking a brand row or "Configure" button.
*   The page displays the brand name prominently at the top with a "Go Back" link to return to Brand Listing.
*   The settings are organized into multiple sections: Shooting Guide, General, Appearance, Business Information, and Social Media (displayed as tabs or accordion sections as per Figma).
*   The system loads the current brand data and displays it in all sections with appropriate edit permissions based on user role.
*   Changes in any section are saved independently; users do not need to save all sections at once.

### 4.2 Role-Based Access Control Enforcement

*   On page load, the system checks the user's role (Agency Owner, Admin, or Team Member) and brand assignments.
*   For Agency Owners, all sections are editable with full CRUD permissions.
*   For Admins, General, Appearance, and Business Information sections are displayed as read-only (fields grayed out or disabled with no "Save" button visible).
*   For Admins, Shooting Guide and Social Media sections are fully editable.
*   For Team Members, all sections are read-only with no edit capabilities.
*   If a user attempts to edit a read-only field via direct API call or browser manipulation, the system rejects the request with error: "You do not have permission to modify this section."

### 4.3 Shooting Guide Section - Upload and Management Logic

*   The Shooting Guide section displays three service types based on what the brand has selected during setup: Photo, Video, and Content.
*   Each service type has its own shooting guide upload area.
*   Only one shooting guide PDF can be uploaded per service type.
*   If no shooting guide exists, an "Upload" button is displayed.
*   If a shooting guide exists, the system displays the PDF file name, a "Download" button, and a "Replace" button.
*   Clicking "Upload" or "Replace" opens the system file browser restricted to PDF files only.
*   The system validates file format (PDF only) and file size (max 15MB).
*   Invalid file format triggers error: "Invalid file format. Please upload a PDF file."
*   File size exceeding 15MB triggers error: "File size exceeds 15MB. Please upload a smaller file."
*   Upon successful upload, the PDF is stored in the database/cloud storage with a unique identifier linked to the brand and service type.
*   The old shooting guide (if replaced) is soft-deleted (removed from user access but retained in database for audit purposes).
*   Contractors can access the shooting guide in the Contractor Portal under the Event Details tab when viewing a project (Developer Note: Follow Contractor Portal FRD for exact UI placement).
*   Contractors can download the shooting guide PDF directly from the portal.

### 4.4 General Section - Field Validation and Update Logic

*   The General section displays three fields: Brand Name (text input, max 100 characters), Website (URL input, max 255 characters), and Phone Number (tel input, max 20 characters).
*   All fields are mandatory; the system does not allow saving if any field is blank.
*   Brand Name must be unique within the agency (case-insensitive check against other brands under the same agency).
*   If a duplicate brand name is entered, the system displays error: "This brand name already exists. Please choose a different name."
*   Website must be in valid URL format (must start with https://, http://, or [www](http://www).).
*   Invalid URL format triggers error: "Please enter a valid website URL (e.g., [https://example.com](https://example.com))."
*   Phone Number accepts any format (international numbers supported); validation only checks that it is not blank.
*   When "Save" is clicked, the system performs all validations and updates the database if all pass.
*   Success message: "Brand information updated successfully."
*   Updated brand name propagates to Brand Listing table, Project listings, Proposal headers, Package displays, and all other modules referencing the brand.

### 4.5 Appearance Section - Logo Update and Propagation

*   The Appearance section displays current Main Logo, Secondary Logo, Brand Color, and Default Cover Photo with live previews.
*   Clicking "Change" or "Upload New" for Main Logo opens the file browser.
*   File validations: PNG, JPG, JPEG, WEBP formats only; max 5MB file size.
*   After file selection, the cropping modal opens with a fixed aspect ratio (PM Note: Confirm exact aspect ratio - appears 3:1 or 4:1 for main logo).
*   The user adjusts the crop area and clicks "Save" in the modal.
*   The system processes the crop, uploads the new logo, and replaces the old one in the database.
*   The new Main Logo immediately appears in the preview and propagates to: Brand Listing icons (if no Secondary Logo), Proposal headers, Contract headers, Package displays, Email signatures, and all brand-associated documents.
*   Secondary Logo follows the same process but with 1:1 square aspect ratio cropping.
*   If Secondary Logo is uploaded, it is used for Brand Listing icons and circular/square UI elements throughout the platform.
*   If Secondary Logo is deleted or not uploaded, the Main Logo is used for all icon placements (cropped to fit).

### 4.6 Appearance Section - Brand Color Update and Propagation

*   Clicking the Brand Color picker opens the color selection interface with gradient selector and HEX/RGB input fields.
*   The system displays current color in real-time preview (swatch).
*   User can select color visually or manually enter HEX code (e.g., #E89623) or RGB values (R: 232, G: 150, B: 35).
*   The system validates HEX codes (must be #RRGGBB or #RGB format) and RGB values (must be 0-255 range).
*   Invalid HEX triggers error: "Invalid HEX code format."
*   RGB out of range triggers error: "RGB values must be between 0-255."
*   Upon clicking "Save," the new brand color is stored in the database and propagated to: Proposals with "Use Brand Color" enabled, Packages with brand color option, Lead Forms with brand color, Buttons and UI elements in client-facing materials.
*   The color change is immediate and does not require page refresh for live preview.

### 4.7 Appearance Section - Default Cover Photo Update and Library Integration

*   Clicking "Change" for Default Cover Photo opens the file browser.
*   File validations: PNG, JPG, JPEG, WEBP formats only; max 15MB file size.
*   After file selection, the cropping modal opens with a wide aspect ratio (PM Note: Confirm exact aspect ratio - appears 16:9 for headers).
*   The user crops the image and clicks "Save."
*   The system saves the full uncropped image to the user's Library (accessible in Projects, Proposals for future use).
*   The system saves the cropped version as the brand's new default cover photo.
*   The new default cover photo is used for: All new projects created under this brand (as the project header image), Proposal headers (if set to use brand default), Client portal headers.
*   Existing projects retain their original cover photos unless manually updated per-project.
*   The cover photo can be overridden on a per-project basis in Project Settings.

### 4.8 Business Information Section - Address Update and Field Restrictions

*   The Business Information section displays five address fields: Street Address, City, State/Province, Country, and Zip/Postal Code.
*   All fields display current values as set during brand setup or previous edits.
*   Agency Owners can edit only Street Address and Zip/Postal Code; City, State, and Country remain read-only (locked based on original Google Maps selection).
*   This restriction maintains data integrity and prevents address inconsistencies (e.g., pairing New York City with California state).
*   If the Agency Owner needs to change City, State, or Country, they must re-enter the address via the Google Maps integration (PM Note: Confirm if re-triggering Google Maps is allowed in settings or only during setup).
*   All five fields are mandatory; saving with any blank field triggers error: "\[Field name\] is required."
*   Updated address information propagates to: Proposals (business address section), Contracts (business address), Invoices (billing address), Lead Forms (location display), Project creation (address auto-fill for event location).

### 4.9 Social Media Section - URL Validation and Update Logic

*   The Social Media section displays eight platform fields: Facebook, Instagram, LinkedIn, X, Pinterest, Vimeo, YouTube, and TikTok.
*   Each field displays current URL if previously saved, or is empty if not set.
*   All fields are optional; users can save with all fields empty or with only some filled.
*   URL validation: Entered URLs must start with https:// or [www](http://www). (e.g., [https://facebook.com/brand](https://facebook.com/brand), [www.instagram.com/brand](http://www.instagram.com/brand)).
*   URLs like "facebook.com/brand" (no prefix) trigger error: "Please enter a valid URL (must start with https:// or [www](http://www).)."
*   The system performs format validation only; it does not check if the URL exists or is reachable.
*   Users can add one URL per platform; no duplicate platform links allowed.
*   Removing a URL (clearing the field) and saving removes the social media link from the brand.
*   Updated social media links are used in: Email footers (automated emails to clients), Proposal footers, Client portal footer, Contract documents (if configured to include social media).

### 4.10 Live Preview and Real-Time Updates

*   The Appearance section provides live preview for logos, brand color, and cover photo.
*   When a user uploads a new logo or cover photo, the preview updates immediately after the crop is saved (before final "Save" button is clicked).
*   When a user selects a new brand color, the color swatch preview updates in real-time as the user adjusts the picker or enters HEX/RGB values.
*   This live preview allows users to visualize changes before committing them to the database.
*   The "Save" or "Update" button finalizes the changes and propagates them across the platform.

### 4.11 Data Propagation Across Modules

*   All changes made in Brand Settings/Configuration propagate automatically to dependent modules.
*   Brand Name changes update: Brand Listing table, Project dropdowns, Proposal headers, Package listings, Lead Form displays, Contractor assignment interfaces, Reports and filters.
*   Logo changes update: Brand Listing icons, Proposal/Contract headers, Package displays, Email signatures, Client portal.
*   Brand Color changes update: Proposals, Packages, Lead Forms, Client-facing materials with "Use Brand Color" enabled.
*   Cover Photo changes update: New projects (as default header), Proposal headers, Client portal headers.
*   Address changes update: Proposals, Contracts, Invoices, Lead Forms, Project creation.
*   Social Media changes update: Email footers, Proposal footers, Client portal footer.
*   The system uses real-time or near-real-time propagation (updates occur within seconds of saving).

### 4.12 Validation and Error Handling

*   All editable fields perform real-time validation as the user types or on field blur.
*   Error messages display inline below the field in red text.
*   The "Save" or "Update" button remains disabled (grayed out) until all validations pass.
*   If the user attempts to save with validation errors, the system does not submit the form and highlights all invalid fields.
*   If a server error occurs during save (e.g., database failure), the system displays: "Unable to save changes. Please try again later or contact support."
*   If a network error occurs (user loses internet connection), the system displays: "Network connection lost. Please check your internet connection and try again."

### 4.13 Permission Enforcement and Security

*   The system enforces role-based permissions at both the UI level (disabling fields) and the API level (rejecting unauthorized requests).
*   If an Admin attempts to edit General, Appearance, or Business Information fields via API manipulation, the request is rejected with HTTP 403 Forbidden: "You do not have permission to modify this section."
*   If a Team Member attempts to edit any field, the request is rejected similarly.
*   All API endpoints for brand updates require authentication and role validation before processing.
*   Audit logs are maintained for all brand changes, recording: User who made the change, Timestamp, Fields modified, Old and new values.

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

**Section**

**Field Name**

**Field Type**

**Mandatory**

**Max Length**

**Validation Rules**

**Error Message**

**Shooting Guide**

Photo Service

Shooting Guide PDF

File Upload

No

15MB

File format: PDF only; Max size: 15MB

"Invalid file format. Please upload a PDF file" / "File size exceeds 15MB. Please upload a smaller file"

Video Service

Shooting Guide PDF

File Upload

No

15MB

File format: PDF only; Max size: 15MB

Same as above

Content Service

Shooting Guide PDF

File Upload

No

15MB

File format: PDF only; Max size: 15MB

Same as above

**General**

Brand Name

Text Input

Yes

100 chars

1-100 characters, allows special characters, unique within agency (case-insensitive)

"Brand name is required" / "Brand name must be between 1-100 characters" / "This brand name already exists. Please choose a different name."

Website

URL Input

Yes

255 chars

Must start with https://, http://, or [www](http://www).

"Website is required" / "Please enter a valid website URL (e.g., [https://example.com](https://example.com))"

Phone Number

Tel Input

Yes

20 chars

Not blank; accepts any format

"Phone number is required"

**Appearance**

Main Logo

File Upload (Image)

Yes

5MB

File format: PNG, JPG, JPEG, WEBP; Max size: 5MB; Must be cropped

"Main logo is required" / "Invalid file format. Please upload PNG, JPG, JPEG, or WEBP" / "File size exceeds 5MB. Please upload a smaller image"

Secondary Logo

File Upload (Image)

No

5MB

File format: PNG, JPG, JPEG, WEBP; Max size: 5MB; 1:1 aspect ratio crop

Same as Main Logo

Brand Color

Color Picker

Yes

N/A

Valid HEX (#RRGGBB or #RGB) or RGB (0-255)

"Brand color is required" / "Invalid HEX code format" / "RGB values must be between 0-255"

Default Cover Photo

File Upload (Image)

Yes

15MB

File format: PNG, JPG, JPEG, WEBP; Max size: 15MB; Must be cropped

"Cover photo is required" / "Invalid file format. Please upload PNG, JPG, JPEG, or WEBP" / "File size exceeds 15MB. Please upload a smaller image"

**Business Information**

Street Address

Text Input

Yes

255 chars

Not blank; editable by Owner only

"Street address is required"

City

Text Input

Yes

100 chars

Not blank; read-only after Google Maps selection

"City is required"

State/Province

Text Input

Yes

100 chars

Not blank; read-only after Google Maps selection

"State/Province is required"

Country

Text Input

Yes

100 chars

Not blank; read-only after Google Maps selection

"Country is required"

Zip/Postal Code

Text Input

Yes

20 chars

Not blank; editable by Owner only

"Zip/Postal Code is required"

**Social Media**

Facebook URL

URL Input

No

255 chars

Must start with https:// or [www](http://www). if entered

"Please enter a valid URL (must start with https:// or [www](http://www).)"

Instagram URL

URL Input

No

255 chars

Must start with https:// or [www](http://www). if entered

Same as above

LinkedIn URL

URL Input

No

255 chars

Must start with https:// or [www](http://www). if entered

Same as above

X (Twitter) URL

URL Input

No

255 chars

Must start with https:// or [www](http://www). if entered

Same as above

Pinterest URL

URL Input

No

255 chars

Must start with https:// or [www](http://www). if entered

Same as above

Vimeo URL

URL Input

No

255 chars

Must start with https:// or [www](http://www). if entered

Same as above

YouTube URL

URL Input

No

255 chars

Must start with https:// or [www](http://www). if entered

Same as above

TikTok URL

URL Input

No

255 chars

Must start with https:// or [www](http://www). if entered

Same as above

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

**Action**

**Success Message**

**Display Method**

**Duration**

**Post-Success Action**

Shooting Guide Uploaded (Photo)

"Shooting guide for Photo service uploaded successfully"

Toast notification (green)

3 seconds

Display file name with Download and Replace options

Shooting Guide Replaced (Video)

"Shooting guide for Video service updated successfully"

Toast notification (green)

3 seconds

Update file name display; old guide soft-deleted

General Information Updated

"Brand information updated successfully"

Toast notification (green)

3 seconds

Refresh page or update display with new data

Main Logo Updated

"Main logo updated successfully"

Toast notification (green)

3 seconds

Update logo preview; propagate to all modules

Secondary Logo Updated

"Secondary logo updated successfully"

Toast notification (green)

3 seconds

Update logo preview; propagate to icon displays

Brand Color Updated

"Brand color updated successfully"

Toast notification (green)

3 seconds

Update color preview; propagate to materials

Cover Photo Updated

"Cover photo updated successfully"

Toast notification (green)

3 seconds

Update preview; save full image to Library; set cropped as default

Business Address Updated

"Business address updated successfully"

Toast notification (green)

3 seconds

Propagate to Proposals, Contracts, Invoices, Forms

Social Media Links Updated

"Social media links updated successfully"

Toast notification (green)

3 seconds

Propagate to email footers, proposals, portals

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

**Error Scenario**

**Error Message**

**Trigger Condition**

**Display Method**

**User Action Required**

**Permission Errors**

Admin Attempts Edit General

"You do not have permission to modify this section."

Admin clicks Save in General section

Toast notification (red) or modal

Contact agency owner for changes

Team Member Attempts Edit

"You do not have permission to modify brand settings."

Team Member attempts any edit

Toast notification (red)

Contact agency owner or admin

**Shooting Guide Errors**

Invalid File Format (Not PDF)

"Invalid file format. Please upload a PDF file."

User uploads non-PDF file

Toast notification (red)

Upload PDF file only

File Size Exceeds 15MB

"File size exceeds 15MB. Please upload a smaller file."

User uploads PDF >15MB

Toast notification (red)

Compress or upload smaller file

**General Section Errors**

Brand Name Empty

"Brand name is required"

User clears brand name and clicks Save

Inline error below field (red)

Enter a brand name

Brand Name Too Long

"Brand name must be between 1-100 characters"

User enters >100 characters

Inline error below field (red)

Shorten brand name

Brand Name Duplicate

"This brand name already exists. Please choose a different name."

User enters name of another brand under same agency

Inline error below field (red)

Enter unique brand name

Website Empty

"Website is required"

User clears website and clicks Save

Inline error below field (red)

Enter website URL

Website Invalid Format

"Please enter a valid website URL (e.g., [https://example.com](https://example.com))"

User enters URL without https://, http://, or [www](http://www).

Inline error below field (red)

Correct URL format

Phone Number Empty

"Phone number is required"

User clears phone number and clicks Save

Inline error below field (red)

Enter phone number

**Appearance Section Errors**

Logo Invalid Format

"Invalid file format. Please upload PNG, JPG, JPEG, or WEBP"

User uploads unsupported image format

Toast notification (red)

Upload supported image format

Logo File Size Exceeds 5MB

"File size exceeds 5MB. Please upload a smaller image"

User uploads logo >5MB

Toast notification (red)

Compress or upload smaller file

Cover Photo Exceeds 15MB

"File size exceeds 15MB. Please upload a smaller image"

User uploads cover photo >15MB

Toast notification (red)

Compress or upload smaller file

Invalid HEX Code

"Invalid HEX code format"

User enters invalid HEX code (e.g., #GGGGGG)

Inline error below HEX input (red)

Enter valid HEX code (#RRGGBB or #RGB)

RGB Out of Range

"RGB values must be between 0-255"

User enters RGB value <0 or >255

Inline error below RGB input (red)

Enter RGB values within 0-255 range

**Business Information Errors**

Street Address Empty

"Street address is required"

User clears street address and clicks Save

Inline error below field (red)

Enter street address

City Empty

"City is required"

City field is blank

Inline error below field (red)

Cannot edit (read-only); contact support if incorrect

State Empty

"State/Province is required"

State field is blank

Inline error below field (red)

Cannot edit (read-only); contact support if incorrect

Country Empty

"Country is required"

Country field is blank

Inline error below field (red)

Cannot edit (read-only); contact support if incorrect

Zip Empty

"Zip/Postal Code is required"

User clears zip code and clicks Save

Inline error below field (red)

Enter zip/postal code

**Social Media Errors**

Invalid URL Format

"Please enter a valid URL (must start with https:// or [www](http://www).)"

User enters URL without https:// or [www](http://www).

Inline error below field (red)

Correct URL format

**System Errors**

Save Failure (Server Error)

"Unable to save changes. Please try again later or contact support."

Database or server error during save

Toast notification (red)

Retry later or contact support

Network Connection Lost

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

User loses internet connection during save

Toast notification (orange)

Restore connection and retry

## **8\. Edge Cases**

**Edge Case**

**System Behavior**

**Expected Outcome**

**Notes**

Admin uploads Shooting Guide, then Agency Owner deletes brand

Shooting guide is deleted along with brand; soft-delete retains in DB

Guide no longer accessible to contractors

Expected behavior

User uploads 14.9MB cover photo (just under limit)

Upload succeeds; image cropped and saved

Cover photo updates successfully

Within limits

User changes brand name to match deleted brand from 6 months ago

System allows (deleted brands not checked for uniqueness)

Brand name change successful

Expected behavior

User uploads Main Logo, crop modal crashes

Upload fails; Main Logo remains unchanged

User must retry upload

Graceful failure

User changes brand color to exact same HEX as current

System saves "change" (no actual change)

Success message displayed; no propagation needed

Minor inefficiency, acceptable

Contractor accesses Shooting Guide while Agency Owner is replacing it

Contractor sees old guide until replacement completes

After replacement, new guide appears on next page load

Race condition handled

User with slow internet uploads 15MB PDF

Upload may take 30+ seconds; loading indicator required

Upload completes after delay; success message displays

UX consideration

Secondary Logo deleted, brand listing uses Main Logo for icons

Main Logo appears in brand listing circular icons (cropped to fit)

Icon displays correctly using Main Logo

Expected behavior

User changes Street Address from "123 Main St" to "124 Main St"

Only Street Address updates; City, State, Country, Zip remain unchanged

Address updates correctly without affecting read-only fields

Expected behavior

User enters social media URL with trailing slash "[https://facebook.com/brand/](https://facebook.com/brand/)"

System accepts URL as-is (no normalization)

URL saved with trailing slash; works correctly in links

Acceptable

User removes all social media links (clears all fields)

All links removed from brand; email footers show no social icons

Social media section empty; no links displayed

Expected behavior

Brand has 3 services (Photo, Video, Content), user uploads guides for Photo and Video only

Content service shows "Upload" button; Photo and Video show Download/Replace

Guides uploaded for 2 services; 1 service has no guide

Expected behavior

User uploads 100-character brand name (at max limit)

Validation passes; brand name saved

Brand name displays correctly; may truncate in some UI areas with ellipsis

Expected behavior

User enters invalid HEX "#GGG" then corrects to "#EEE"

First entry shows error; corrected entry passes validation

Validation works correctly; error clears on fix

Expected behavior

User changes brand logo while proposal with old logo is being generated

Proposal generation uses brand data snapshot from start; old logo appears

Proposals in-progress not affected by mid-generation changes

Expected behavior

Brand color updated, existing proposals with "Use Brand Color" open in client view

Existing proposals retain old color (generated at creation time)

New proposals use new color; old proposals unchanged

Expected behavior

Cover photo updated, project created 1 second before update uses old photo

Project uses old default cover photo (set at creation time)

New projects use new cover; existing projects unchanged

Expected behavior

User on Brand Settings page, another user (Agency Owner) changes brand name

First user's page does not auto-refresh; sees old name until manual refresh

Page displays stale data until refresh

Acceptable (no real-time sync)

## **9\. Acceptance Criteria**

### 9.1 Functional Requirements

*   ✅ Agency Owners have full edit access to all Brand Settings sections
*   ✅ Admins have read-only access to General, Appearance, Business Information; full access to Shooting Guide and Social Media
*   ✅ Team Members have read-only access to all sections
*   ✅ Shooting Guides can be uploaded for each service type (Photo, Video, Content) with PDF validation (max 15MB)
*   ✅ Replacing Shooting Guide removes old file (soft-delete) and uploads new file
*   ✅ Contractors can download Shooting Guides from Contractor Portal Event Details tab
*   ✅ General section validates Brand Name (1-100 chars, unique within agency), Website (URL format), Phone Number (not blank)
*   ✅ Appearance section allows updating Main Logo, Secondary Logo, Brand Color, and Cover Photo with live preview
*   ✅ Logos are cropped (Main: wide aspect ratio, Secondary: 1:1 square) before saving
*   ✅ Brand Color validates HEX codes and RGB values (0-255 range)
*   ✅ Cover Photo saves full image to Library and cropped version as brand default
*   ✅ Business Information allows editing only Street Address and Zip; City, State, Country are read-only
*   ✅ Social Media section validates URL format (must start with https:// or [www](http://www).) for all 8 platforms
*   ✅ All changes propagate correctly to dependent modules (Projects, Proposals, Packages, Forms, Contractor Portal)

### 9.2 Data Consistency

*   ✅ Brand Name uniqueness enforced within agency (case-insensitive)
*   ✅ Updated brand information displays correctly across all modules
*   ✅ Logo changes propagate to Brand Listing, Proposals, Contracts, Packages, Email signatures
*   ✅ Brand Color changes propagate to materials using "Use Brand Color" option
*   ✅ Cover Photo changes apply to new projects (existing projects retain original)
*   ✅ Address changes propagate to Proposals, Contracts, Invoices, Lead Forms
*   ✅ Social Media links propagate to email footers, proposals, client portals

### 9.3 Validation & Error Handling

*   ✅ All mandatory fields display clear error messages when empty or invalid
*   ✅ File upload errors (format, size) display immediately after file selection
*   ✅ URL format errors display in real-time or on field blur
*   ✅ Duplicate brand name error prevents saving
*   ✅ Permission errors prevent unauthorized edits (UI and API level)
*   ✅ Server and network errors display with retry guidance

### 9.4 User Experience

*   ✅ Live preview updates for logos, colors, and cover photos before saving
*   ✅ Real-time validation feedback on all editable fields
*   ✅ Success messages display after each section save
*   ✅ Page loads within 2 seconds with all brand data pre-filled
*   ✅ Image cropping tools are intuitive and responsive
*   ✅ Read-only fields are clearly indicated (grayed out or disabled)

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

**Test cases for Brand Settings / Configuration module are available in the separate Excel file:**

[3\_Brand\_Settings\_Configuration\_Test\_Cases.xlsx](https://docs.google.com/spreadsheets/d/1FiYVV0QfWjIz1uTnAfQq7NxlZwxFeHMA/edit?usp=drive_link&ouid=105170312247554220827&rtpof=true&sd=true)

## **11\. Dependencies**

**Dependency Type**

**Module/Service Name**

**Dependency Description**

**Impact if Unavailable**

**Mitigation**

Internal Module

Brand Listing Module

Entry point to Brand Settings via Configure button or row click

Users cannot access Brand Settings

Provide direct URL access or navigation from other modules

Internal Module

Project Management Module

Updated brand information used in project creation and displays

Projects may show outdated brand data

Manual refresh or delayed propagation acceptable

Internal Module

Proposal Management Module

Updated logos, colors, address used in proposals

New proposals may use old brand data

Proposals generated with brand data snapshot at creation time

Internal Module

Package Management Module

Updated brand information displayed in packages

Packages may show outdated brand data

Manual refresh or delayed propagation acceptable

Internal Module

Lead Form Module

Updated address and brand info used in lead forms

Forms may show outdated data

Manual refresh or delayed propagation acceptable

Internal Module

Contractor Portal

Shooting Guides accessible in Contractor Portal Event Details tab

Contractors cannot access guides

**Developer Note:** Follow Contractor Portal FRD for integration

Internal Module

Library Module

Cover photos saved to Library for reuse

Full cover photo not saved to Library

Only cropped version available

External API

Google Maps API

Used during setup for address; not used in Brand Settings

No impact (address already set)

Address editing limited to Street and Zip only

Database

Brands Table

Stores all brand settings (logos, colors, address, etc.)

Brand Settings page cannot load or save

Display error: "Unable to load brand settings. Please try again later."

File Storage

Cloud Storage (AWS S3, Cloudinary, etc.)

Stores uploaded Shooting Guides, logos, cover photos

Image/PDF uploads fail

Display error: "Upload failed. Please try again later."

## **12\. References**

### 12.1 Figma Designs: [Figma](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=13441-273806&t=ER8XqMIaN9iUXWJy-0)

4\. Brand Domain Name Section

# **FRD #4: Brand Domain Name Section**

## **1\. Module Overview**

### 1.1 Module Name

Brand Domain Name Section

### 1.2 Purpose

The Brand Domain Name Section allows agency owners to configure and manage domain names for their brands' client portals. Each brand receives a default Pixelly subdomain (e.g., brandname.pixelly.com) which can be customized. Additionally, agency owners can connect custom domains (e.g., portal.brandname.com) by configuring DNS settings. This module handles domain uniqueness validation, change limit enforcement (maximum 3 changes), DNS setup instructions, verification, and email notifications for connection status.

### 1.3 Business Goals

*   Provide professional, branded client portal URLs for enhanced brand identity
*   Support custom domain connections for agencies wanting full brand control
*   Enforce domain change limits to prevent frequent URL disruption for clients
*   Preserve old domains to prevent broken links in existing agreements and portals
*   Automate DNS verification and provide clear setup guidance
*   Notify users of domain connection success or failure via email

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

**Role**

**View Domain Settings**

**Edit Default Subdomain**

**Connect Custom Domain**

**Change Domain After Limit**

**Receive Email Notifications**

Agency Owner

✅ Yes

✅ Yes (within 3 changes)

✅ Yes

❌ No (must contact support)

✅ Yes

Admin

✅ Yes

❌ No

❌ No

❌ No

❌ No

Team Member

✅ Yes (Read-Only)

❌ No

❌ No

❌ No

❌ No

### 2.1 Permission Details

**Agency Owner:**

*   Full access to view and edit domain settings
*   Can change default Pixelly subdomain up to 3 times
*   Can connect and disconnect custom domains
*   Receives email notifications for DNS verification success/failure
*   After 3 domain changes, must contact Pixelly support for additional changes

**Admin:**

*   Read-only access to domain settings
*   Cannot modify default subdomain or connect custom domains
*   Does not receive email notifications

**Team Member:**

*   Read-only access to domain settings for assigned brands only
*   Cannot modify any domain configurations

## **3\. User Flow**

### 3.1 Accessing Brand Domain Name Section

3.1 The user navigates to Settings > Brands from the left sidebar.

3.2 The user clicks on a brand row or "Configure" button to access Brand Settings.

3.3 The user navigates to the "Brand Domain Name" section/tab within Brand Settings.

3.4 The system displays the current default Pixelly subdomain (e.g., brandname.pixelly.com).

3.5 The system displays the number of domain changes remaining (e.g., "You have 2 changes remaining").

3.6 If a custom domain is connected, the system displays it with a "Disconnect" option.

### 3.2 Changing Default Pixelly Subdomain (First or Second Change)

3.7 The Agency Owner clicks "Edit" or "Change" next to the default subdomain field.

3.8 The system enables the subdomain input field for editing.

3.9 The user enters a new subdomain name (e.g., "newbrandname" for newbrandname.pixelly.com).

3.10 The system performs real-time validation to check if the subdomain is available (not already taken by another brand system-wide).

3.11 If the subdomain is available, the system displays a green checkmark or "Available" message.

3.12 If the subdomain is taken, the system displays an error: "This subdomain is already in use. Please choose another."

3.13 The user clicks "Save" to confirm the change.

3.14 The system updates the subdomain, decrements the change counter, and displays a success message.

### 3.3 Changing Default Subdomain (Third and Final Change)

3.15 Before the third change, the system displays a warning modal: "This is your last attempt to modify the domain name. You will not be able to change the domain name after this. Please contact Pixelly if you have any questions."

3.16 The user clicks "Proceed" to continue or "Cancel" to abort.

3.17 If the user proceeds, the subdomain change is processed as described in steps 3.8-3.14.

3.18 After the third change, the system displays: "You have used all 3 domain changes. Contact Pixelly support for additional changes."

3.19 The "Edit" or "Change" button is replaced with a "Contact Support" link.

### 3.4 Attempting Domain Change After Limit Reached

3.20 If the user has already made 3 changes and clicks "Contact Support," the system opens a support contact form or redirects to Pixelly's support page.

3.21 The system does not allow further domain changes via the UI until support manually resets the counter.

### 3.5 Connecting a Custom Domain

3.22 The Agency Owner clicks "Connect Custom Domain" button in the Brand Domain Name section.

3.23 The system displays a modal or expanded section requesting the custom subdomain (e.g., "portal" for portal.brandname.com).

3.24 The user enters the desired subdomain and domain (e.g., "portal.brandname.com").

3.25 The system displays dynamic CNAME DNS setup instructions: "Add a CNAME record with the following details: Name: portal, Value: brandname.pixelly.com, TTL: Automatic or 3600."

3.26 The user adds the CNAME record in their domain registrar's DNS settings.

3.27 The user clicks "Verify Connection" in the Pixelly interface.

3.28 The system attempts to verify the DNS CNAME record by querying DNS servers.

3.29 If verification succeeds within 15 minutes to 1 hour, the system displays a success message and sends a success email to the agency owner.

3.30 If verification fails or takes longer than expected, the system continues checking in the background and sends an email with the result (success or failure).

### 3.6 DNS Verification Success Email

3.31 The system sends an email to the agency owner with subject: "Custom Domain Connected Successfully - \[Brand Name\]."

3.32 The email body contains: "Your custom domain \[portal.brandname.com\] has been successfully connected to your \[Brand Name\] client portal. Clients can now access the portal using this URL."

3.33 (PM Note: Confirm exact email content and format.)

### 3.7 DNS Verification Failure Email

3.34 If DNS verification fails after 24 hours, the system sends an email to the agency owner with subject: "Custom Domain Connection Failed - \[Brand Name\]."

3.35 The email body contains: "We were unable to verify the CNAME record for \[portal.brandname.com\]. Please check your DNS settings and ensure the CNAME record is correctly configured. Common issues: Incorrect CNAME value, DNS propagation delay (can take up to 48 hours), Typo in subdomain name. Need help? Contact Pixelly support."

3.36 (PM Note: Confirm exact email content, error details, and troubleshooting guidance.)

### 3.8 Disconnecting a Custom Domain

3.37 The user clicks "Disconnect" next to the connected custom domain.

3.38 The system displays a confirmation modal: "Are you sure you want to disconnect \[portal.brandname.com\]? Clients using this URL will no longer be able to access the portal."

3.39 The user clicks "Confirm" to proceed or "Cancel" to abort.

3.40 If confirmed, the system removes the custom domain association and reverts to the default Pixelly subdomain.

3.41 The system displays a success message: "Custom domain disconnected successfully. Portal reverted to \[brandname.pixelly.com\]."

## **4\. Functional Logic**

### 4.1 Default Pixelly Subdomain Assignment

*   When a brand is created, the system automatically generates a default subdomain based on the brand name (e.g., brand name "Pixel Studios" → subdomain "pixelstudios.pixelly.com").
*   The subdomain is generated by removing spaces, special characters, and converting to lowercase (e.g., "O'Reilly & Co." → "oreillyco.pixelly.com").
*   The system validates that the generated subdomain is unique system-wide (not already used by another brand across all agencies).
*   If the subdomain is taken, the system appends a numeric suffix (e.g., "pixelstudios1.pixelly.com").
*   The default subdomain is displayed in the Brand Domain Name section and can be changed by the agency owner up to 3 times.

### 4.2 Domain Change Limit Enforcement

*   Each brand has a domain change counter initialized at 0 (0 changes made).
*   When the agency owner changes the subdomain for the first time, the counter increments to 1.
*   The system displays the number of remaining changes (e.g., "You have 2 changes remaining" after the first change).
*   Before the third change, the system displays a warning modal: "This is your last attempt to modify the domain name. You will not be able to change the domain name after this. Please contact Pixelly if you have any questions."
*   After the third change, the counter reaches 3, and the system disables the "Edit" button.
*   The "Edit" button is replaced with a "Contact Support" link that redirects to Pixelly's support page or opens a support form.
*   The system enforces the limit at the database level; attempts to change the domain via API calls after 3 changes are rejected with error: "Domain change limit reached. Contact support."

### 4.3 Old Domain Preservation

*   When the subdomain is changed, the system does not delete the old subdomain from the database.
*   Old subdomains are marked as "inactive" but retained in the system indefinitely (preserved forever).
*   Both the old and new subdomains work simultaneously, redirecting to the same brand portal.
*   This ensures that existing client portal links in contracts, proposals, and emails remain functional and do not break.
*   Clients using old subdomain URLs are seamlessly redirected to the portal without errors.

### 4.4 Subdomain Uniqueness Validation

*   When the user enters a new subdomain, the system performs a real-time check against the database to ensure it is not already in use by another brand system-wide.
*   The validation query checks all active and inactive subdomains across all agencies to prevent conflicts.
*   If the subdomain is available, the system displays "Available" or a green checkmark.
*   If the subdomain is taken, the system displays error: "This subdomain is already in use. Please choose another."
*   The system allows only lowercase letters, numbers, and hyphens in subdomains (no spaces, special characters, or underscores).
*   Subdomains must be 3-50 characters long.
*   Invalid characters or length triggers error: "Subdomain must be 3-50 characters and contain only lowercase letters, numbers, and hyphens."

### 4.5 Custom Domain Connection - DNS Setup Instructions

*   When the user clicks "Connect Custom Domain," the system displays a modal or expanded section with DNS setup instructions.
*   The user is prompted to enter their custom subdomain and domain (e.g., "portal" for portal.brandname.com).
*   The system validates that the custom domain format is correct (subdomain + domain, e.g., portal.brandname.com).
*   The system dynamically generates CNAME setup instructions: "Add a CNAME record in your DNS settings: Name: \[subdomain\], Value: \[brandname.pixelly.com\], TTL: Automatic or 3600."
*   The instructions are displayed clearly with copy-paste functionality for the CNAME value.
*   The system provides a "Verify Connection" button for the user to trigger DNS verification after adding the CNAME record.

### 4.6 DNS Verification Process

*   When the user clicks "Verify Connection," the system queries DNS servers to check if the CNAME record exists and points to the correct value (brandname.pixelly.com).
*   The initial verification attempt occurs immediately (within seconds).
*   If the CNAME record is found and correct, the system displays a success message and sends a success email to the agency owner.
*   If the CNAME record is not found or incorrect, the system displays: "DNS verification in progress. We'll send you an email once verification is complete (usually within 15 minutes to 1 hour)."
*   The system continues checking the DNS record in the background every 15 minutes for up to 24 hours.
*   If verification succeeds within 24 hours, the system sends a success email.
*   If verification fails after 24 hours, the system sends a failure email with troubleshooting guidance.
*   (PM Note: Confirm exact wait time before sending failure email - 24 hours suggested.)

### 4.7 Email Notifications - Success

*   Success email subject: "Custom Domain Connected Successfully - \[Brand Name\]"
*   Email sent to: Agency owner's email address
*   Email trigger: DNS verification succeeds
*   Email body (PM Note: Confirm exact content):
    *   "Your custom domain \[portal.brandname.com\] has been successfully connected to your \[Brand Name\] client portal."
    *   "Clients can now access the portal using this URL: [https://portal.brandname.com](https://portal.brandname.com)"
    *   "The default Pixelly subdomain (brandname.pixelly.com) will continue to work."
    *   "If you have any questions, contact Pixelly support."

### 4.8 Email Notifications - Failure

*   Failure email subject: "Custom Domain Connection Failed - \[Brand Name\]"
*   Email sent to: Agency owner's email address
*   Email trigger: DNS verification fails after 24 hours
*   Email body (PM Note: Confirm exact content and error details):
    *   "We were unable to verify the CNAME record for \[portal.brandname.com\] after 24 hours."
    *   "Please check your DNS settings and ensure the CNAME record is correctly configured:"
    *   "Name: \[subdomain\], Value: \[brandname.pixelly.com\], TTL: Automatic or 3600"
    *   "Common issues: Incorrect CNAME value, DNS propagation delay (can take up to 48 hours), Typo in subdomain name"
    *   "After correcting the issue, click 'Verify Connection' again in your Brand Settings."
    *   "Need help? Contact Pixelly support at support@pixelly.com."

### 4.9 Custom Domain Disconnection

*   When the user clicks "Disconnect" next to a connected custom domain, the system displays a confirmation modal.
*   The modal warns: "Are you sure you want to disconnect \[portal.brandname.com\]? Clients using this URL will no longer be able to access the portal."
*   If the user confirms, the system removes the custom domain association from the database.
*   The portal reverts to using only the default Pixelly subdomain (brandname.pixelly.com).
*   The system displays success message: "Custom domain disconnected successfully. Portal reverted to \[brandname.pixelly.com\]."
*   The custom domain no longer routes to the brand portal; clients using the custom URL receive a "Page Not Found" or similar error.

### 4.10 Simultaneous Domain Functionality

*   Both the default Pixelly subdomain and the custom domain (if connected) work simultaneously.
*   Clients can access the portal using either URL: brandname.pixelly.com or portal.brandname.com.
*   No grace period is needed; both domains are active immediately after custom domain connection.
*   Old subdomains (from previous changes) also continue to work and redirect to the portal.
*   This ensures maximum flexibility and prevents broken links for clients.

### 4.11 Role-Based Access Enforcement

*   Only Agency Owners can edit subdomains and connect custom domains.
*   Admins and Team Members have read-only access; all edit buttons and "Connect Custom Domain" option are hidden or disabled.
*   If an Admin or Team Member attempts to modify domain settings via API manipulation, the request is rejected with HTTP 403 Forbidden: "You do not have permission to modify domain settings."
*   All domain change and custom domain connection actions are logged with user ID, timestamp, and action details for audit purposes.

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

**Field Name**

**Field Type**

**Mandatory**

**Max Length**

**Validation Rules**

**Error Message**

Default Pixelly Subdomain

Text Input

Yes

50 characters

3-50 characters, lowercase letters, numbers, hyphens only; unique system-wide

"Subdomain is required" / "Subdomain must be 3-50 characters" / "This subdomain is already in use. Please choose another." / "Subdomain can only contain lowercase letters, numbers, and hyphens"

Custom Domain Subdomain

Text Input

Yes (if connecting)

50 characters

Valid subdomain format (e.g., "portal", "client"); lowercase letters, numbers, hyphens only

"Custom subdomain is required" / "Invalid subdomain format"

Custom Domain

Text Input

Yes (if connecting)

100 characters

Valid domain format (e.g., "brandname.com"); must be user's owned domain

"Custom domain is required" / "Invalid domain format"

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

**Action**

**Success Message**

**Display Method**

**Duration**

**Post-Success Action**

Default Subdomain Changed

"Default subdomain updated successfully to \[newsubdomain.pixelly.com\]"

Toast notification (green)

3 seconds

Update display; decrement change counter

Custom Domain Connection Initiated

"DNS verification in progress. We'll send you an email once verification is complete."

Toast notification (blue)

5 seconds

Begin background DNS checks

Custom Domain Connected (Immediate)

"Custom domain \[portal.brandname.com\] connected successfully!"

Toast notification (green)

5 seconds

Display custom domain with Disconnect option

Custom Domain Disconnected

"Custom domain disconnected successfully. Portal reverted to \[brandname.pixelly.com\]"

Toast notification (green)

3 seconds

Remove custom domain from display

DNS Verification Success (Email)

Email sent with subject "Custom Domain Connected Successfully - \[Brand Name\]"

Email to agency owner

N/A

Custom domain becomes active

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

**Error Scenario**

**Error Message**

**Trigger Condition**

**Display Method**

**User Action Required**

Subdomain Already in Use

"This subdomain is already in use. Please choose another."

User enters subdomain already taken by another brand

Inline error below field (red)

Enter a different subdomain

Invalid Subdomain Characters

"Subdomain can only contain lowercase letters, numbers, and hyphens"

User enters spaces, special characters, or uppercase letters

Inline error below field (red)

Correct subdomain format

Subdomain Too Short/Long

"Subdomain must be 3-50 characters"

User enters <3 or >50 characters

Inline error below field (red)

Adjust subdomain length

Domain Change Limit Reached

"Domain change limit reached. You have used all 3 changes. Contact Pixelly support for additional changes."

User attempts 4th domain change

Modal or toast notification (orange)

Click "Contact Support" link

Invalid Custom Domain Format

"Invalid domain format. Please enter a valid domain (e.g., brandname.com)"

User enters malformed custom domain

Inline error below field (red)

Correct domain format

DNS Verification Failure (24 Hours)

Email sent with subject "Custom Domain Connection Failed - \[Brand Name\]"

DNS CNAME not found after 24 hours

Email to agency owner

Check DNS settings, retry verification

Admin Attempts Domain Edit

"You do not have permission to modify domain settings."

Admin clicks Edit or Connect Custom Domain

Toast notification (red)

Contact agency owner

Server Error During Save

"Unable to save domain changes. Please try again later or contact support."

Database or server error during domain update

Toast notification (red)

Retry later or contact support

## **8\. Edge Cases**

**Edge Case**

**System Behavior**

**Expected Outcome**

**Notes**

User changes subdomain 3 times in rapid succession

Each change decrements counter; warning before 3rd; limit enforced after 3rd

After 3 changes, "Contact Support" link displayed

Expected behavior

User connects custom domain, DNS takes 48 hours to propagate

Background checks continue for 24 hours; failure email sent if not verified

User receives failure email at 24 hours, can retry after DNS propagates

DNS delays are common

User disconnects custom domain while clients are using it

Custom domain stops routing to portal; clients see error

Clients using custom URL receive "Page Not Found" error

User warned in disconnect confirmation modal

User changes default subdomain after connecting custom domain

Both old and new subdomains work; custom domain unaffected

All URLs (old subdomain, new subdomain, custom domain) route to portal

Expected behavior

User connects custom domain "portal.brandname.com" then tries "client.brandname.com"

First domain disconnected, second domain connection initiated

Only one custom domain allowed per brand at a time

System allows only 1 custom domain

User enters custom domain belonging to another user's brand

DNS verification fails (CNAME won't match)

Failure email sent; domain not connected

Security measure

Agency Owner uses all 3 changes, then brand is transferred to new owner

New owner inherits change limit; cannot make further changes without support

Contact Support link displayed for new owner

Change limit tied to brand, not user

User corrects CNAME record after initial verification failure

User clicks "Verify Connection" again; verification succeeds

Custom domain connects successfully

Retry mechanism works

User deletes CNAME record after custom domain is connected

Portal becomes inaccessible via custom domain; default subdomain still works

Clients using custom URL see error; default URL works

User should disconnect formally

## **9\. Acceptance Criteria**

### 9.1 Functional Requirements

*   ✅ Each brand receives a unique default Pixelly subdomain on creation
*   ✅ Agency Owners can change default subdomain up to 3 times
*   ✅ Warning modal displayed before 3rd (final) subdomain change
*   ✅ After 3 changes, "Edit" button replaced with "Contact Support" link
*   ✅ Subdomain uniqueness validated in real-time system-wide
*   ✅ Old subdomains preserved and continue to work after changes
*   ✅ Agency Owners can connect custom domains via CNAME DNS setup
*   ✅ Dynamic CNAME setup instructions generated for user's domain
*   ✅ DNS verification process checks CNAME record and reports status
*   ✅ Success email sent to agency owner when custom domain connects
*   ✅ Failure email sent after 24 hours if DNS verification fails
*   ✅ Custom domain and default subdomain work simultaneously
*   ✅ Custom domain can be disconnected with confirmation modal
*   ✅ Admins and Team Members have read-only access to domain settings

### 9.2 Validation & Security

*   ✅ Subdomain format validated (3-50 chars, lowercase, numbers, hyphens only)
*   ✅ Duplicate subdomain rejected with clear error message
*   ✅ Custom domain format validated before DNS setup
*   ✅ Permission enforcement prevents non-owners from editing domains
*   ✅ API-level validation rejects unauthorized domain changes

### 9.3 Email Notifications

*   ✅ Success email sent immediately after DNS verification succeeds
*   ✅ Failure email sent after 24 hours if verification fails
*   ✅ Emails sent only to agency owner (not admins or team members)
*   ✅ Email content includes troubleshooting guidance for failures
*   ✅ (PM Note: Confirm exact email content and format)

### 9.4 User Experience

*   ✅ Real-time subdomain availability check provides immediate feedback
*   ✅ Clear visual indication of remaining domain changes
*   ✅ Warning modal prevents accidental use of final domain change
*   ✅ DNS setup instructions are clear and easy to copy-paste
*   ✅ Verify Connection button provides progress feedback
*   ✅ All error messages are actionable and user-friendly

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

**Test cases for Brand Domain Name Section are available in the separate Excel file:**

[4\_Brand\_Domain\_Name\_Section\_Test\_Cases.xlsx](https://docs.google.com/spreadsheets/d/1HuzDXNHJeoDgsoRC8ckJhHT0MN1JLTfK/edit?usp=drive_link&ouid=105170312247554220827&rtpof=true&sd=true)

## **11\. Dependencies**

**Dependency Type**

**Module/Service Name**

**Dependency Description**

**Impact if Unavailable**

**Mitigation**

Internal Module

Brand Settings Module

Entry point to Domain Name section

Users cannot access domain settings

Provide direct URL or alternative navigation

External Service

DNS Servers

DNS CNAME verification for custom domains

Custom domain connections cannot be verified

Display error; allow manual retry later

External Service

Email Service (SMTP)

Sends success/failure emails to agency owner

Users not notified of verification status

Display status in UI as fallback

Database

Brands Table

Stores default subdomain, custom domain, change counter

Domain settings cannot load or save

Display error: "Unable to load domain settings"

API

Domain Verification API

Checks CNAME record and validates custom domains

Custom domain setup fails

Display error; suggest contacting support

## **12\. References**

### 12.1 Figma Designs: [4\_Brand\_Domain\_Name\_Section\_Test\_Cases.xlsx](https://docs.google.com/spreadsheets/d/1HuzDXNHJeoDgsoRC8ckJhHT0MN1JLTfK/edit?usp=drive_link&ouid=105170312247554220827&rtpof=true&sd=true)

5\. Client Portal Settings Section

# **FRD #5: Client Portal Settings Section**

## **1\. Module Overview**

### 1.1 Module Name

Client Portal Settings Section

### 1.2 Purpose

The Client Portal Settings Section allows agency owners and admins to configure how clients access and view their brand's client portal. This includes managing the portal link display, controlling automatic inclusion of portal links in automated emails, customizing portal appearance (logo, colors, title), and providing a live preview of portal customizations.

### 1.3 Business Goals

*   Provide flexible control over client portal link distribution
*   Enable portal appearance customization for brand consistency
*   Allow easy copying and sharing of portal links
*   Support automated email integration with toggle control
*   Ensure portal branding matches brand identity

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

**Role**

**View Settings**

**Edit Portal Settings**

**Toggle Auto-Include**

**Customize Appearance**

**Copy Portal Link**

Agency Owner

✅ Yes

✅ Yes

✅ Yes

✅ Yes

✅ Yes

Admin

✅ Yes

✅ Yes

✅ Yes

✅ Yes

✅ Yes

Team Member

✅ Yes (Read-Only)

❌ No

❌ No

❌ No

✅ Yes

## **3\. User Flow**

3.1 User navigates to Brand Settings > Client Portal Settings section.

3.2 System displays current portal link with "Copy Link" button.

3.3 User can toggle "Auto-include in emails" switch (default: ON).

3.4 User selects which logo to display (Primary or Secondary).

3.5 User customizes portal title and color.

3.6 System provides live preview of portal appearance.

3.7 User clicks "Save" to apply changes.

3.8 System updates portal configuration and displays success message.

## **4\. Functional Logic**

### 4.1 Portal Link Display and Copy

*   System displays complete portal URL (default Pixelly subdomain or custom domain if connected).
*   "Copy Link" button copies URL to clipboard with visual confirmation.
*   Portal link is always accessible and can be manually shared by users.

### 4.2 Auto-Include Toggle (Per Brand)

*   Toggle controls whether portal link is automatically included in automated client emails.
*   Default state: ON (portal link included in all automated emails).
*   When OFF, users can manually insert portal link via copy-paste or variable placeholder.
*   Affected emails (PM Note: Complete list needed):
    *   Contract sent
    *   Proposal sent
    *   Payment confirmation
    *   Booking confirmation
    *   Questionnaire sent
    *   (PM Note: Provide complete list of automated emails)

### 4.3 Logo Selection

*   User chooses between Primary Logo (wide) or Secondary Logo (square) for portal display.
*   Selected logo appears in client portal header.
*   Live preview updates immediately upon selection.

### 4.4 Portal Appearance Customization

*   Portal Title: Custom text displayed in portal header (default: brand name).
*   Portal Color: Inherits brand color by default; can be customized separately.
*   Customizations apply only to client-facing portal, not internal platform.

### 4.5 Live Preview

*   Preview pane shows portal appearance with selected logo, title, and color.
*   Updates in real-time as user makes changes.
*   Allows validation before saving.

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

**Field Name**

**Field Type**

**Mandatory**

**Max Length**

**Validation Rules**

**Error Message**

Portal Link

Text (Read-Only)

N/A

N/A

Display only

N/A

Auto-Include Toggle

Toggle Switch

No

N/A

Boolean (ON/OFF)

N/A

Logo Selection

Radio Button

Yes

N/A

Must select Primary or Secondary

"Please select a logo"

Portal Title

Text Input

No

100 chars

Alphanumeric, allows spaces/special chars

"Title must be 100 characters or less"

Portal Color

Color Picker

No

N/A

Valid HEX or RGB

"Invalid color format"

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

**Action**

**Success Message**

**Display Method**

**Duration**

Portal Settings Saved

"Client portal settings updated successfully"

Toast (green)

3 seconds

Portal Link Copied

"Portal link copied to clipboard"

Toast (blue)

2 seconds

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

**Error Scenario**

**Error Message**

**Trigger Condition**

**Display Method**

Save Failure

"Unable to save portal settings. Please try again."

Server error

Toast (red)

Invalid Color

"Invalid color format"

Invalid HEX/RGB

Inline error

## **8\. Edge Cases**

**Edge Case**

**System Behavior**

**Expected Outcome**

No logo uploaded

Use brand name initials as placeholder

Placeholder displays in portal

Auto-include OFF, user needs link

User can manually copy-paste link into emails

Portal link accessible via copy button

Custom domain changes

Portal link updates automatically

New domain displayed in settings

## **9\. Acceptance Criteria**

*   ✅ Portal link displays correctly (default or custom domain)
*   ✅ Copy Link button copies URL to clipboard
*   ✅ Auto-include toggle controls email link insertion (default: ON, per brand)
*   ✅ Logo selection (Primary/Secondary) updates live preview
*   ✅ Portal title and color customize client portal appearance
*   ✅ Live preview reflects all customizations in real-time
*   ✅ Changes save successfully and propagate to client portal

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

[5\_Client\_Portal\_Settings\_Section\_Test\_Cases.xlsx](https://docs.google.com/spreadsheets/d/1BW5MQyaVEPmX46nZZgyHTwc_s3N9uEOk/edit?usp=drive_link&ouid=105170312247554220827&rtpof=true&sd=true)

## **11\. Dependencies**

**Dependency Type**

**Module**

**Description**

**Impact if Unavailable**

Internal Module

Brand Domain

Portal link uses brand domain (default or custom)

Portal link may show incorrect URL

Internal Module

Email System

Auto-include toggle affects automated emails

Links not included in emails

## **12\. References**

### 12.1 Figma Designs: [Figma](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=28804-58304&t=ER8XqMIaN9iUXWJy-0)

### 12.2 PM Notes:

### Confirm complete list of automated emails where auto-include toggle applies

### Confirm if portal title defaults to brand name or allows custom default

### 

6\. Events & Service Section

# **FRD #5: Events & Service Section**

## **1\. Module Overview**

### 1.1 Module Name

Events & Service Section

### 1.2 Purpose

The Events & Service Section allows agency owners and admins to manage event types and service types for brands. Users can add default or custom event types, select service types (Photo, Video, Content), and discontinue services. The module includes sophisticated dependency checking to prevent data inconsistencies when removing or discontinuing events/services that are actively used in Packages, Proposals, Automations, Lead Forms, Contracts, Questionnaires, and Contractor assignments.

### 1.3 Business Goals

*   Enable flexible event and service management for brand customization
*   Support addition of unlimited custom event types
*   Allow service type selection (Photo, Video, Content - maximum 3)
*   Prevent data corruption through comprehensive dependency validation
*   Provide clear warnings about impact of removing events/services
*   Maintain historical data integrity in reports
*   Support discontinuation of services without deleting historical records

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

**Role**

**View Events/Services**

**Add Events/Services**

**Edit Events/Services**

**Discontinue Services**

**View Impact Warnings**

Agency Owner

✅ Yes

✅ Yes

✅ Yes

✅ Yes

✅ Yes

Admin

✅ Yes

✅ Yes

✅ Yes

✅ Yes (with restrictions)

✅ Yes

Team Member

✅ Yes (Read-Only)

❌ No

❌ No

❌ No

❌ No

## **3\. User Flow**

### Events Management

3.1 User navigates to Brand Settings > Events & Service section.

3.2 System displays currently selected event types (default and custom).

3.3 User clicks "Add Event" to add custom event type.

3.4 User enters event name and clicks "Add."

3.5 System validates uniqueness and adds event to brand.

3.6 User can remove event by clicking "Remove" icon.

3.7 System checks dependencies (Lead Forms, Packages, Automations, Projects).

3.8 If dependencies exist, system displays warning modal with impact list.

3.9 User reviews impact and confirms or cancels removal.

3.10 If confirmed, event is removed from future use; existing data preserved.

### Services Management

3.11 User views selected service types (Photo, Video, Content).

3.12 User can add service types (minimum 1, maximum 3).

3.13 User clicks "Discontinue" for a service type.

3.14 System checks dependencies: Packages, Proposals, Automations, Lead Forms, Contracts, Questionnaires, Active Projects, Contractors.

3.15 If active dependencies exist, system blocks removal and displays error with affected modules.

3.16 User must manually remove service from all dependencies before system allows discontinuation.

3.17 Once dependencies cleared, service can be discontinued.

3.18 Discontinued service hidden from future project creation but retained in reports and historical data.

## **4\. Functional Logic**

### 4.1 Event Types Management

*   Users can select from default event types (PM Note: Complete list needed - visible: Wedding, Corporate Event, Birthday).
*   Users can add unlimited custom event types (e.g., "Engagement Shoot," "Product Launch").
*   Event names must be unique within the brand (case-insensitive).
*   Events propagate to: Project creation dropdowns, Lead Forms, Contractor assignments.

### 4.2 Service Types Management

*   Three fixed service types available: Photo, Video, Content.
*   Users must select at least 1 service, can select up to all 3.
*   Services cannot be added beyond the system (no custom services - use A La Carte for additional offerings).
*   Selected services propagate to: Projects, Packages, Proposals, Contracts, Questionnaires, Contractor assignments.

### 4.3 Event/Service Addition

*   Adding events/services immediately makes them available in all dependent modules.
*   New events/services affect both existing (in-progress) and future projects.
*   No warnings needed for addition (safe operation).

### 4.4 Event Removal - Dependency Checks

Dependencies checked before allowing event removal:

*   Lead Forms using the event
*   Packages filtered/targeted to the event
*   Automation rules triggered by the event
*   Projects (in-progress or upcoming) tagged with the event

If dependencies exist:

*   Warning modal displays: "This event is used in: \[List of modules\]. Removing it will affect \[X\] lead forms, \[Y\] packages, \[Z\] automations. Are you sure?"
*   User can click links to view affected items in each module.
*   User must manually update dependencies or confirm removal understanding impact.

### 4.5 Service Discontinuation - Strict Dependency Checks

Dependencies checked (blocking removal if active):

*   **Packages** with the service
*   **Active Proposals** including the service
*   **Automations** configured for the service
*   **Lead Forms** with the service as option
*   **Contracts** with service agreements
*   **Questionnaires** mapped to the service
*   **Active Projects** (not completed) using the service
*   **Contractors** assigned to projects with the service

If ANY active dependency exists:

*   System displays error modal: "Cannot discontinue service. This service is actively used in: \[List\]. Please remove the service from these modules first."
*   User redirected to affected module when clicking module name in error list.
*   Service removal blocked until all dependencies manually cleared.

Once all dependencies cleared:

*   Service can be discontinued.
*   Service hidden from: Future project creation, Contractor invitations, New packages, New proposals, New lead forms.
*   Service retained in: Historical reports, Completed projects, Existing contracts (read-only display).

### 4.6 AI-Powered Impact Warnings

*   System uses AI/logic to generate comprehensive impact warnings showing all affected areas.
*   Warning includes: Module names, Count of affected items, Links to view items.
*   (Developer Note: Implement AI-powered warning generation showing complete impact list)

### 4.7 Historical Data Preservation

*   Discontinued services remain visible in Reports with "Discontinued" label.
*   Revenue and performance data for discontinued services retained for accurate tracking.
*   Completed projects continue to display discontinued services (read-only).
*   Service can be re-added in the future (requires manual recreation of packages/proposals).

### 4.8 Re-adding Discontinued Services

*   If user re-adds a previously discontinued service, it becomes active again for future use.
*   Historical data is preserved and linked.
*   Packages, proposals, and forms must be manually recreated (not auto-restored).

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

**Field Name**

**Field Type**

**Mandatory**

**Validation Rules**

**Error Message**

Event Name

Text Input

Yes

1-50 chars, unique within brand (case-insensitive)

"Event name is required" / "This event already exists"

Service Type

Checkbox (Multi-Select)

Yes

Min 1, Max 3 selections

"Select at least 1 service" / "Maximum 3 services allowed"

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

**Action**

**Success Message**

**Display Method**

**Duration**

Event Added

"Event '\[Event Name\]' added successfully"

Toast (green)

3 seconds

Event Removed

"Event '\[Event Name\]' removed successfully"

Toast (green)

3 seconds

Service Discontinued

"Service '\[Service Name\]' discontinued successfully"

Toast (green)

3 seconds

Service Re-Added

"Service '\[Service Name\]' activated successfully"

Toast (green)

3 seconds

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

**Error Scenario**

**Error Message**

**Trigger Condition**

**Display Method**

Duplicate Event

"This event already exists"

User enters event name matching existing (case-insensitive)

Inline error

Blank Event Name

"Event name is required"

User submits empty event name

Inline error

Service Removal Blocked

"Cannot discontinue service. This service is actively used in: \[Packages, Proposals, Automations, Lead Forms, Contracts, Questionnaires\]. Please remove the service from these modules first."

Active dependencies exist

Modal with module links

No Services Selected

"Select at least 1 service"

User deselects all services

Inline error

Too Many Services

"Maximum 3 services allowed"

User attempts to select 4th service

Inline error

## **8\. Edge Cases**

**Edge Case**

**System Behavior**

**Expected Outcome**

Service discontinued, then re-added after 6 months

Service reactivated; historical data preserved and linked

Service available for future use; past data intact

Event removed, 50 lead forms affected

Warning modal shows "50 lead forms affected" with link

User can review and update lead forms before confirming

All 3 services selected, user tries to discontinue all

System prevents deselecting last service

At least 1 service must remain active

Service discontinued, appears in old completed project

Completed project shows service with "Discontinued" label (read-only)

Historical accuracy maintained

Service removed from packages, but active proposal still has it

System blocks discontinuation until proposal is updated

Prevents inconsistency

## **9\. Acceptance Criteria**

*   ✅ Users can add unlimited custom event types
*   ✅ Event names validated for uniqueness within brand
*   ✅ Users can select 1-3 service types (Photo, Video, Content)
*   ✅ Adding events/services propagates to all dependent modules
*   ✅ Event removal displays warning modal with dependency impact list
*   ✅ Service discontinuation blocked if active dependencies exist
*   ✅ Error modal shows complete list of blocking dependencies with links
*   ✅ Discontinued services hidden from future use but retained in reports/history
*   ✅ Re-adding discontinued services requires manual package/proposal recreation
*   ✅ Reports display discontinued services with "Discontinued" label

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

[6\_Events\_Service\_Section\_Test\_Cases.xlsx](https://docs.google.com/spreadsheets/d/1dBjPvvuw75v6UKoR1okUl-vLyXnEGhei/edit?usp=drive_link&ouid=105170312247554220827&rtpof=true&sd=true)

## **11\. Dependencies**

**Dependency Type**

**Module**

**Description**

**Impact if Unavailable**

Internal Module

Packages

Dependency check for service removal

Cannot validate if service removal is safe

Internal Module

Proposals

Dependency check for service removal

Cannot validate if service removal is safe

Internal Module

Lead Forms

Event/service usage validation

Cannot check lead form dependencies

Internal Module

Automations

Event/service automation validation

Cannot check automation dependencies

Internal Module

Contracts

Service agreement validation

Cannot check contract dependencies

Internal Module

Questionnaires

Service-specific questionnaire check

Cannot validate questionnaire usage

Internal Module

Projects

Active project service validation

Cannot check project dependencies

Internal Module

Contractors

Service assignment validation

Cannot check contractor dependencies

Internal Module

Reports

Historical data display

Discontinued services won't display in reports

## **12\. References**

### 12.1 Figma Designs: [Figma](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=15803-142557&t=ER8XqMIaN9iUXWJy-0)

### 12.2 PM Notes:

### Confirm complete default event types list

### Confirm AI-powered warning implementation approach

### Verify dependency check logic with development team

### 

7\. Service Area Section

# **FRD #5: Service Area Section**

## **1\. Module Overview**

### 1.1 Module Name

Service Area Section

### 1.2 Purpose

The Service Area Section allows agency owners and admins to manage geographic service areas for brands. Users can add, edit, and remove service areas using free-form text input. Service areas are used throughout the platform in project creation, lead forms, packages, proposals, calendars, automations, contractor management, reports, and filters. The module ensures data consistency by validating duplicates and preventing blank entries.

### 1.3 Business Goals

*   Enable flexible geographic targeting for brand operations
*   Support unlimited service area additions
*   Propagate service areas to all dependent modules for consistent filtering
*   Allow removal of service areas with impact awareness
*   Maintain data integrity through validation rules

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

**Role**

**View Service Areas**

**Add Service Areas**

**Remove Service Areas**

Agency Owner

✅ Yes

✅ Yes

✅ Yes

Admin

✅ Yes

✅ Yes

✅ Yes

Team Member

✅ Yes (Read-Only)

❌ No

❌ No

## **3\. User Flow**

3.1 User navigates to Brand Settings > Service Area section.

3.2 System displays currently added service areas as tags/chips.

3.3 User types service area name in input field (e.g., "New York, NY").

3.4 User presses Enter or clicks "Add" button.

3.5 System validates: not blank, not duplicate (case-insensitive).

3.6 If valid, system adds service area as tag/chip below input.

3.7 User can remove service area by clicking "X" icon on tag.

3.8 System checks impact on future projects and lead forms.

3.9 User confirms removal.

3.10 Service area removed; hidden from future dropdowns; existing projects retain original data.

## **4\. Functional Logic**

### 4.1 Service Area Addition

*   Input is free-form text (no predefined dropdowns).
*   Users can add unlimited service areas.
*   Each service area displayed as tag/chip with "X" remove icon.
*   Format validation: Not blank, not duplicate (case-insensitive comparison).
*   Service areas displayed exactly as entered (no auto-formatting).

### 4.2 Service Area Propagation

Service areas propagate to:

*   **Project & Event Management**: Service area dropdown in project creation
*   **Lead Forms**: Service area selection for targeting
*   **Packages**: Service area filtering/targeting
*   **Proposals**: Service area display
*   **Calendars & Availability**: Service area filtering
*   **Automations**: Service area-based automation rules
*   **Contractor Management**: Invite, Setup, Assign Contractor (service area matching)
*   **Reports**: Service area filters
*   **Brand Settings**: Service area display and management

### 4.3 Service Area Removal Impact

*   Removal affects **only future projects and lead forms**.
*   **Existing (in-progress or completed) projects** retain original service area data.
*   Lead forms using the service area must be manually updated (system does not auto-remove).
*   Service area disappears from dropdowns in project creation and contractor assignment.

### 4.4 Validation Rules

*   **Not blank**: Service area cannot be empty string.
*   **Not duplicate**: Case-insensitive check against existing service areas for the brand.
*   **At least 1 required**: Brand must have at least one service area at all times.

### 4.5 Display Format

*   Service areas display exactly as entered (e.g., "New York, NY" stays "New York, NY", "new york" stays "new york").
*   No auto-capitalization or formatting applied by system.

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

**Field Name**

**Field Type**

**Mandatory**

**Max Length**

**Validation Rules**

**Error Message**

Service Area Name

Free-Form Text Input (Tags)

Yes

100 chars per area

Not blank, not duplicate (case-insensitive), at least 1 service area required

"Service area cannot be empty" / "This service area has already been added" / "At least one service area is required"

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

**Action**

**Success Message**

**Display Method**

**Duration**

Service Area Added

"Service area '\[Area Name\]' added successfully"

Toast (green) or inline confirmation

2 seconds

Service Area Removed

"Service area '\[Area Name\]' removed successfully"

Toast (green)

2 seconds

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

**Error Scenario**

**Error Message**

**Trigger Condition**

**Display Method**

Blank Service Area

"Service area cannot be empty"

User clicks Add without entering text

Inline error

Duplicate Service Area

"This service area has already been added"

User enters existing area (case-insensitive)

Inline error

Remove Last Service Area

"At least one service area is required"

User attempts to remove final service area

Inline error or disabled Remove button

## **8\. Edge Cases**

**Edge Case**

**System Behavior**

**Expected Outcome**

User adds 20 service areas

All 20 saved and displayed as tags

No limit enforced

User types "New York" then "new york"

Second entry rejected as duplicate

Error: "This service area has already been added"

Service area removed, lead form still uses it

Lead form retains old service area (must be manually updated)

Manual intervention required

Existing project has removed service area

Project data unchanged; service area displays (read-only historical data)

Historical accuracy preserved

## **9\. Acceptance Criteria**

*   ✅ Users can add unlimited service areas via free-form text input
*   ✅ Service areas display exactly as entered (no auto-formatting)
*   ✅ Duplicate service areas rejected (case-insensitive)
*   ✅ Blank service areas rejected
*   ✅ At least 1 service area must exist at all times
*   ✅ Service areas propagate to all 9+ dependent modules
*   ✅ Removal affects only future projects/forms; existing data preserved
*   ✅ Removed service areas hidden from dropdowns

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

[7\_Service\_Area\_Section\_Test\_Cases.xlsx](https://docs.google.com/spreadsheets/d/1yzwtsmXXFBs4MyC2sjdYFiWEIynsnnrf/edit?usp=drive_link&ouid=105170312247554220827&rtpof=true&sd=true)

## **11\. Dependencies**

**Dependency Type**

**Module**

**Description**

**Impact if Unavailable**

Internal Module

Project & Event Management

Service area used in project creation

Projects cannot filter by service area

Internal Module

Lead Forms

Service area targeting

Lead forms cannot target specific areas

Internal Module

Packages

Service area filtering

Packages cannot be area-specific

Internal Module

Proposals

Service area display

Proposals won't show service area

Internal Module

Calendars & Availability

Service area filtering

Cannot filter calendar by area

Internal Module

Automations

Service area-based rules

Automations cannot trigger by area

Internal Module

Contractor Management

Service area matching

Contractors cannot be assigned by area

Internal Module

Reports

Service area filters

Reports cannot filter by area

## **12\. References**

### 12.1 Figma Designs: [7\_Service\_Area\_Section\_Test\_Cases.xlsx](https://docs.google.com/spreadsheets/d/1yzwtsmXXFBs4MyC2sjdYFiWEIynsnnrf/edit?usp=drive_link&ouid=105170312247554220827&rtpof=true&sd=true)

###