Extend Search to Beneficiaries with Filters, Pagination, Sorting, and Facets

[grantfox-oss]

Description

Current search only covers campaigns and donations. Extend the search feature to support beneficiaries with advanced filtering, pagination, sorting, faceted search, and optimized query performance.

Background

Beneficiary discovery is currently limited, making it harder for donors, admins, and partners to find people in need by location, profile attributes, or risk/verification status. A richer beneficiary search experience will improve matching, transparency, and platform usability.

Scope

• Add beneficiary search support alongside existing campaign/donation search
• Filter beneficiaries by:
  • location: country, city
  • needs category
  • verification status
  • risk score
  • age range
  • family size
• Add pagination and sorting to beneficiary search results
• Add faceted search metadata for common dimensions
• Optimize search queries with indexes and query tuning
• Ensure API contract is backward-compatible for campaigns/donations

Goals

• Enable search users to discover beneficiaries by both demographic and programmatic attributes
• Provide responsive search with pagination and sorting
• Provide UI-friendly facet metadata for filter counts
• Prevent slow scans by adding appropriate database indexes and query optimizations

Functional requirements

Beneficiary filters

Support search filters for beneficiaries:

• location.country
• location.city
• needsCategory
• verificationStatus (e.g. VERIFIED, PENDING, REJECTED)
• riskScore range
• age range
• familySize range

Pagination

• Add page and limit support
• Return pagination metadata:
  • total
  • page
  • pageSize
  • totalPages

Sorting

Support sorting by:

• relevance / score
• createdAt
• updatedAt
• riskScore
• age
• familySize

Faceted search

Return facet counts for beneficiary search results, including:

• country
• city
• needs categories
• verification status
• risk score buckets
• age ranges
• family size buckets

Faceted responses should support UI filter panels and drill-down.

Query optimization

• Add indexes on beneficiary search fields:
  • country, city
  • needsCategory
  • verificationStatus
  • riskScore
  • age
  • familySize
• Use query plans or full-text indexes where appropriate
• Avoid N+1 queries and repeated joins
• Ensure faceted aggregation queries are efficient
• Add test coverage to verify performance-sensitive queries

API contract

Extend search endpoints or add beneficiary-specific search routes:

• GET /search/beneficiaries or GET /beneficiaries/search
• Query params:
  • q
  • country
  • city
  • needsCategory
  • verificationStatus
  • riskScoreMin
  • riskScoreMax
  • ageMin
  • ageMax
  • familySizeMin
  • familySizeMax
  • page
  • limit
  • sortBy
  • sortOrder
• Response shape:
  • results: Beneficiary[]
  • pagination: { total, page, pageSize, totalPages }
  • facets: { countries, cities, needsCategories, verificationStatuses, riskScoreRanges, ageRanges, familySizeRanges }

Acceptance criteria

• Beneficiaries are searchable via existing or new search endpoint
• Filters for location, needs, verification, risk, age, and family size work correctly
• Pagination returns stable pages with metadata
• Sorting works for supported fields
• Faceted counts are returned and match filtered result set
• Query performance is optimized with indexes and efficient SQL
• Existing campaign and donation search behavior remains unchanged
• Tests cover filtering, pagination, sorting, facets, and query correctness

Implementation notes

• Add or extend search.service.ts, search.controller.ts, and route definitions
• Update Prisma schema / DB model indexes if needed
• Add search-specific DTO/validation for beneficiary filter params
• Add unit and integration tests for beneficiary search
• Document new beneficiary search parameters in API.md

[Oluwatos94]

Hi Maintainer, I'm Tosin, a software developer with many years of working experience.

I'll extend the search layer to support beneficiaries. The work splits cleanly into four parts: a BeneficiarySearchDto with validated query params, service-layer filter + sort + pagination logic, faceted aggregation queries, and Prisma index additions on the searchable fields. Facets get computed in the same query pass to avoid redundant DB hits. N+1 is a non-issue since beneficiary results won't need joined sub-queries beyond what Prisma handles at the model level.

Tests will cover filtering, pagination edge cases, sort correctness, and facet accuracy.

[tydavid5]

hi team, kindly assign this task to me

[grantfox-oss]

🦊 GrantFox — @Oluwatos94 has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #74)
2. Your PR will be reviewed by the aid-linkk maintainers

Good luck! Track your progress on GrantFox.

[GBOYEE]

Hi! I'd like to work on this issue.

I have experience with this stack and can deliver a clean, tested solution. Please assign this to me and I'll submit a PR shortly.

My approach:

• Analyze the root cause
• Implement a fix following existing code patterns
• Add tests and documentation

Thanks!

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign campaign!

@Oluwatos94's PR #97 was approved and merged by @BarryArinze.

🏆 @Oluwatos94: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (261 total points). Track your full progress on GrantFox.

👏 Great work, @Oluwatos94! Keep contributing to aid-linkk.