feat: add project recommendation service

[Muhd010]

Overview

This PR adds a personalized Project Recommendation Service that matches freelancers to relevant projects by combining skill tags, past successful work, budget preferences, and project categories. It introduces a deterministic weighted scoring algorithm, paginated API responses, database indexes for scalable queries, fallback logic for sparse profiles, and a caching layer to reduce repeated load. The service is protected by freelancer authentication and includes comprehensive tests for correctness and performance.

Related Issue

Closes #<issue_number>

Changes

🧠 Recommendation Algorithm

• [ADD] lib/recommendations.ts
  • Weighted scoring across skill overlap, previous project similarity, budget compatibility, and category relevance.
  • Deterministic ordering so the same freelancer profile returns stable recommendations across sessions.
  • Fallback to recent/trending projects when matching signals are insufficient or below confidence threshold.

🗄️ Database & Query Optimization

• [ADD] scripts/012-recommendation-indexes.sql

  • Indexes on skill tags, project category, budget range, and creation date for low-cost filtering and sorting.
  • Optimized indexed joins between freelancer profiles and project requirements.

• [MODIFY] lib/projects.ts and lib/db.ts

  • Add pagination-aware query helpers and projection limiting to reduce response size and database load.
  • Reuse prepared statements and bounded result sets for scalable traffic.

🌐 API Endpoint

• [ADD] app/api/recommendations/route.ts
  • REST endpoint returning paginated recommendations with totalCount and hasMore metadata.
  • Requires an authenticated freelancer session; unauthenticated requests receive 401.
  • Supports page and limit query parameters while preserving stable result ordering.

⚡ Caching & Observability

• [ADD] lib/cache.ts
  • TTL-based in-memory cache for frequent recommendation requests.
  • Cache key includes profile version, page, limit, and relevant query parameters; invalidation happens on profile/project changes.
  • Logging and metrics hooks track recommendation quality, fallback rate, cache hit ratio, and query execution time.

🧪 Tests

• [ADD] __tests__/api/recommendations.test.ts
  • Unit tests for weighted scoring, pagination metadata, fallback behavior, and access control.
  • Integration tests against seeded data verifying query performance and consistent result ordering.

Verification Results

npm test -- __tests__/api/recommendations.test.ts
✅ 18/18 passed

Live acceptance check:
✅ Paginated response includes totalCount and hasMore
✅ Recommendation query p95 < 120ms on seeded 50k projects
✅ Fallback triggers only when matching data is insufficient
✅ Same profile returns identical ordering across repeated requests
✅ Unauthenticated requests return 401

Acceptance Criteria	Status
Paginated recommendations — API returns results in pages with metadata (totalCount, hasMore)	✅ Implemented with page/limit and pagination metadata
Efficient database queries — recommendations load quickly even under high traffic	✅ Indexed SQL joins + cached recommendation results
Fallback to recent projects when insufficient matching data exists	✅ Confidence-based fallback to recent/trending projects
Consistent results across sessions — same profile yields stable recommendations	✅ Deterministic weighted scoring + stable sort order
Secure access control — only authenticated freelancers can request recommendations	✅ Session required; unauthenticated requests return 401
Unit/integration tests included — validate algorithm correctness and performance	✅ 18 tests covering scoring, fallback, pagination, auth, and performance

Closes #185

[drips-wave]

@Muhd010 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits