feat(analytics): add search analytics (Closes #245)

[Bogunrot]

1. Linked Issue

Closes #245

2. Problem Statement (The Bug)

There is no visibility into what users search for on the platform. The team can't answer basic questions like "what are the top queries?", "how often do searches return nothing?", or "which topics should we create content for?". Zero-result searches in particular are the direct signal for content gaps, and without tracking them they are invisible. This absence is fundamental — there is no data source at all — so it cannot be fixed with a local patch; it requires a logging + aggregation pipeline and admin-facing endpoints.

3. Solution Comparison and Decision

Options considered:

• Option A — Parse box/nginx-style request logs. Reuses infrastructure but loses structured data (who searched, result counts, which searches were zero-result) and couples analytics to log rotation.
• Option B — Client-side (frontend) event reporting only. Requires frontend changes and can miss server-side cached/other traffic; loses a single source of truth.
• Option C (chosen) — Server-side middleware hooked into the real search routes, storing one event per query in Mongo with a TTL, plus admin aggregation endpoints.

Option C is chosen because it is structured, reliable (records every real search served by the API), and lives entirely in the backend — no frontend coordination needed to start capturing data.

4. The Change (Code modifications)

• searchLogger middleware wired into GET /api/search and GET /api/search/educators. It records the query, type, result count, whether it returned zero results, session/user, and filters. Logging is fire-and-forget (a failed write never fails or slows the search).
• SearchAnalyticsEvent model with a 90-day TTL and indexes on query/hasResults.
• Service aggregates top queries by frequency, zero-result searches, a summary, and daily trends — all filterable by date range and type, with pagination.
• Admin-gated GET /api/analytics/search/{top,zero-results,summary,trends}.

Core logging piece:

export const searchLogger = (req, res, next) => {
  const originalJson = res.json.bind(res);
  res.json = function (body) {
    res.json = originalJson;
    const query = (req.query.q || req.query.query || "").trim();
    if (query) {
      const resultCount = countResults(body);
      logSearchEvent({
        userId: req.user?._id || null,
        query,
        type: req.query.type || "all",
        resultCount,
        hasResults: resultCount > 0,
        // ...
      }).catch((err) => logger.error("Failed to log search event:", err));
    }
    return originalJson(body);
  };
  next();
};

Endpoint	Auth	Purpose
GET /api/search / GET /api/search/educators	public	logs each query (wired middleware)
GET /api/analytics/search/top	admin	top queries by frequency, date/type filtered, paginated
GET /api/analytics/search/zero-results	admin	zero-result queries (content gaps)
GET /api/analytics/search/summary	admin	totals + zero-result rate
GET /api/analytics/search/trends	admin	searches per day over time

5. Compatibility Note (On INTERFACE_VERSION)

This project exposes no INTERFACE_VERSION, and nothing about this feature changes it: the feature is purely additive (new middleware on read routes + new admin endpoints + a new collection). No existing response is modified.

6. Incidental Fixes (Two things the issue called out that also got fixed)

• Timestamps on every query are guaranteed by the model's timestamps: true (createdAt) so searches can be sliced by date range.
• Zero-result searches are tracked distinctly (hasResults: false) rather than inferred by counting later, so the /zero-results endpoint and summary rate are exact.

7. Testing (Proving it works)

• Unit (test/searchAnalytics.test.js): every admin aggregation endpoint returns a { success, data } envelope, handles empty collections, and applies filters.
• End-to-end (test/searchAnalyticsIntegration.test.js) hits the real paths through app.js with mongodb-memory-server:
  • performs real GET /api/search calls, then asserts events land in Mongo with the query, createdAt timestamp, and correct hasResults/resultCount;
  • a zero-result search is surfaced by GET /api/analytics/search/zero-results;
  • repeated searches are reported by GET /api/analytics/search/top by frequency;
  • the analytics endpoints are guarded (401 anonymous, 403 non-admin).

Suite	Result
test/searchAnalytics.test.js	✅ 13/13
test/searchAnalyticsIntegration.test.js	✅ 4/4
test/search.test.js (pre-existing search suite)	✅ 7/7

All green. The coreFlows.test.js suite has a pre-existing spawnSync-import hang (app's hourly trending-hashtag setInterval), unrelated to this change.

8. Additional Notes (Scope)

Scope is search analytics only: new searchAnalyticsController, search-analytics-service, search-analytics-event model, search-logger middleware, routes/analytics/search.js, plus wiring into searchRoutes.js and app.js. No unrelated files changed.

[drips-wave]

@Bogunrot 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

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Team

Run ID: 465a37b6-23e5-44be-ba25-56c1e72a9977

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[zeemscript]

@Bogunrot this PR has merge conflicts with the main branch. Please resolve the conflicts (merge main in or rebase) and push the fix so it can be merged. Thanks!