Clients List Page

Created: November 23, 2025
Route: /clients
File: app/(crm)/clients/page.tsx

Overview

The Clients List page provides a comprehensive view of all client households and intake submissions in the CRM system.

Features

📊 Dashboard Stats

Four key metrics displayed at the top:

• Total Households - All active households in the system
• Intake Completed - Households with completed intake applications
• Urgent Priority - Households marked as urgent priority
• High Priority - Households marked as high priority

🔍 Filtering System

Priority Filter:

• All (default)
• Urgent
• High
• Medium
• Low

Intake Status Filter:

• All (default)
• Completed - Shows only households with completed intake
• Incomplete - Shows only households with incomplete intake

Filters update the URL with query parameters for bookmarkable filtered views.

📋 Data Table

Columns:

1. Household - Household name, size, and flags (children, veteran)
2. Contact - Head of household name and phone
3. Location - City, state, and zip code
4. Housing Status - Current housing situation with color-coded badges
5. Priority - Priority level and vulnerability score
6. Intake - Completion status and date
7. Actions - Link to detailed household profile

🎨 Visual Indicators

Housing Status Badges:

• 🔴 Red: Homeless
• 🟠 Orange: Sheltered
• 🟡 Yellow: At Risk
• 🟢 Green: Housed/Stable

Priority Badges:

• 🔴 Red: Urgent (70-100 vulnerability score)
• 🟠 Orange: High (50-69)
• 🟡 Yellow: Medium (30-49)
• 🟢 Green: Low (0-29)

Intake Status:

• 🟢 Green: Completed
• ⚪ Gray: Incomplete

🔗 Navigation

Access Points:

• CRM Navigation: "Clients" menu item
• CRM Dashboard: Click "Households" stat card
• CRM Dashboard: "View Clients" quick action
• Direct URL: /clients

Actions:

• "View Details" → Takes you to /clients/[id] for full household profile
• "+ New Intake" → Opens the intake form at /intake

Data Source

The page queries the households table with a join to clients to get:

• All household information
• Head of household details
• Intake completion status
• Priority and vulnerability scores

Query Structure:

supabase
  .from('households')
  .select(`
    *,
    clients!inner(
      id, first_name, last_name, 
      phone, email, is_head_of_household
    )
  `)
  .eq('status', 'active')

Access Control

• Admin/Staff: View all households system-wide
• Caseworkers: View only households in their organization
• Org Users: View only households in their organization

Access is controlled via RLS policies on the households table.

URL Parameters

Priority Filter:

• /clients - All priorities
• /clients?priority=urgent - Urgent only
• /clients?priority=high - High only
• /clients?priority=medium - Medium only
• /clients?priority=low - Low only

Intake Filter:

• /clients?intake=completed - Completed intake only
• /clients?intake=incomplete - Incomplete intake only

Combined:

• /clients?priority=urgent&intake=completed

Empty States

The page handles empty states gracefully:

• No households in system
• No matches for current filter
• Displays helpful message and icon
• Suggests adjusting filters or creating new intake

Responsive Design

• ✅ Mobile-friendly table (horizontal scroll)
• ✅ Responsive filter buttons
• ✅ Stacked stat cards on mobile
• ✅ Dark mode support
• ✅ Touch-friendly click targets

Performance

Optimizations:

• Server-side rendering (RSC)
• Single database query with join
• Indexed columns (status, org_id)
• Client-side filtering after data load

Integration Points

Links To:

• Individual household profiles (/clients/[id])
• Intake form (/intake)
• Resource matching (via household profile)
• Referral creation (via household profile)

Linked From:

• CRM Navigation
• CRM Dashboard
• Admin users page (future)

Future Enhancements

Planned Features:

1. Search Functionality

   • Search by name, phone, email
   • Search by location (city, zip)

2. Sorting

   • Sort by priority score
   • Sort by intake date
   • Sort by household size

3. Pagination

   • Limit to 50 per page
   • Page navigation controls

4. Bulk Actions

   • Assign caseworker to multiple
   • Export to CSV
   • Print/PDF reports

5. Advanced Filters

   • Filter by immediate needs
   • Filter by veteran status
   • Filter by household composition
   • Date range filters

6. Column Customization

   • Show/hide columns
   • Reorder columns
   • Save preferences

Usage Examples

View All Urgent Cases

Navigate to: /clients?priority=urgent

View Incomplete Intakes

Navigate to: /clients?intake=incomplete

View High Priority Completed Intakes

Navigate to: /clients?priority=high&intake=completed

Related Documentation

• Applicant Intake Implementation
• Resource Library & Coordinated Entry
• Referral System

Support

Common Questions

Q: Why don't I see any households?
A: Check that:

• You have proper permissions (staff, admin, or caseworker role)
• Your organization has households assigned
• The households table has data

Q: Why can't I see certain households?
A: Non-admin users can only see households in their organization. Check your org_id in your profile.

Q: How do I assign priority levels?
A: Priority levels are automatically calculated based on the vulnerability score during intake submission.

Q: Can I manually edit household data?
A: Currently, household data can be viewed but not edited from this page. Navigate to the individual household profile for more options.

---

Page Created: November 23, 2025
Last Updated: November 23, 2025