Step 14 Management Bundles

Purpose (Product)

• Allow landlords to choose their preferred level of property management support, determining the services they'll receive and the pricing structure.

• Three tiers available: Manual (free), Co-managed (monthly fee), and Pro (monthly fee + 5% rental income).

• Pro tier selection triggers onboarding pause and requires a call with the team for verification and setup.

---

UX Flow (What the user sees)

• Three horizontally arranged plan cards with property images, tier names, pricing, and feature lists.

• Each card shows: image, tier name, price, description, and bulleted feature list.

• Pro tier has a "Top Choice" badge. Cards have hover effects and selection states.

• Selecting a plan highlights the card and updates the form. Validation requires plan selection before proceeding.

![[Service Bundles.png]]

---

System Flow (How it works)

sequenceDiagram
    actor Landlord
    participant Frontend as Web App (Next.js)
    participant Backend as API (NestJS)
    participant DB as Database

    %% Load management tiers
    Frontend->>Backend: GET /api/management-tiers
    Backend-->>Frontend: Management tier data with pricing

    %% Plan selection
    Landlord->>Frontend: Click plan card
    Frontend->>Frontend: Update selectedPlan state
    Frontend->>Frontend: Set form values (plan, isOnboardingPaused)

    %% Submit plan selection
    Landlord->>Frontend: Click "Next"
    Frontend->>Frontend: Validate form (plan required)

    Frontend->>Backend: PATCH /api/properties/{id} { managementTierId }
    Backend->>DB: Update properties.managementTierId

    Frontend->>Backend: PATCH /api/users/{id} { isOnboardingPaused }
    Backend->>DB: Update users.isOnboardingPaused

    Backend-->>Frontend: 200 OK (updated property and user)
    Frontend->>Frontend: Update local user context
    Frontend->>Frontend: Advance to next step

---

Data Touched

Properties table:

• managementTierId (string, required): References management tier

Users table:

• isOnboardingPaused (boolean): Set to true for Pro tier if user hasn't had onboarding call

Management Tiers table:

• id, name, displayName, description, basePrice (read-only)

Validation rules:

• Plan selection is required

• Pro tier automatically sets isOnboardingPaused = true (unless user had onboarding call)

---

APIs Called

GET /api/management-tiers

• Method: GET

• Response: Array of management tier objects

• Used to populate plan options and pricing

PATCH /api/properties/{id}

• Method: PATCH

• Payload: { managementTierId: string }

• Response: Updated property object

• Idempotent: Yes

PATCH /api/users/{id}

• Method: PATCH

• Payload: { isOnboardingPaused: boolean }

• Response: Updated user object

• Idempotent: Yes

---

QA Checklist

Basic functionality:

• All three plan cards display correctly with images

• Plan selection highlights selected card

• Form validation prevents submission without plan selection

• Pro tier shows "Top Choice" badge

Plan selection:

• Manual plan sets isOnboardingPaused = false

• Co-managed plan sets isOnboardingPaused = false

• Pro plan sets isOnboardingPaused = true (unless user had onboarding call)

• Plan selection persists across page refreshes

Data persistence:

• Management tier ID saved to property

• User onboarding pause status updated

• Form pre-populates with existing selection on page load

Error handling:

• Network errors handled gracefully

• Validation errors display clearly

• Failed operations don't break form state

UX/UI:

• Cards have proper hover effects

• Selected state is clearly indicated

• Responsive design works on mobile/desktop

• Feature lists display correctly with bullet points