QA Docs

QA Docs

None Google Auth QA Docs Qejaverse Feature Guide Qejaverse UAT Docs Sales & Business Development testing-docs
Edit
Open in ChatGPT
Ask ChatGPT about this page
Open in Claude
Ask Claude about this page

User Journey Docs: Property Manager/Owner Role

Purpose: This document describes the complete user journey for the Property Manager/Owner role in the CasaHub (MiCasa) application. It serves as a reference for QA testers and anyone who needs to understand how this role flows through the application.

Companion Document: QA test Plan

Table of Contents

  1. Authentication
  2. Onboarding Flow
  3. Manager Dashboard
  4. Project Management
  5. Unit Management
  6. Building & Phase Management
  7. Team Management
  8. Applications & Contracts
  9. Agent Directory
  10. Billing & Subscriptions
  11. Permission Boundaries

1. Authentication

1.1 Registration (New Account)

User Story:
As a new Property Manager, I want to create an account so that I can access the platform and manage my properties.

User Journey:

  1. User navigates to casahub.jh.frappe.cloud/micasa

  2. User clicks "Create Account" or "Sign Up" button

  3. User chooses registration method:

    • Manual Registration:
      • User enters first name, last name, email, and password
      • User clicks "Create Account" button
      • Account is created in the system
    • Single Sign-On (Google):
      • User clicks "Sign in with Google" button
      • User is redirected to Google OAuth flow
      • User selects/confirms Google account
      • Account is created and linked to Google identity

  4. After successful registration, user is automatically logged in

  5. User is redirected to /onboarding-check

Expected Behavior:

  • Registration form validates all required fields before submission

  • Password must meet minimum requirements (8+ characters)

  • Email must be unique in the system

  • User receives a welcome email after account creation

  • Upon successful registration, user has only the base "MiCasa User" role

  • User cannot access any dashboard or protected routes until onboarding is complete

Success Criteria:

  • Account created successfully in database

  • User session is established (logged in)

  • User is redirected to onboarding flow

  • User has only "MiCasa User" role at this point

1.2 Login (Existing Account)

User Story:
As a returning Property Manager, I want to log in to my account so that I can access my dashboard and manage my properties.

User Journey:

  1. User navigates to /micasa/login

  2. User chooses login method:

    • Email/Password:
      • User enters registered email address
      • User enters password
      • User clicks "Sign In" button
    • Google SSO:
      • User clicks "Sign in with Google" button
      • User completes Google OAuth flow

  3. System validates credentials

  4. Upon successful login:

    • If onboarding incomplete → redirect to /onboarding-check
    • If onboarding complete → redirect to role-specific dashboard (/manager/dashboard or /owner/dashboard)

Expected Behavior:

  • Invalid credentials show clear error message

  • "Forgot Password" link is available for password recovery

  • Session persists across browser tabs

  • User's active role determines which dashboard they land on

Success Criteria:

  • User is authenticated and session is established

  • User is redirected to appropriate destination based on onboarding status

  • Dashboard loads with user's data

1.3 Logout

User Story:
As a logged-in user, I want to log out so that my session is securely ended.

User Journey:

  1. User clicks on their profile/avatar in the sidebar

  2. User clicks "Logout" option

  3. System clears session and authentication tokens

  4. User is redirected to login page

Expected Behavior:

  • All protected routes become inaccessible after logout

  • Attempting to access /manager/dashboard directly redirects to login

  • Session storage is cleared

Success Criteria:

  • User session is terminated

  • User cannot access protected routes

  • User is redirected to login page

2. Onboarding Flow

2.1 Onboarding Check

User Story:
As a new user, I want the system to guide me through required setup steps so that my account is properly configured.

User Journey:

  1. User arrives at /onboarding-check (automatically after registration/login)

  2. System checks user's onboarding status:

    • profile_completed: Has user filled in required profile fields?
    • primary_role_selected: Has user chosen their primary role?

  3. System redirects based on status:

    • If profile not completed → /onboarding/profile
    • If profile completed but role not selected → /onboarding/role
    • If both completed → role-specific dashboard

Expected Behavior:

  • Loading spinner shows while checking status

  • User cannot bypass onboarding gates

  • Onboarding status is checked on every login until complete

Success Criteria:

  • User is routed to the correct onboarding step

  • Completed steps are not repeated

2.2 Profile Gate (Profile Completion)

User Story:
As a new user, I want to complete my profile with essential information so that I can proceed to use the platform.

User Journey:

  1. User arrives at /onboarding/profile

  2. User sees profile completion form with fields:

    • Phone number (required) - with country code selector (default: +254 Kenya)
    • Gender (required) - dropdown selection
    • Date of Birth (required) - date picker

  3. User fills in all required fields

  4. User clicks "Continue" or "Save & Continue" button

  5. System validates and saves profile data

  6. User is redirected to /onboarding/role

Expected Behavior:

  • Phone number validates format based on country code

  • All fields are required before proceeding

  • User cannot skip this step

  • "Logout" option is available if user wants to exit

Success Criteria:

  • Profile data is saved to user's CasaHub Profile

  • profile_completed flag is set to true

  • User is redirected to role selection

2.3 Role Selection Gate

User Story:
As a new user, I want to select my primary role so that the platform shows me relevant features and dashboards.

User Journey:

  1. User arrives at /onboarding/role

  2. User sees role selection cards:

    • Property Owner - "I own real estate properties and want to monitor my investments"
    • Property Manager - "I manage properties and operations on behalf of owners"
    • Real Estate Agent - "I help clients find and transact properties"
    • Client/Tenant - "I am looking to buy, rent, or view properties"

  3. User clicks on their desired role card (e.g., "Property Manager")

  4. Selected card shows visual confirmation (checkmark, highlight)

  5. User clicks "Continue" button

  6. System assigns the corresponding role to user

  7. User is redirected to role-specific dashboard

Expected Behavior:

  • Only one role can be selected at a time

  • Selected role is visually highlighted

  • User must select a role before proceeding

  • Role assignment happens server-side for security

Success Criteria:

  • User is assigned the correct Frappe role:

    • "Property Owner" → "MiCasa Owner" role
    • "Property Manager" → "MiCasa Manager" role

  • primary_role_selected flag is set to true

  • User is redirected to /manager/dashboard or /owner/dashboard

  • User can now access role-specific features

3. Manager Dashboard

3.1 Dashboard Overview

User Story:
As a Property Manager, I want to see a comprehensive overview of my managed properties so that I can quickly assess the status of my portfolio.

User Journey:

  1. User navigates to /manager/dashboard (or lands here after login)

  2. Dashboard loads with the following sections:

    • Header: Welcome message with user's name
    • KPI Cards Row: 4 key metrics displayed as clickable cards
    • Financial Health Section: Revenue and collection metrics
    • Project Breakdown: Status of managed projects
    • Recent Activity: Latest access requests and updates

Expected Behavior:

  • All sections load with data or appropriate empty states
  • Loading spinners show while data is being fetched
  • KPI cards are clickable and navigate to relevant pages
  • Period filter (This Month, This Quarter, etc.) updates financial metrics

Success Criteria:

  • Dashboard loads within 3 seconds
  • All KPI values are accurate and reflect current data
  • No console errors or stuck loading states

3.2 KPI Cards

User Story:
As a Property Manager, I want to see key metrics at a glance so that I can quickly understand my portfolio status.

User Journey:

  1. User views the 4 KPI cards on the dashboard:

    • Managed Projects: Total number of projects user manages

    • Pending Requests: Number of agent access requests awaiting approval

    • Total Units: Total units across all projects (with available count)

    • Active Agents: Number of agents with project access

  2. User clicks on a KPI card to navigate to the relevant page:

    • "Pending Requests" → /manager/applications?tab=requests

    • "Active Agents" → /manager/agents

Expected Behavior:

  • Cards display accurate counts

  • Clickable cards have hover effects

  • Clicking navigates to the correct page

Success Criteria:

  • All counts match actual data in the system

  • Navigation works correctly from each clickable card

3.3 Financial Metrics

User Story:
As a Property Manager, I want to see financial performance metrics so that I can track revenue and collections.

User Journey:

  1. User views the Financial Health section showing:

    • Total Collected: Sum of all payments received

    • Pending Payments: Outstanding amounts due

    • Overdue Payments: Payments past their due date

    • Collection Rate: Percentage of expected payments collected

  2. User can change the period filter (This Month, This Quarter, This Year)

  3. Metrics update to reflect the selected period

Expected Behavior:

  • Currency is displayed in KES (Kenyan Shillings)

  • Period filter triggers data refresh

  • Loading indicator shows during data fetch

Success Criteria:

  • Financial figures are accurate for the selected period

  • Period changes update all relevant metrics

4. Project Management

4.1 View Projects List

User Story:
As a Property Manager, I want to see all projects I manage so that I can access and manage them.

User Journey:

  1. User clicks "Projects" in the sidebar navigation

  2. User is navigated to /projects or /projects/my-projects

  3. Projects list displays as cards showing:

    • Project name
    • Location
    • Status (Active, Draft, Completed, etc.)
    • Unit count
    • Cover image (if available)

  4. User can search projects by name

  5. User can filter projects by status or category

Expected Behavior:

  • Projects load with pagination if more than 20

  • Empty state shows if no projects exist

  • Search filters results in real-time

Success Criteria:

  • All user's managed projects are displayed

  • Search and filter work correctly

  • Clicking a project card opens project details

4.2 Create New Project

User Story:
As a Property Manager, I want to create a new project so that I can start managing a new property development.

User Journey:

  1. User clicks "Create Project" button on projects page

  2. User is taken to the Project Setup Wizard

  3. User completes the wizard steps:

    • Step 1 - Basics: Project name, company, template, category, development type, description

    • Step 2 - Location: Address, county, coordinates (optional)

    • Step 3 - Media: Cover image, gallery images, videos

    • Step 4 - Structure: Phases, buildings configuration

    • Step 5 - Units: Bulk unit creation or skip for later

    • Step 6 - Team: Add team members (optional)

    • Step 7 - Review: Review all information before creation

  4. User clicks "Create Project" on the final step

  5. Project is created and user is redirected to project detail page

Expected Behavior:

  • Wizard shows clear progress indicator

  • User can navigate back to previous steps

  • Required fields are validated before proceeding

  • Image uploads show progress and preview

  • User is automatically added as a team member with "Manager" role

Success Criteria:

  • Project is created in the database

  • User has management access to the project

  • Toast notification confirms success

  • User is redirected to the new project's detail page

4.3 View Project Details

User Story:
As a Property Manager, I want to view detailed information about a project so that I can understand its current status.

User Journey:

  1. User clicks on a project card from the projects list

  2. User is navigated to /projects/{project-id}

  3. Project detail page displays:

    • Cover image/hero section

    • Project name and description

    • Location information

    • Unit statistics (total, available, sold, reserved)

    • "Manage" button for accessing management features

  4. User can see project status and completion percentage

Expected Behavior:

  • All project information loads correctly

  • Images display properly

  • Statistics are accurate and up-to-date

Success Criteria:

  • Project details match what was entered during creation

  • Unit statistics are accurate

  • "Manage" button is visible and functional

4.4 Access Project Management

User Story:
As a Property Manager, I want to access the management interface so that I can manage units, buildings, phases, and team.

User Journey:

  1. User clicks "Manage" button on project detail page

  2. User is navigated to /projects/{project-id}/manage

  3. Management interface displays with tabbed navigation:

    • Units: List and manage all units

    • Buildings: List and manage buildings

    • Phases: List and manage project phases

    • Team: View and manage team members

    • Templates: Manage unit templates

    • Payment Plans: Configure payment plans

    • Settings: Project settings and configuration

  4. User clicks on tabs to switch between sections

Expected Behavior:

  • All tabs load their respective content

  • Active tab is visually highlighted

  • Tab content is scrollable if needed

Success Criteria:

  • All management tabs are accessible

  • Each tab displays correct content

  • No console errors when switching tabs

4.5 Edit Project Settings

User Story:
As a Property Manager, I want to edit project settings so that I can update project information.

User Journey:

  1. User navigates to project management → Settings tab

  2. User toggles "Edit Mode" on

  3. User modifies project fields (name, description, status, etc.)

  4. User clicks "Save" button

  5. Changes are saved and confirmed with toast notification

Expected Behavior:

  • Edit mode clearly indicates editable state

  • Changes are validated before saving

  • Save button is disabled while saving

  • Success/error feedback is provided

Success Criteria:

  • Changes are persisted to the database

  • Updated values appear when viewing project details

  • Toast confirms successful save

5. Unit Management

5.1 View Units List

User Story:
As a Property Manager, I want to see all units in a project so that I can manage their status and details.

User Journey:

  1. User navigates to project management → Units tab

  2. Units list/table displays showing:

    • Unit number/name
    • Unit type (Apartment, Villa, Plot, etc.)
    • Status (Available, Reserved, Sold, etc.)
    • Price
    • Building/Phase assignment

  3. User can search units by number or name

  4. User can filter units by status, type, or building

Expected Behavior:

  • Table is sortable by columns

  • Search filters results in real-time

  • Pagination works for large unit counts

  • Empty state shows if no units exist

Success Criteria:

  • All project units are displayed

  • Search and filters work correctly

  • Unit count matches project statistics

5.2 Create Single Unit

User Story:
As a Property Manager, I want to create a new unit so that I can add it to my project inventory.

User Journey:

  1. User clicks "Add Unit" button in units management

  2. Modal or form appears with fields:

    • Unit number/name (required)
    • Unit type (required)
    • Price (required)
    • Building assignment (required)
    • Phase assignment (optional)
    • Floor number (optional)
    • Bedrooms, bathrooms, size (optional)

  3. User fills in required fields

  4. User clicks "Save" or "Create" button

  5. Unit is created and appears in the units list

Expected Behavior:

  • Form validates required fields

  • Building dropdown shows available buildings

  • Price field accepts numeric input

  • Success toast confirms creation

Success Criteria:

  • Unit is created in the database

  • Unit appears in the units list

  • Unit status defaults to "Available"

  • Subscription usage count is incremented

5.3 Bulk Create Units

User Story:
As a Property Manager, I want to create multiple units at once so that I can quickly populate a building with units.

User Journey:

  1. User clicks "Bulk Create" button in units management

  2. Bulk creation modal appears with fields:

    • Select building (required)
    • Number of units to create (required)
    • Naming pattern (e.g., "Unit-", "Apt-")
    • Starting number
    • Unit type
    • Default price

  3. User configures the bulk creation settings

  4. User clicks "Generate" or "Create" button

  5. System creates units with sequential naming

  6. Progress indicator shows creation status

  7. Units appear in the list after completion

Expected Behavior:

  • Subscription limit is checked before creation

  • If limit would be exceeded, error message shows with upgrade prompt

  • Progress indicator shows for large batches

  • All units are created with consistent naming

Success Criteria:

  • Requested number of units are created

  • Units have sequential names (e.g., Unit-001, Unit-002)

  • Subscription usage is updated

  • Toast confirms successful creation

5.4 Edit Unit Details

User Story:
As a Property Manager, I want to edit unit details so that I can update pricing or status.

User Journey:

  1. User clicks on a unit row in the units list

  2. Unit detail view or edit modal opens

  3. User clicks "Edit" button

  4. User modifies unit fields (price, status, details)

  5. User clicks "Save" button

  6. Changes are saved and confirmed

Expected Behavior:

  • All editable fields are accessible
  • Status changes are reflected immediately
  • Price changes are validated

Success Criteria:

  • Changes are persisted to the database
  • Updated values appear in the units list
  • Toast confirms successful save

5.5 Filter and Search Units

User Story:
As a Property Manager, I want to filter and search units so that I can quickly find specific units.

User Journey:

  1. User locates the search input in units management

  2. User types a partial unit number or name

  3. Results filter in real-time as user types

  4. User can also use filter dropdowns:

    • Status filter (Available, Reserved, Sold, etc.)
    • Type filter (Apartment, Villa, etc.)
    • Building filter

  5. Filters can be combined for precise results

Expected Behavior:

  • Search is case-insensitive

  • Filters update results immediately

  • Clear button resets all filters

  • Result count updates with filters

Success Criteria:

  • Search returns matching units

  • Filters correctly narrow results

  • Combined filters work together

6. Building & Phase Management

6.1 View Buildings List

User Story:
As a Property Manager, I want to see all buildings in a project so that I can manage the project structure.

User Journey:

  1. User navigates to project management → Buildings tab

  2. Buildings list displays as cards showing:

    • Building name
    • Number of floors (if set)
    • Unit count
    • Occupancy rate

  3. User can add new buildings or edit existing ones

Expected Behavior:

  • Buildings display with accurate unit counts

  • Empty state shows if no buildings exist

  • Add button is visible and functional

Success Criteria:

  • All project buildings are displayed

  • Unit counts are accurate

  • Building cards are clickable for details

6.2 Create New Building

User Story:
As a Property Manager, I want to create a new building so that I can organize units within the project.

User Journey:

  1. User clicks "Add Building" button

  2. Modal or form appears with fields:

    • Building name (required)
    • Number of floors (optional)
    • Description (optional)

  3. User fills in the building name

  4. User clicks "Save" button

  5. Building is created and appears in the list

Expected Behavior:

  • Form validates required fields

  • Subscription limit is checked (if applicable)

  • Success toast confirms creation

Success Criteria:

  • Building is created in the database

  • Building appears in the buildings list

  • Building is available for unit assignment

6.3 View Phases List

User Story:
As a Property Manager, I want to see all phases in a project so that I can track development progress.

User Journey:

  1. User navigates to project management → Phases tab

  2. Phases list displays showing:

    • Phase name
    • Start and end dates (if set)
    • Unit count
    • Completion status

  3. User can add new phases or edit existing ones

Expected Behavior:

  • Phases display in chronological order

  • Dates are formatted clearly

  • Empty state shows if no phases exist

Success Criteria:

  • All project phases are displayed

  • Phase information is accurate

  • Add button is functional

6.4 Create New Phase

User Story:
As a Property Manager, I want to create a new phase so that I can organize the project timeline.

User Journey:

  1. User clicks "Add Phase" button

  2. Modal or form appears with fields:

    • Phase name (required)
    • Start date (optional)
    • End date (optional)
    • Description (optional)

  3. User fills in the phase name

  4. User optionally sets dates

  5. User clicks "Save" button

  6. Phase is created and appears in the list

Expected Behavior:

  • Date picker allows easy date selection

  • End date must be after start date (if both set)

  • Success toast confirms creation

Success Criteria:

  • Phase is created in the database

  • Phase appears in the phases list

  • Phase is available for unit/building assignment

7. Team Management

7.1 View Team Members

User Story:
As a Property Manager, I want to see all team members on a project so that I can manage project access.

User Journey:

  1. User navigates to project management → Team tab

  2. Team members list displays showing:

    • Member name and profile photo
    • Email address
    • Role on project (Manager, Sales Manager, Agent, etc.)
    • Join date

  3. User can see their own entry in the list

  4. User can switch between "Active Members" and "Pending Invitations" views

Expected Behavior:

  • Current user is visible in the team list

  • Roles are clearly displayed

  • Empty state shows if only the current user is on the team

Success Criteria:

  • All team members are displayed

  • Role information is accurate

  • Pending invitations are shown separately

7.2 Invite Team Member

User Story:
As a Property Manager, I want to invite new team members so that they can help manage the project.

User Journey:

  1. User clicks "Invite Member" button

  2. Invitation modal appears with fields:

    • Email address (required)
    • Role selection (Manager, Sales Manager, Agent)
    • Optional personal message

  3. User enters the invitee's email

  4. User selects the role to assign

  5. User clicks "Send Invitation" button

  6. Invitation is sent via email

  7. Pending invitation appears in the invitations list

Expected Behavior:

  • Email is validated for correct format

  • Role options are clearly described

  • Success toast confirms invitation sent

  • Invitation appears in "Pending Invitations" tab

Success Criteria:

  • Invitation record is created in the database

  • Email is sent to the invitee

  • Invitation shows in pending list with status

  • Invitee can accept and join the project

7.3 Remove Team Member

User Story:
As a Property Manager, I want to remove team members so that I can revoke their project access.

User Journey:

  1. User locates the team member to remove in the list

  2. User clicks "Remove" button or menu option

  3. Confirmation dialog appears

  4. User confirms the removal

  5. Team member is removed from the project

Expected Behavior:

  • Confirmation is required before removal

  • User cannot remove themselves

  • Success toast confirms removal

  • Removed member loses project access immediately

Success Criteria:

  • Team member is removed from the project

  • Member no longer appears in team list

  • Member can no longer access the project

8. Applications & Contracts

8.1 View Access Requests

User Story:
As a Property Manager, I want to see agent access requests so that I can approve or reject them.

User Journey:

  1. User clicks "Applications" in the sidebar navigation

  2. User is navigated to /manager/applications

  3. "Requests" tab is active by default

  4. Access requests list displays showing:

    • Agent name and profile photo
    • Project they're requesting access to
    • Request date
    • Status (Pending, Approved, Rejected)

  5. User can filter by status or project

Expected Behavior:

  • Pending requests are highlighted or shown first

  • Request details are clearly visible

  • Action buttons are accessible for pending requests

Success Criteria:

  • All access requests are displayed

  • Filtering works correctly

  • Pending count matches dashboard KPI

8.2 Approve Access Request

User Story:
As a Property Manager, I want to approve agent access requests so that agents can start working on my projects.

User Journey:

  1. User locates a pending access request

  2. User clicks "Approve" button

  3. Optional: User adds approval notes

  4. User confirms the approval

  5. Request status changes to "Approved"

  6. Agent receives notification of approval

Expected Behavior:

  • Approval is processed immediately

  • Status updates in the list

  • Success toast confirms approval

  • Agent gains project access

Success Criteria:

  • Request status is updated to "Approved"

  • Agent can now access the project

  • Agent receives email/in-app notification

8.3 Reject Access Request

User Story:
As a Property Manager, I want to reject access requests so that I can decline agents who don't meet my criteria.

User Journey:

  1. User locates a pending access request

  2. User clicks "Reject" button

  3. User enters rejection reason (required)

  4. User confirms the rejection

  5. Request status changes to "Rejected"

  6. Agent receives notification with reason

Expected Behavior:

  • Rejection reason is required

  • Status updates in the list

  • Agent is notified with the reason provided

Success Criteria:

  • Request status is updated to "Rejected"

  • Agent receives notification with reason

  • Agent does not gain project access

8.4 View Contracts

User Story:
As a Property Manager, I want to see all agent contracts so that I can manage formal agreements.

User Journey:

  1. User clicks "Contracts" tab on the Applications page

  2. Contracts list displays showing:

    • Agent name
    • Project name
    • Contract status (Draft, Sent, Signed, Active, Expired)
    • Contract dates

  3. User can filter by status or project

Expected Behavior:

  • Contracts are organized by status

  • Status badges are color-coded

  • Action buttons vary by contract status

Success Criteria:

  • All contracts are displayed

  • Status information is accurate

  • Filtering works correctly

8.5 Create Agent Contract

User Story:
As a Property Manager, I want to create contracts for agents so that we have formal agreements in place.

User Journey:

  1. User clicks "Create Contract" button (or from an approved request)

  2. Contract creation form appears with fields:

    • Select agent (if not pre-filled)
    • Select project
    • Contract title
    • Contract type
    • Start and end dates
    • Terms and conditions

  3. User fills in contract details

  4. User clicks "Create" button

  5. Contract is created in "Draft" status

Expected Behavior:

  • Form validates required fields

  • Agent dropdown shows approved agents

  • Contract is saved as draft initially

Success Criteria:

  • Contract is created in the database

  • Contract appears in contracts list with "Draft" status

  • Contract can be edited before sending

8.6 Send Contract to Agent

User Story:
As a Property Manager, I want to send contracts to agents so that they can review and sign them.

User Journey:

  1. User locates a draft contract

  2. User clicks "Send" or "Send to Agent" button

  3. User confirms sending

  4. Contract status changes to "Sent"

  5. Agent receives email notification with contract

Expected Behavior:

  • Confirmation is required before sending

  • Status updates immediately

  • Agent receives email with contract details/link

Success Criteria:

  • Contract status is updated to "Sent"

  • Agent receives email notification

  • Agent can view and respond to contract

8.7 Activate Signed Contract

User Story:
As a Property Manager, I want to activate signed contracts so that agents have full project access.

User Journey:

  1. User locates a contract in "Signed" status (agent has signed)

  2. User reviews the signed document

  3. User clicks "Activate" or "Confirm" button

  4. User confirms activation

  5. Contract status changes to "Active"

  6. Agent receives confirmation

Expected Behavior:

  • Only signed contracts can be activated

  • Activation grants full project access

  • Success toast confirms activation

Success Criteria:

  • Contract status is updated to "Active"

  • Agent has full project access

  • Contract dates are enforced

9. Agent Directory

9.1 View All Agents

User Story:
As a Property Manager, I want to browse all registered agents so that I can discover potential partners for my projects.

User Journey:

  1. User clicks "Agents" in the sidebar navigation

  2. User is navigated to /manager/agents

  3. Agent directory displays as a grid of agent cards showing:

    • Agent profile photo
    • Agent name
    • Agency/company (if set)
    • KYC verification status badge
    • Active project count

  4. User can scroll through the list to browse agents

Expected Behavior:

  • Agents are loaded with pagination

  • Verified agents show a verification badge

  • Loading skeleton shows while data loads

  • Empty state shows if no agents registered

Success Criteria:

  • All registered agents are accessible

  • Profile information is accurate

  • Verification status is correctly displayed

9.2 Search Agents

User Story:
As a Property Manager, I want to search for agents by name so that I can find specific agents quickly.

User Journey:

  1. User locates the search input on the agents page

  2. User types agent name or partial name

  3. Results filter in real-time as user types

  4. Matching agents are displayed

Expected Behavior:

  • Search is case-insensitive

  • Results update with each keystroke (debounced)

  • Clear button resets the search

  • "No results" message if no matches

Success Criteria:

  • Search returns relevant agents

  • Performance is acceptable (no lag)

  • Clearing search shows all agents

9.3 Filter Agents by KYC Status

User Story:
As a Property Manager, I want to filter agents by verification status so that I can find verified professionals.

User Journey:

  1. User locates the filter/dropdown on the agents page

  2. User selects KYC status filter:

    • All Agents
    • Verified Only
    • Pending Verification
    • Not Verified

  3. Agent list updates to show only matching agents

Expected Behavior:

  • Filter updates results immediately

  • Filter can be combined with search

  • Count updates to show filtered results

Success Criteria:

  • Filter correctly shows agents by KYC status

  • Multiple filters work together

  • Clear/reset option is available

9.4 View Agent Profile

User Story:
As a Property Manager, I want to view an agent's full profile so that I can assess their qualifications.

User Journey:

  1. User clicks on an agent card in the directory

  2. Agent profile page or modal opens showing:

    • Full name and photo
    • Contact information (if visible)
    • Bio/description
    • KYC verification status and details
    • List of current active projects
    • Performance metrics (if available)

  3. User can close the profile and return to the directory

Expected Behavior:

  • Profile loads completely

  • Sensitive information is appropriately hidden

  • Back button returns to directory

  • "Request Access" or "Invite to Project" options may be available

Success Criteria:

  • Full agent profile is displayed

  • Information is accurate and up-to-date

  • Navigation back to directory works

10. Billing & Subscriptions

10.1 Access Billing Page

User Story:
As a Property Manager, I want to access billing settings so that I can manage my subscription and payments.

User Journey:

  1. User clicks "Settings" in the sidebar navigation

  2. User clicks "Billing" option (or navigates directly to /billing)

  3. Billing page loads with tabbed interface:

    • Plans tab (default)
    • Payment History tab
    • Payment Methods tab

Expected Behavior:

  • Default tab is "Plans"

  • Tab state is reflected in URL (/billing?tab=plans)

  • Tabs are clearly labeled with icons

  • Back button returns to previous page

Success Criteria:

  • Billing page loads correctly

  • All three tabs are accessible

  • URL updates when switching tabs

10.2 View Current Subscription Plan

User Story:
As a Property Manager, I want to see my current subscription plan so that I understand my limits and benefits.

User Journey:

  1. User is on the Billing page, Plans tab

  2. User sees subscription plan cards:

    • Free Plan: Basic features with limits
    • Enterprise Plan: Full features with higher/no limits

  3. Current plan is highlighted with "Current Plan" badge

  4. Plan cards show:

    • Monthly/Annual pricing toggle
    • Feature list with checkmarks
    • Limits (units, projects, agents, etc.)

  5. User can compare plans side-by-side

Expected Behavior:

  • Current plan is clearly identified

  • Pricing updates when toggling monthly/annual

  • Feature comparison is accurate

  • "Upgrade" button shows on non-current plans

Success Criteria:

  • Current plan is correctly identified

  • Pricing and features are accurate

  • Toggle between monthly/annual works

10.3 View Payment History

User Story:
As a Property Manager, I want to see my payment history so that I can track my billing transactions.

User Journey:

  1. User clicks "Payment History" tab on the Billing page

  2. Payment history section displays:

    • Billing Status Card: Next payment date, last payment info
    • Payment History List: All past payments

  3. Each payment entry shows:

    • Date
    • Amount (in KES)
    • Payment method (M-Pesa, Card)
    • Status badge (Completed, Failed, Pending)
    • Invoice number/reference

  4. List is scrollable for many entries

Expected Behavior:

  • Payments are sorted by date (newest first)

  • Status badges are color-coded

  • Empty state if no payments exist

  • Clicking a payment may show details

Success Criteria:

  • All payments are listed

  • Payment details are accurate

  • Status reflects actual payment state

10.4 Manage Payment Methods

User Story:
As a Property Manager, I want to manage my payment methods so that I can update how I pay for subscriptions.

User Journey:

  1. User clicks "Payment Methods" tab on the Billing page

  2. Payment methods section displays:

    • List of saved payment methods
    • Each method shows type (M-Pesa, Card), last digits, expiry
    • Default method is indicated

  3. User can:

    • Add new payment method
    • Remove existing method
    • Set default payment method

Expected Behavior:

  • Saved methods are displayed clearly

  • Add method opens appropriate flow (M-Pesa or Card)

  • Remove requires confirmation

  • Default method is visually distinct

Success Criteria:

  • All saved methods are displayed

  • Add/remove functionality works

  • Default can be changed

10.5 Upgrade Subscription

User Story:
As a Property Manager, I want to upgrade my subscription so that I can access more features and higher limits.

User Journey:

  1. User is on the Billing page, Plans tab

  2. User clicks "Upgrade" on the Enterprise plan card

  3. User is navigated to upgrade/payment page

  4. User selects billing cycle (monthly/annual)

  5. User chooses payment method:

    • M-Pesa: Enter phone number, receive STK push
    • Card: Enter card details or use saved card

  6. User confirms payment

  7. Payment is processed

  8. Subscription is upgraded immediately

  9. User receives confirmation email

Expected Behavior:

  • Upgrade flow guides user through payment

  • Price is clearly displayed before payment

  • STK push (M-Pesa) is sent to user's phone

  • Loading state shows during processing

  • Success/failure feedback is immediate

Success Criteria:

  • Payment is processed successfully

  • Subscription tier is updated

  • New limits are applied immediately

  • Confirmation email is received

11. Permission Boundaries

11.1 What Property Managers CAN Do

Property Managers have the following capabilities within CasaHub:

Project Management:

  • Create new projects (within subscription limits)

  • Edit project settings and information

  • Configure project structure (phases, buildings)

  • Upload project media and documentation

  • View project analytics and reports

Unit Management:

  • Create units (single or bulk, within limits)

  • Edit unit details (price, status, specifications)

  • Change unit status (Available, Reserved, Sold)

  • Assign units to buildings and phases

  • Search and filter units

Team Management:

  • View all team members on their projects

  • Invite new team members via email

  • Assign roles to team members (Manager, Sales Manager, Agent)

  • Remove team members from projects

  • View pending invitations

Agent & Application Management:

  • View all registered agents in the directory

  • Approve agent access requests for their projects

  • Reject access requests with reason

  • Create, send, and manage agent contracts

  • Activate signed contracts

Billing (Self-Service):

  • View current subscription plan

  • View payment history

  • Manage payment methods

  • Upgrade subscription

11.2 What Property Managers CANNOT Do

Property Managers have the following restrictions:

Project Restrictions:

  • Cannot delete projects (only Owners can delete)

  • Cannot transfer project ownership

  • Cannot access projects they don't manage

Administrative Restrictions:

  • Cannot modify system-wide settings

  • Cannot access other users' billing information

  • Cannot view other managers' projects

  • Cannot modify subscription tiers (pricing, features)

User Management Restrictions:

  • Cannot create user accounts directly (invitations only)

  • Cannot modify other users' profiles

  • Cannot assign system roles (only project roles)

  • Cannot bypass KYC verification requirements

Financial Restrictions:

  • Cannot issue refunds directly

  • Cannot modify payment plan configurations for the system

  • Cannot access revenue reports for projects they don't manage

11.3 Subscription Limit Enforcement

Property Managers are subject to subscription limits based on their plan:

Free Tier Limits:

  • Maximum 5 units total

  • Maximum 1 project

  • Maximum 1 agent slot

  • Maximum 1 building per project

  • Maximum 1 phase per project

  • Maximum 1 unit template

  • Maximum 1 payment plan

When Limits Are Reached:

  • User sees "Limit Reached" message when trying to create beyond limits

  • Upgrade prompt is displayed with link to billing page

  • Creation is blocked until upgrade or resource deletion

Enterprise Tier:

  • Higher or unlimited resources (configurable by system)

  • Prorated billing for mid-cycle additions

  • Priority support access

11.4 Route Access Restrictions

Property Managers can access the following routes:

Accessible Routes:

  • /manager/dashboard - Manager dashboard

  • /projects - Projects list

  • /projects/:id - Project details

  • /projects/:id/manage - Project management

  • /manager/applications - Access requests and contracts

  • /manager/agents - Agent directory

  • /billing - Billing and subscription

  • /profile - User profile settings

  • /settings - General settings

Restricted Routes:

  • /owner/* - Owner-specific routes (requires Owner role)

  • /agent/* - Agent-specific routes (requires Agent role)

  • /admin/* - Administrative routes (requires Admin role)

  • /client/* - Client-specific routes (requires Client role)

Behavior on Restricted Access:

  • User is redirected to /unauthorized page

  • Clear message explains access is denied

  • Link to return to appropriate dashboard

End of Document

This document describes the complete user journey for the Property Manager/Owner role in CasaHub. For specific test cases and validation criteria, refer to the companion document. QA test Plan

Last updated 1 hour ago
Was this helpful?
Thanks!