Ritam/unified tracking

apps/backend/src/bootstrap/loaders/express.ts

@@ -12,6 +12,7 @@ import routeRedirectRoutes from "../../modules/route-redirect/routes";
 import semanticSearchRoutes from "../../modules/semantic-search/routes";
 import staffRoutes from "../../modules/staff/routes";
 import targetedMessageRoutes from "../../modules/targeted-message/routes";
+import trackingRoutes from "../../modules/tracking/routes";
 import passportLoader from "./passport";
 
 export default async (
@@ -79,6 +80,9 @@ export default async (
     targetedMessageRoutes(root, redis);
   }
 
+  // load tracking beacon route
+  trackingRoutes(app, redis);
+
   // load semantic search routes
   app.use("/semantic-search", semanticSearchRoutes);
 

apps/backend/src/bootstrap/loaders/index.ts

@@ -4,6 +4,7 @@ import { config } from "../../../../../packages/common/src/utils/config";
 import { startBannerViewCountFlushJob } from "../../modules/banner/jobs/flush-view-counts";
 import { startViewCountFlushJob } from "../../modules/class/jobs/flush-view-counts";
 import { startClickEventsFlushJob } from "../../modules/click-tracking/jobs/flush-click-events";
+import { startTrackingEventsFlushJob } from "../../modules/tracking/jobs/flush-tracking-events";
 import { startActivityScoreUpdateJob } from "../../modules/user/jobs/update-activity-scores";
 // loaders
 import apolloLoader from "./apollo";
@@ -35,6 +36,7 @@ export default async (root: Application): Promise<void> => {
   startBannerViewCountFlushJob(apolloRedis);
   startClickEventsFlushJob(apolloRedis);
   startActivityScoreUpdateJob();
+  startTrackingEventsFlushJob(apolloRedis);
 
   // append backend path to all routes
   root.use(config.backendPath, app);

apps/backend/src/modules/banner/routes.ts

@@ -4,6 +4,7 @@ import type { RedisClientType } from "redis";
 import { BannerModel } from "@repo/common/models";
 
 import { trackIntensiveClick } from "../click-tracking/controller";
+import { bufferTrackingEvents } from "../tracking/controller";
 
 export default (app: Application, redis?: RedisClientType) => {
   // Redirect-based click tracking for all banners
@@ -23,10 +24,25 @@ export default (app: Application, redis?: RedisClientType) => {
         return res.redirect("/");
       }
 
-      // Track click event if enabled and redis is available
-      if (banner.clickEventLogging && redis) {
-        trackIntensiveClick(redis, req, bannerId, "banner").catch((error) => {
-          console.error("Error tracking banner click event:", error);
+      if (redis) {
+        // Legacy intensive click tracking (opt-in per banner)
+        if (banner.clickEventLogging) {
+          trackIntensiveClick(redis, req, bannerId, "banner").catch((error) => {
+            console.error("Error tracking banner click event:", error);
+          });
+        }
+
+        // Unified tracking — always emitted
+        bufferTrackingEvents(redis, req, [
+          {
+            eventType: "click",
+            targetType: "banner",
+            targetId: bannerId,
+            metadata: { version: banner.currentVersion },
+            timestamp: new Date().toISOString(),
+          },
+        ]).catch((error) => {
+          console.error("Error buffering banner tracking event:", error);
         });
       }
 

apps/backend/src/modules/catalog/controller.ts

@@ -25,13 +25,13 @@ import {
 } from "@repo/common/models";
 
 import { getFields, hasFieldPath } from "../../utils/graphql";
-import { searchSemantic } from "../semantic-search/client";
 import { formatClass, formatSection } from "../class/formatter";
 import type { ClassModule } from "../class/generated-types/module-types";
 import { formatCourse } from "../course/formatter";
 import { formatEnrollment } from "../enrollment/formatter";
 import type { EnrollmentModule } from "../enrollment/generated-types/module-types";
 import type { GradeDistributionModule } from "../grade-distribution/generated-types/module-types";
+import { searchSemantic } from "../semantic-search/client";
 import { getCachedCatalog, getSearchIndex } from "./catalog-cache";
 
 export interface CatalogQueryParams {

apps/backend/src/modules/index.ts

@@ -19,6 +19,7 @@ import Schedule from "./schedule";
 import Staff from "./staff";
 import TargetedMessage from "./targeted-message";
 import Term from "./term";
+import Tracking from "./tracking";
 import User from "./user";
 
 const modules = [
@@ -42,6 +43,7 @@ const modules = [
   RouteRedirect,
   Pod,
   TargetedMessage,
+  Tracking,
 ];
 
 export const resolvers = merge(modules.map((module) => module.resolver));

apps/backend/src/modules/rating/formatter.ts

@@ -36,8 +36,9 @@ export const formatUserRatings = (ratings: UserRatings): UserRatings => {
 
       reviewTitle: (userClass as UserClass & { reviewTitle?: string | null })
         .reviewTitle,
-      reviewContent: (userClass as UserClass & { reviewContent?: string | null })
-        .reviewContent,
+      reviewContent: (
+        userClass as UserClass & { reviewContent?: string | null }
+      ).reviewContent,
       lastUpdated: userClass.lastUpdated?.toString(),
     })),
   };

apps/backend/src/modules/route-redirect/routes.ts

@@ -4,6 +4,7 @@ import type { RedisClientType } from "redis";
 import { RouteRedirectModel } from "@repo/common/models";
 
 import { trackIntensiveClick } from "../click-tracking/controller";
+import { bufferTrackingEvents } from "../tracking/controller";
 
 export default (app: Application, redis?: RedisClientType) => {
   // Server-side redirect handler for snappy redirects
@@ -25,15 +26,30 @@ export default (app: Application, redis?: RedisClientType) => {
         return res.redirect("/");
       }
 
-      // Track click event if enabled and redis is available
-      if (redirect.clickEventLogging && redis) {
-        trackIntensiveClick(
-          redis,
-          req,
-          redirect._id.toString(),
-          "redirect"
-        ).catch((error) => {
-          console.error("Error tracking redirect click event:", error);
+      if (redis) {
+        // Legacy intensive click tracking (opt-in per redirect)
+        if (redirect.clickEventLogging) {
+          trackIntensiveClick(
+            redis,
+            req,
+            redirect._id.toString(),
+            "redirect"
+          ).catch((error) => {
+            console.error("Error tracking redirect click event:", error);
+          });
+        }
+
+        // Unified tracking — always emitted
+        bufferTrackingEvents(redis, req, [
+          {
+            eventType: "click",
+            targetType: "redirect",
+            targetId: redirect._id.toString(),
+            metadata: { fromPath, toPath: redirect.toPath },
+            timestamp: new Date().toISOString(),
+          },
+        ]).catch((error) => {
+          console.error("Error buffering redirect tracking event:", error);
         });
       }
 

apps/backend/src/modules/targeted-message/routes.ts

@@ -4,6 +4,7 @@ import type { RedisClientType } from "redis";
 import { TargetedMessageModel } from "@repo/common/models";
 
 import { trackIntensiveClick } from "../click-tracking/controller";
+import { bufferTrackingEvents } from "../tracking/controller";
 
 export default (app: Application, redis?: RedisClientType) => {
   // Redirect-based click tracking for targeted messages
@@ -43,12 +44,41 @@ export default (app: Application, redis?: RedisClientType) => {
           })
         : undefined;
 
-      // Track click event if enabled and redis is available
-      if (message.clickEventLogging && redis) {
-        trackIntensiveClick(redis, req, messageId, "targeted-message", {
-          additionalInfo: resolvedAdditionalInfo,
-        }).catch((error) => {
-          console.error("Error tracking targeted message click event:", error);
+      if (redis) {
+        // Legacy intensive click tracking (opt-in per message)
+        if (message.clickEventLogging) {
+          trackIntensiveClick(redis, req, messageId, "targeted-message", {
+            additionalInfo: resolvedAdditionalInfo,
+          }).catch((error) => {
+            console.error(
+              "Error tracking targeted message click event:",
+              error
+            );
+          });
+        }
+
+        // Unified tracking — always emitted
+        bufferTrackingEvents(redis, req, [
+          {
+            eventType: "click",
+            targetType: "targeted-message",
+            targetId: messageId,
+            metadata: matchedCourse
+              ? {
+                  courseId: courseIdParam,
+                  subject: matchedCourse.subject,
+                  courseNumber: matchedCourse.courseNumber,
+                  semester: semesterParam,
+                  year: yearParam ? Number(yearParam) : undefined,
+                }
+              : undefined,
+            timestamp: new Date().toISOString(),
+          },
+        ]).catch((error) => {
+          console.error(
+            "Error buffering targeted-message tracking event:",
+            error
+          );
         });
       }