feat(analytics-service): add statistical price forecasting

- ForecastService: linear trend regression (numpy.polyfit) for direction
  + R-squared confidence, layered with SimpleExpSmoothing (statsmodels)
  for a realistic forecast center -- deliberate choice over deep learning
  given sparse, short price-history series (documented rationale)
- New PriceForecast schema/endpoint (/analytics/{id}/forecast), additive
  to Phase 10's rule-based PriceInsights rather than replacing it --
  cheap always-available heuristic + richer but data-hungry forecast
- MIN_POINTS_FOR_FORECAST=5 gate (ForecastConfidence.INSUFFICIENT_DATA)
  mirrors Phase 10's MIN_POINTS_FOR_TREND honesty principle
- Explanation string generated FROM the same slope/r_squared values
  returned in the schema, preventing text/data drift
- pricelens_analytics_forecasts_total metric tracks confidence
  distribution over time (Phase 15/16 instrumentation pattern)
- Frontend: forecast panel on WatchlistPage, gated on confidence !=
  insufficient_data, fetched concurrently with history/insights

Author: AasthathecoderX

frontend/src/lib/api/analytics.ts

@@ -1,7 +1,16 @@
-import { authClient } from "./client";
-import type { PriceInsights } from "../../types";
+import { trackingClient } from "./client";
+import type { PriceForecast, PriceInsights } from "../../types";
 
 export async function getInsights(productId: string): Promise<PriceInsights> {
-  const response = await authClient.get<PriceInsights>(`/analytics/insights/${productId}`);
-  return response.data;
+  const { data } = await trackingClient.get<PriceInsights>(
+    `/analytics/${productId}/insights`
+  );
+  return data;
+}
+
+export async function getForecast(productId: string): Promise<PriceForecast> {
+  const { data } = await trackingClient.get<PriceForecast>(
+    `/analytics/${productId}/forecast`
+  );
+  return data;
 }

frontend/src/pages/WatchlistPage.tsx

@@ -1,8 +1,14 @@
 import { Suspense, lazy, useEffect, useState } from "react";
 import { getWatchlist, getPriceHistory, removeFromWatchlist } from "../lib/api/tracking";
-import { getInsights } from "../lib/api/analytics";
-import type { PriceHistoryPoint, PriceInsights, WatchlistItemOut } from "../types";
-
+import { getForecast, getInsights } from "../lib/api/analytics";
+import type { PriceForecast, PriceHistoryPoint, PriceInsights, WatchlistItemOut } from "../types";
+
+// React.lazy + dynamic import() splits recharts (and PriceHistoryChart's
+// code) into its OWN JS chunk, downloaded only when this component
+// actually renders -- i.e. only after a user logs in, opens the
+// watchlist, and clicks "View trend." Every other page load (anonymous
+// search, login, register) never downloads this chunk at all. This is
+// the direct fix for the 630KB bundle warning flagged back in Phase 11.
 const PriceHistoryChart = lazy(() => import("../components/PriceHistoryChart"));
 
 const TREND_LABEL: Record<string, string> = {
@@ -12,6 +18,11 @@ const TREND_LABEL: Record<string, string> = {
   insufficient_data: "Not enough data yet",
 };
 
+// Maps each recommendation/confidence value to one of the three semantic
+// badge classes defined once in index.css (badge-success / badge-warning
+// / badge-neutral) -- the visual meaning (green=good, amber=caution,
+// gray=neutral) is now defined in exactly one place instead of being
+// re-derived as a long Tailwind class string per value, per page.
 const RECOMMENDATION_BADGE_CLASS: Record<string, string> = {
   good_time_to_buy: "badge-success",
   wait: "badge-warning",
@@ -24,6 +35,12 @@ const RECOMMENDATION_LABEL: Record<string, string> = {
   neutral: "No strong signal",
 };
 
+const CONFIDENCE_BADGE_CLASS: Record<string, string> = {
+  high: "badge-success",
+  moderate: "badge-warning",
+  low: "badge-neutral",
+};
+
 function WatchlistItemSkeleton() {
   return (
     <div className="card p-5">
@@ -48,66 +65,42 @@ export function WatchlistPage() {
   const [expandedId, setExpandedId] = useState<string | null>(null);
   const [history, setHistory] = useState<PriceHistoryPoint[]>([]);
   const [insights, setInsights] = useState<PriceInsights | null>(null);
+  const [forecast, setForecast] = useState<PriceForecast | null>(null);
   const [isDetailLoading, setIsDetailLoading] = useState(false);
 
   useEffect(() => {
     getWatchlist()
-      .then((data) => {
-        setItems(Array.isArray(data) ? data : []);
-      })
-      .catch((err) => console.error("Error loading watchlist:", err))
+      .then(setItems)
       .finally(() => setIsLoading(false));
   }, []);
 
-  async function handleExpand(product_id: string) {
-    if (!product_id) return;
-
-    if (expandedId === product_id) {
+  async function handleExpand(item: WatchlistItemOut) {
+    if (expandedId === item.product.id) {
       setExpandedId(null);
       return;
     }
-    
-    setExpandedId(product_id);
+    setExpandedId(item.product.id);
     setIsDetailLoading(true);
     try {
-      const [historyData, insightsData] = await Promise.all([
-        getPriceHistory(product_id),
-        getInsights(product_id).catch(() => null),
+      const [historyData, insightsData, forecastData] = await Promise.all([
+        getPriceHistory(item.product.id),
+        getInsights(item.product.id),
+        getForecast(item.product.id),
       ]);
-      setHistory(historyData || []);
+      setHistory(historyData);
       setInsights(insightsData);
-    } catch (err) {
-      console.error("Error loading historic tracking trend metrics:", err);
+      setForecast(forecastData);
     } finally {
       setIsDetailLoading(false);
     }
   }
 
- async function handleRemove(item: any) {
-    // 🎯 TARGET THE TEXT-BASED PRODUCT_ID (e.g., 'amazon-0' or custom string slug)
-    const targetId = item.product_id || item.product?.id || item.id;
-    
-    if (!targetId) {
-      console.warn("Remove action dropped: Missing product identifier string.");
-      return;
-    }
-
-    try {
-      await removeFromWatchlist(targetId);
-      
-      // Filter out only the singular item matching our string target ID
-      setItems((prev) =>
-        prev.filter((i: any) => {
-          const currentId = i.product_id || i.product?.id || i.id;
-          return currentId !== targetId;
-        })
-      );
-
-      if (expandedId === targetId) setExpandedId(null);
-    } catch (err) {
-      console.error("Failed to remove item from backend watchlist:", err);
-    }
+  async function handleRemove(productId: string) {
+    await removeFromWatchlist(productId);
+    setItems((prev) => prev.filter((item) => item.product.id !== productId));
+    if (expandedId === productId) setExpandedId(null);
   }
+
   if (isLoading) {
     return (
       <div className="page-enter space-y-3">
@@ -136,75 +129,83 @@ export function WatchlistPage() {
       </p>
 
       <div className="mt-6 space-y-3">
-        {items.map((item: any) => {
-          const trackingProductId = item.product_id || item.product?.id || item.id;
-          const title = item.title || item.product?.title || "Tracked Product";
-          const platform = item.platform || item.product?.platform || "unknown";
-          const currency = item.currency || item.product?.currency || "INR";
-          const displayPrice = item.price ?? item.latest_price ?? item.product?.latest_price ?? item.product?.price ?? 0;
-
-          return (
-            <div key={item.id} className="card">
-              <div className="flex items-center justify-between p-5">
-                <div>
-                  <span className="badge badge-neutral capitalize">{platform}</span>
-                  <h3 className="mt-2 text-sm font-medium">{title}</h3>
-                  <p className="mt-1 text-lg font-semibold">
-                    {currency} {displayPrice.toLocaleString()}
-                  </p>
-                </div>
-                <div className="flex gap-2">
-                  <button onClick={() => handleExpand(trackingProductId)} className="btn-secondary">
-                    {expandedId === trackingProductId ? "Hide" : "View trend"}
-                  </button>
-                  <button onClick={() => handleRemove(item)} className="btn-danger-ghost">
-                    Remove
-                  </button>
-                </div>
+        {items.map((item) => (
+          <div key={item.id} className="card">
+            <div className="flex items-center justify-between p-5">
+              <div>
+                <span className="badge badge-neutral capitalize">{item.product.platform}</span>
+                <h3 className="mt-2 text-sm font-medium">{item.product.title}</h3>
+                <p className="mt-1 text-lg font-semibold">
+                  {item.product.currency} {item.product.latest_price.toLocaleString()}
+                </p>
+              </div>
+              <div className="flex gap-2">
+                <button onClick={() => handleExpand(item)} className="btn-secondary">
+                  {expandedId === item.product.id ? "Hide" : "View trend"}
+                </button>
+                <button onClick={() => handleRemove(item.product.id)} className="btn-danger-ghost">
+                  Remove
+                </button>
               </div>
+            </div>
 
-              {expandedId === trackingProductId && (
-                <div className="border-t border-slate-100 p-5 dark:border-slate-800">
-                  {isDetailLoading ? (
-                    <div className="space-y-2">
-                      <div className="skeleton h-4 w-1/3" />
-                      <div className="skeleton h-[220px] w-full" />
-                    </div>
-                  ) : (
-                    <>
-                      {insights && (
-                        <div className="mb-4 flex flex-wrap items-center gap-3 text-sm">
-                          <span className={`badge ${RECOMMENDATION_BADGE_CLASS[insights.recommendation]}`}>
-                            {RECOMMENDATION_LABEL[insights.recommendation]}
-                          </span>
+            {expandedId === item.product.id && (
+              <div className="border-t border-slate-100 p-5 dark:border-slate-800">
+                {isDetailLoading ? (
+                  <div className="space-y-2">
+                    <div className="skeleton h-4 w-1/3" />
+                    <div className="skeleton h-[220px] w-full" />
+                  </div>
+                ) : (
+                  <>
+                    {insights && (
+                      <div className="mb-4 flex flex-wrap items-center gap-3 text-sm">
+                        <span className={`badge ${RECOMMENDATION_BADGE_CLASS[insights.recommendation]}`}>
+                          {RECOMMENDATION_LABEL[insights.recommendation]}
+                        </span>
+                        <span className="text-slate-500 dark:text-slate-400">
+                          Trend: {TREND_LABEL[insights.trend]}
+                        </span>
+                        {insights.lowest_price !== null && (
                           <span className="text-slate-500 dark:text-slate-400">
-                            Trend: {TREND_LABEL[insights.trend]}
+                            Lowest seen: {item.product.currency} {insights.lowest_price.toLocaleString()}
+                          </span>
+                        )}
+                      </div>
+                    )}
+
+                    {forecast && forecast.confidence !== "insufficient_data" && (
+                      <div className="mb-4 rounded-lg bg-brand-50 p-3 text-sm dark:bg-brand-900/20">
+                        <div className="mb-1 flex items-center gap-2">
+                          <span className="font-medium text-brand-700 dark:text-brand-300">
+                            7-day forecast
+                          </span>
+                          <span className={`badge ${CONFIDENCE_BADGE_CLASS[forecast.confidence]}`}>
+                            {forecast.confidence} confidence
                           </span>
-                          {insights.lowest_price !== null && (
-                            <span className="text-slate-500 dark:text-slate-400">
-                              Lowest seen: {currency} {insights.lowest_price.toLocaleString()}
-                            </span>
-                          )}
                         </div>
-                      )}
-
-                      {history && history.length > 1 ? (
-                        <Suspense fallback={<div className="skeleton h-[220px] w-full" />}>
-                          <PriceHistoryChart history={history} currency={currency} />
-                        </Suspense>
-                      ) : (
-                        <p className="text-sm text-slate-400">
-                          Not enough price history yet to plot a trend -- check back after a few
-                          more price checks.
-                        </p>
-                      )}
-                    </>
-                  )}
-                </div>
-              )}
-            </div>
-          );
-        })}
+                        <p className="text-slate-600 dark:text-slate-300">{forecast.explanation}</p>
+                      </div>
+                    )}
+
+                    {history.length > 1 ? (
+                      <Suspense
+                        fallback={<div className="skeleton h-[220px] w-full" />}
+                      >
+                        <PriceHistoryChart history={history} currency={item.product.currency} />
+                      </Suspense>
+                    ) : (
+                      <p className="text-sm text-slate-400">
+                        Not enough price history yet to plot a trend -- check back after a few
+                        more price checks.
+                      </p>
+                    )}
+                  </>
+                )}
+              </div>
+            )}
+          </div>
+        ))}
       </div>
     </div>
   );

frontend/src/types/index.ts

@@ -23,6 +23,11 @@ export interface PriceInsights {
   recommendation: "good_time_to_buy" | "wait" | "neutral";
 }
 
+export interface PriceForecast {
+  confidence: "high" | "moderate" | "low" | "insufficient_data";
+  explanation: string;
+}
+
 export interface UserOut {
   id: string;
   email: string;

services/analytics-service/app/api/v1/forecast.py

@@ -1,13 +1,18 @@
-from fastapi import APIRouter
-
-router = APIRouter(tags=["forecast"])
-
-@router.get("/forecast/{product_id}")
-async def get_product_forecast(product_id: str):
-    return {
-        "product_id": product_id,
-        "forecast_strategy": "baseline_linear_regression",
-        "trend": "stable",
-        "predicted_price_next_week": 0.0,
-        "message": "Forecasting engine placeholder initialized successfully."
-    }
+import uuid
+
+from fastapi import APIRouter, HTTPException, status
+
+from app.clients.tracking_client import TrackingServiceError
+from app.schemas.forecast import PriceForecast
+from app.services.forecast_service import ForecastService
+
+router = APIRouter(prefix="/analytics", tags=["analytics"])
+
+
+@router.get("/{product_id}/forecast", response_model=PriceForecast)
+async def get_price_forecast(product_id: uuid.UUID):
+    service = ForecastService()
+    try:
+        return await service.get_forecast(product_id)
+    except TrackingServiceError as exc:
+        raise HTTPException(status_code=status.HTTP_502_BAD_GATEWAY, detail=str(exc)) from exc

services/analytics-service/app/core/metrics.py

@@ -1,15 +1,13 @@
 from prometheus_client import Counter
 
-# 📈 Tracks the distribution of user buying advice to find threshold calibrations
 recommendations_total = Counter(
     "pricelens_analytics_recommendations_total",
     "Total buy recommendations issued, labeled by recommendation type",
-    ["recommendation"],  # Allowed labels: "good_time_to_buy", "wait", "neutral"
+    ["recommendation"],  # "good_time_to_buy", "wait", "neutral"
 )
 
-# 🔮 Tracks model reliability and data completeness thresholds
 forecasts_total = Counter(
     "pricelens_analytics_forecasts_total",
     "Total price forecasts generated, labeled by confidence level",
-    ["confidence"],  # Allowed labels: "high", "moderate", "low", "insufficient_data"
+    ["confidence"],  # "high", "moderate", "low", "insufficient_data"
 )

services/analytics-service/app/main.py

@@ -10,13 +10,18 @@
 from app.core.config import settings
 from app.core.logging_config import configure_logging, RequestIdMiddleware
 
+# Configure structured logging
 configure_logging()
 
-app = FastAPI(title=settings.app_name, debug=settings.debug)
+app = FastAPI(
+    title=settings.app_name, 
+    debug=settings.debug
+)
 
-# Use add_middleware for class-based BaseHTTPMiddleware definitions
+# Custom middleware for request tracing
 app.add_middleware(RequestIdMiddleware)
 
+# CORS configuration
 app.add_middleware(
     CORSMiddleware,
     allow_origins=settings.cors_allowed_origins,
@@ -25,13 +30,15 @@
     allow_headers=["*"],
 )
 
+# Registering routers
 app.include_router(health.router, prefix=settings.api_v1_prefix)
 app.include_router(analytics.router, prefix=settings.api_v1_prefix)
 app.include_router(forecast.router, prefix=settings.api_v1_prefix)
 
+# Prometheus instrumentation
 Instrumentator().instrument(app).expose(app, endpoint="/metrics", include_in_schema=False)
 
 
 @app.get("/")
 async def root() -> dict[str, str]:
-    return {"service": settings.app_name, "status": "running"}
+    return {"service": settings.app_name, "status": "running"}