From 35b64fcf7e87f48ddefbd23103287b00acd2c153 Mon Sep 17 00:00:00 2001
From: Paul Ochieng Levi <ochiengpaul442@gmail.com>
Date: Wed, 20 May 2026 00:02:48 +0300
Subject: [PATCH 1/8] Enhance Analytics components with error handling and
 loading states; update hooks for improved data fetching

---
 .../components/AnalyticsDashboard.tsx         |   7 +-
 .../analytics/components/QuickAccessCard.tsx  | 113 ++++++++++++------
 .../src/modules/analytics/hooks/index.ts      |  57 +++++++--
 .../src/modules/analytics/types/index.ts      |   2 +
 .../src/shared/hooks/usePreferences.ts        |   8 +-
 5 files changed, 132 insertions(+), 55 deletions(-)

diff --git a/src/platform/src/modules/analytics/components/AnalyticsDashboard.tsx b/src/platform/src/modules/analytics/components/AnalyticsDashboard.tsx
index ab030f58d3..e24344be16 100644
--- a/src/platform/src/modules/analytics/components/AnalyticsDashboard.tsx
+++ b/src/platform/src/modules/analytics/components/AnalyticsDashboard.tsx
@@ -112,6 +112,7 @@ export const AnalyticsDashboard: React.FC<AnalyticsDashboardProps> = ({
     siteCards,
     isLoading: siteCardsLoading,
     isRefreshing: siteCardsRefreshing,
+    error: siteCardsError,
     refetch: refreshSiteCards,
   } = useAnalyticsSiteCards({
     selectedSiteIds,
@@ -457,10 +458,12 @@ export const AnalyticsDashboard: React.FC<AnalyticsDashboardProps> = ({
         sites={siteCards}
         onManageFavorites={handleManageFavorites}
         onRefresh={handleRefreshDashboard}
-        isRefreshing={isRefreshing}
+        isRefreshing={siteCardsRefreshing || isRefreshing}
         selectedPollutant={filters.pollutant}
         onCardClick={handleCardClick}
-        isLoading={siteCardsLoading || siteCardsRefreshing || isRefreshing}
+        isLoading={siteCardsLoading}
+        placeholderCount={selectedSites.length}
+        hasError={Boolean(siteCardsError)}
         showIcon={showIcons}
         onShowIconsChange={setShowIcons}
         infoLine={
diff --git a/src/platform/src/modules/analytics/components/QuickAccessCard.tsx b/src/platform/src/modules/analytics/components/QuickAccessCard.tsx
index 3ad226eaa9..fa5df58e91 100644
--- a/src/platform/src/modules/analytics/components/QuickAccessCard.tsx
+++ b/src/platform/src/modules/analytics/components/QuickAccessCard.tsx
@@ -7,6 +7,7 @@ import { cn } from '@/shared/lib/utils';
 import type { QuickAccessLocationsProps } from '../types';
 import { AnalyticsCard } from './AnalyticsCard';
 import { LoadingSpinner } from '@/shared/components/ui/loading-spinner';
+import { WarningBanner } from '@/shared/components/ui';
 
 export const QuickAccessCard: React.FC<QuickAccessLocationsProps> = memo(
   ({
@@ -23,8 +24,18 @@ export const QuickAccessCard: React.FC<QuickAccessLocationsProps> = memo(
     onShowIconsChange,
     selectedPollutant,
     isLoading = false,
+    placeholderCount = 0,
+    hasError = false,
     onCardClick,
   }) => {
+    const visiblePlaceholderCount = Math.min(Math.max(placeholderCount, 1), 4);
+    const shouldShowSkeleton =
+      visiblePlaceholderCount > 0 &&
+      (isLoading || (hasError && sites.length === 0));
+    const shouldShowAddFavorite = shouldShowSkeleton
+      ? visiblePlaceholderCount < 4
+      : sites.length < 4;
+
     return (
       <div className={cn('w-full space-y-4', className)}>
         <PageHeading
@@ -45,50 +56,76 @@ export const QuickAccessCard: React.FC<QuickAccessLocationsProps> = memo(
           onShowIconsChange={onShowIconsChange}
         />
 
+        {isRefreshing && sites.length > 0 && !isLoading && (
+          <div className="flex justify-end">
+            <div className="inline-flex items-center gap-2 rounded-full border border-border bg-background px-3 py-1 text-xs text-muted-foreground shadow-sm">
+              <LoadingSpinner size={12} />
+              <span>Refreshing latest readings...</span>
+            </div>
+          </div>
+        )}
+
+        {hasError && (
+          <WarningBanner
+            dense={true}
+            title="Latest readings are temporarily unavailable"
+            message="Try Refresh again. Your saved favorites are still available."
+          />
+        )}
+
         {warningBanner && <div>{warningBanner}</div>}
 
         {/* Sites Grid */}
-        <div className="relative">
-          <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-4">
-            {/* Render site cards up to 4 to leave room for Add Location */}
-            {sites.slice(0, 4).map(site => (
-              <AnalyticsCard
-                key={site._id}
-                siteData={site}
-                className="w-full"
-                showIcon={showIcon}
-                selectedPollutant={selectedPollutant}
-                onClick={onCardClick || (() => {})}
-              />
-            ))}
-
-            {/* Show Add Location button if less than 4 sites */}
-            {sites.length < 4 && (
-              <button
-                onClick={() => {
-                  if (onManageFavorites) onManageFavorites();
-                }}
-                className="w-full h-[185px] border-2 border-dashed border-primary/50 dark:border-primary/80 rounded-md flex items-center justify-center text-primary bg-primary/10 dark:bg-primary/20 hover:bg-primary/20 dark:hover:bg-primary/30 hover:scale-95 transition-all duration-200 focus:outline-none"
-                aria-label="Add Location"
-              >
-                <div className="text-center">
-                  <div className="text-lg font-medium">+ Add Favorite</div>
-                </div>
-              </button>
-            )}
-          </div>
+        <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-4">
+          {shouldShowSkeleton
+            ? Array.from({ length: visiblePlaceholderCount }).map(
+                (_, index) => (
+                  <div
+                    key={`favorite-skeleton-${index}`}
+                    className="h-[185px] rounded-md border border-border bg-card p-4 shadow-sm"
+                    aria-hidden="true"
+                  >
+                    <div className="animate-pulse space-y-4">
+                      <div className="space-y-2">
+                        <div className="h-6 w-3/5 rounded bg-muted" />
+                        <div className="h-4 w-1/3 rounded bg-muted" />
+                      </div>
+                      <div className="flex items-center justify-between pt-8">
+                        <div className="space-y-3">
+                          <div className="h-5 w-8 rounded bg-muted" />
+                          <div className="h-8 w-20 rounded bg-muted" />
+                        </div>
+                        <div className="h-16 w-16 rounded-full bg-muted" />
+                      </div>
+                    </div>
+                  </div>
+                )
+              )
+            : sites
+                .slice(0, 4)
+                .map(site => (
+                  <AnalyticsCard
+                    key={site._id}
+                    siteData={site}
+                    className="w-full"
+                    showIcon={showIcon}
+                    selectedPollutant={selectedPollutant}
+                    onClick={onCardClick || (() => {})}
+                  />
+                ))}
 
-          {isLoading && (
-            <div
-              className="absolute inset-0 z-20 flex items-center justify-center rounded-md bg-background/80 backdrop-blur-sm"
-              role="status"
-              aria-live="polite"
+          {shouldShowAddFavorite && (
+            <button
+              onClick={() => {
+                if (onManageFavorites) onManageFavorites();
+              }}
+              className="w-full h-[185px] border-2 border-dashed border-primary/50 dark:border-primary/80 rounded-md flex items-center justify-center text-primary bg-primary/10 dark:bg-primary/20 hover:bg-primary/20 dark:hover:bg-primary/30 hover:scale-95 transition-all duration-200 focus:outline-none"
+              aria-label="Add Location"
             >
-              <div className="flex items-center gap-2 rounded-md border border-border bg-card px-3 py-2 text-sm text-muted-foreground shadow-sm">
-                <LoadingSpinner size={16} />
-                <span>Updating locations...</span>
+              <div className="text-center">
+                <div className="text-lg font-medium">+ Add Favorite</div>
               </div>
-            </div>
+            </button>
           )}
         </div>
       </div>
diff --git a/src/platform/src/modules/analytics/hooks/index.ts b/src/platform/src/modules/analytics/hooks/index.ts
index 1060fcd37f..d0b450318f 100644
--- a/src/platform/src/modules/analytics/hooks/index.ts
+++ b/src/platform/src/modules/analytics/hooks/index.ts
@@ -272,7 +272,7 @@ export const useAnalyticsSiteCards = ({
   enabled = true,
 }: AnalyticsSelections) => {
   const { filters } = useAnalytics();
-  const { user, activeGroup } = useUser();
+  const { activeGroup } = useUser();
   const selectedSiteIdsKey = useMemo(
     () => selectedSiteIds.join(','),
     [selectedSiteIds]
@@ -280,21 +280,25 @@ export const useAnalyticsSiteCards = ({
   const activeGroupKey = activeGroup?.id ?? 'no-active-group';
 
   const shouldFetch = enabled && selectedSiteIds.length > 0;
-
-  const query = useQuery<RecentReading[], Error>({
-    queryKey: [
+  const queryKey = useMemo(
+    () => [
       'analytics',
       'site-cards',
       activeGroupKey,
-      user?.id ?? 'anonymous',
       selectedSiteIdsKey,
       filters.pollutant,
     ],
+    [activeGroupKey, filters.pollutant, selectedSiteIdsKey]
+  );
+  const currentRequestKey = useMemo(() => JSON.stringify(queryKey), [queryKey]);
+  const lastSettledRequestKeyRef = useRef(currentRequestKey);
+
+  const query = useQuery<RecentReading[], Error>({
+    queryKey,
     queryFn: async ({ signal }) => {
       const response = await analyticsService.getRecentReadings(
         {
           site_id: selectedSiteIdsKey,
-          user_id: user?.id,
         },
         signal
       );
@@ -308,17 +312,40 @@ export const useAnalyticsSiteCards = ({
     refetchOnReconnect: false,
     staleTime: ANALYTICS_QUERY_STALE_TIME_MS,
     gcTime: ANALYTICS_QUERY_GC_TIME_MS,
-    placeholderData: previousData => previousData,
   });
 
+  useEffect(() => {
+    if (!shouldFetch) {
+      lastSettledRequestKeyRef.current = currentRequestKey;
+      return;
+    }
+
+    if (!query.isFetching && (query.isSuccess || query.isError)) {
+      lastSettledRequestKeyRef.current = currentRequestKey;
+    }
+  }, [
+    currentRequestKey,
+    query.isError,
+    query.isFetching,
+    query.isSuccess,
+    shouldFetch,
+  ]);
+
+  const isTransitionLoading =
+    shouldFetch &&
+    query.isFetching &&
+    currentRequestKey !== lastSettledRequestKeyRef.current;
+
   const measurementsBySiteId = useMemo(() => {
     return new Map<string, RecentReading>(
       (query.data ?? []).map(measurement => [measurement.site_id, measurement])
     );
   }, [query.data]);
 
+  const hasStableMeasurements = query.data !== undefined;
+
   const siteCards = useMemo(() => {
-    if (!shouldFetch) {
+    if (!shouldFetch || !hasStableMeasurements) {
       return [];
     }
 
@@ -335,7 +362,13 @@ export const useAnalyticsSiteCards = ({
 
       return buildNoValueSiteCard(selectedSite, filters.pollutant);
     });
-  }, [filters.pollutant, measurementsBySiteId, selectedSites, shouldFetch]);
+  }, [
+    filters.pollutant,
+    hasStableMeasurements,
+    measurementsBySiteId,
+    selectedSites,
+    shouldFetch,
+  ]);
 
   const refetchSiteCards = useCallback(async () => {
     if (!shouldFetch) {
@@ -347,8 +380,10 @@ export const useAnalyticsSiteCards = ({
 
   return {
     siteCards,
-    isLoading: shouldFetch ? query.isLoading : false,
-    isRefreshing: shouldFetch ? query.isFetching : false,
+    isLoading: shouldFetch ? query.isLoading || isTransitionLoading : false,
+    isRefreshing: shouldFetch
+      ? query.isFetching && !isTransitionLoading
+      : false,
     error: shouldFetch ? (query.error?.message ?? null) : null,
     refetch: refetchSiteCards,
   };
diff --git a/src/platform/src/modules/analytics/types/index.ts b/src/platform/src/modules/analytics/types/index.ts
index 702848e12d..c7dcb7cd8c 100644
--- a/src/platform/src/modules/analytics/types/index.ts
+++ b/src/platform/src/modules/analytics/types/index.ts
@@ -67,6 +67,8 @@ export interface QuickAccessLocationsProps {
   isRefreshing?: boolean;
   selectedPollutant?: PollutantType;
   isLoading?: boolean;
+  placeholderCount?: number;
+  hasError?: boolean;
   onCardClick?: (site: SiteData) => void;
 }
 
diff --git a/src/platform/src/shared/hooks/usePreferences.ts b/src/platform/src/shared/hooks/usePreferences.ts
index 8196c3766c..47289fe6e7 100644
--- a/src/platform/src/shared/hooks/usePreferences.ts
+++ b/src/platform/src/shared/hooks/usePreferences.ts
@@ -15,13 +15,13 @@ export const getLatestPreferenceForGroup = (
   preferences: UserPreference[] | null | undefined,
   groupId?: string
 ) => {
-  if (!preferences || preferences.length === 0) {
+  if (!preferences || preferences.length === 0 || !groupId) {
     return null;
   }
 
-  const scopedPreferences = groupId
-    ? preferences.filter(preference => preference.group_id === groupId)
-    : preferences;
+  const scopedPreferences = preferences.filter(
+    preference => preference.group_id === groupId
+  );
 
   if (scopedPreferences.length === 0) {
     return null;

From 164505d4144b534a5ef3f2b03615a3e9ecca4a1d Mon Sep 17 00:00:00 2001
From: Paul Ochieng Levi <ochiengpaul442@gmail.com>
Date: Wed, 20 May 2026 00:28:48 +0300
Subject: [PATCH 2/8] Add SelectedEmailCard component and integrate it into
 login forms; update analytics components for improved error handling

---
 .../(individual)/user/(auth)/login/page.tsx   |  23 +---
 .../org/[org_slug]/(auth)/login/page.tsx      |  23 +---
 .../components/AnalyticsDashboard.tsx         |   2 +-
 .../analytics/components/QuickAccessCard.tsx  | 110 ++++++++++--------
 .../src/modules/analytics/hooks/index.ts      |  14 ++-
 .../src/modules/analytics/types/index.ts      |   2 +-
 .../components/auth/SelectedEmailCard.tsx     |  56 +++++++++
 7 files changed, 132 insertions(+), 98 deletions(-)
 create mode 100644 src/platform/src/shared/components/auth/SelectedEmailCard.tsx

diff --git a/src/platform/src/app/(dashboard)/(individual)/user/(auth)/login/page.tsx b/src/platform/src/app/(dashboard)/(individual)/user/(auth)/login/page.tsx
index d7cee9cc73..9e14a176f8 100644
--- a/src/platform/src/app/(dashboard)/(individual)/user/(auth)/login/page.tsx
+++ b/src/platform/src/app/(dashboard)/(individual)/user/(auth)/login/page.tsx
@@ -3,6 +3,7 @@
 import { useEffect, useState, type FormEvent } from 'react';
 import AuthLayout from '@/shared/layouts/AuthLayout';
 import SocialAuthSection from '@/shared/components/auth/SocialAuthSection';
+import SelectedEmailCard from '@/shared/components/auth/SelectedEmailCard';
 import { signIn } from 'next-auth/react';
 import Link from 'next/link';
 import { useSearchParams } from 'next/navigation';
@@ -201,27 +202,7 @@ export default function LoginPage() {
         </form>
       ) : (
         <form onSubmit={handleSubmit(onSubmit)} className="w-full space-y-4">
-          <div className="rounded-xl border border-gray-200 bg-gray-50/80 px-3 py-3 shadow-sm dark:border-gray-700 dark:bg-gray-800/50 sm:px-4">
-            <div className="flex items-center justify-between gap-3">
-              <div className="min-w-0">
-                <p className="text-[10px] font-semibold uppercase tracking-[0.22em] text-gray-500 dark:text-gray-400">
-                  Account
-                </p>
-                <p className="mt-0.5 truncate text-sm font-medium text-gray-900 dark:text-white">
-                  {emailValue || 'your email address'}
-                </p>
-              </div>
-
-              <Button
-                type="button"
-                variant="text"
-                size="sm"
-                onClick={handleGoBack}
-              >
-                Change
-              </Button>
-            </div>
-          </div>
+          <SelectedEmailCard email={emailValue} onChangeEmail={handleGoBack} />
 
           <Input
             label="Password"
diff --git a/src/platform/src/app/(dashboard)/(organization)/org/[org_slug]/(auth)/login/page.tsx b/src/platform/src/app/(dashboard)/(organization)/org/[org_slug]/(auth)/login/page.tsx
index e78ac77a41..94de8bf2a8 100644
--- a/src/platform/src/app/(dashboard)/(organization)/org/[org_slug]/(auth)/login/page.tsx
+++ b/src/platform/src/app/(dashboard)/(organization)/org/[org_slug]/(auth)/login/page.tsx
@@ -4,6 +4,7 @@ import { useEffect, useState, type FormEvent } from 'react';
 import { useParams } from 'next/navigation';
 import AuthLayout from '@/shared/layouts/AuthLayout';
 import SocialAuthSection from '@/shared/components/auth/SocialAuthSection';
+import SelectedEmailCard from '@/shared/components/auth/SelectedEmailCard';
 import { signIn } from 'next-auth/react';
 import Link from 'next/link';
 import { useSearchParams } from 'next/navigation';
@@ -191,27 +192,7 @@ export default function OrgLoginPage() {
         </form>
       ) : (
         <form onSubmit={handleSubmit(onSubmit)} className="w-full space-y-4">
-          <div className="rounded-xl border border-gray-200 bg-gray-50/80 px-3 py-3 shadow-sm dark:border-gray-700 dark:bg-gray-800/50 sm:px-4">
-            <div className="flex items-center justify-between gap-3">
-              <div className="min-w-0">
-                <p className="text-[10px] font-semibold uppercase tracking-[0.22em] text-gray-500 dark:text-gray-400">
-                  Account
-                </p>
-                <p className="mt-0.5 truncate text-sm font-medium text-gray-900 dark:text-white">
-                  {emailValue || 'your email address'}
-                </p>
-              </div>
-
-              <Button
-                type="button"
-                variant="text"
-                size="sm"
-                onClick={handleGoBack}
-              >
-                Change
-              </Button>
-            </div>
-          </div>
+          <SelectedEmailCard email={emailValue} onChangeEmail={handleGoBack} />
 
           <Input
             label="Password"
diff --git a/src/platform/src/modules/analytics/components/AnalyticsDashboard.tsx b/src/platform/src/modules/analytics/components/AnalyticsDashboard.tsx
index e24344be16..ebd5b07549 100644
--- a/src/platform/src/modules/analytics/components/AnalyticsDashboard.tsx
+++ b/src/platform/src/modules/analytics/components/AnalyticsDashboard.tsx
@@ -463,7 +463,7 @@ export const AnalyticsDashboard: React.FC<AnalyticsDashboardProps> = ({
         onCardClick={handleCardClick}
         isLoading={siteCardsLoading}
         placeholderCount={selectedSites.length}
-        hasError={Boolean(siteCardsError)}
+        errorMessage={siteCardsError}
         showIcon={showIcons}
         onShowIconsChange={setShowIcons}
         infoLine={
diff --git a/src/platform/src/modules/analytics/components/QuickAccessCard.tsx b/src/platform/src/modules/analytics/components/QuickAccessCard.tsx
index fa5df58e91..e36f01debf 100644
--- a/src/platform/src/modules/analytics/components/QuickAccessCard.tsx
+++ b/src/platform/src/modules/analytics/components/QuickAccessCard.tsx
@@ -7,7 +7,7 @@ import { cn } from '@/shared/lib/utils';
 import type { QuickAccessLocationsProps } from '../types';
 import { AnalyticsCard } from './AnalyticsCard';
 import { LoadingSpinner } from '@/shared/components/ui/loading-spinner';
-import { WarningBanner } from '@/shared/components/ui';
+import { EmptyState } from '@/shared/components/ui';
 
 export const QuickAccessCard: React.FC<QuickAccessLocationsProps> = memo(
   ({
@@ -25,16 +25,14 @@ export const QuickAccessCard: React.FC<QuickAccessLocationsProps> = memo(
     selectedPollutant,
     isLoading = false,
     placeholderCount = 0,
-    hasError = false,
+    errorMessage = null,
     onCardClick,
   }) => {
     const visiblePlaceholderCount = Math.min(Math.max(placeholderCount, 1), 4);
-    const shouldShowSkeleton =
-      visiblePlaceholderCount > 0 &&
-      (isLoading || (hasError && sites.length === 0));
-    const shouldShowAddFavorite = shouldShowSkeleton
-      ? visiblePlaceholderCount < 4
-      : sites.length < 4;
+    const shouldShowSkeleton = visiblePlaceholderCount > 0 && isLoading;
+    const shouldShowErrorState = !isLoading && Boolean(errorMessage);
+    const shouldShowAddFavorite =
+      !shouldShowSkeleton && !shouldShowErrorState && sites.length < 4;
 
     return (
       <div className={cn('w-full space-y-4', className)}>
@@ -65,54 +63,66 @@ export const QuickAccessCard: React.FC<QuickAccessLocationsProps> = memo(
           </div>
         )}
 
-        {hasError && (
-          <WarningBanner
-            dense={true}
-            title="Latest readings are temporarily unavailable"
-            message="Try Refresh again. Your saved favorites are still available."
-          />
-        )}
-
         {warningBanner && <div>{warningBanner}</div>}
 
         {/* Sites Grid */}
         <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-4">
-          {shouldShowSkeleton
-            ? Array.from({ length: visiblePlaceholderCount }).map(
-                (_, index) => (
-                  <div
-                    key={`favorite-skeleton-${index}`}
-                    className="h-[185px] rounded-md border border-border bg-card p-4 shadow-sm"
-                    aria-hidden="true"
-                  >
-                    <div className="animate-pulse space-y-4">
-                      <div className="space-y-2">
-                        <div className="h-6 w-3/5 rounded bg-muted" />
-                        <div className="h-4 w-1/3 rounded bg-muted" />
-                      </div>
-                      <div className="flex items-center justify-between pt-8">
-                        <div className="space-y-3">
-                          <div className="h-5 w-8 rounded bg-muted" />
-                          <div className="h-8 w-20 rounded bg-muted" />
-                        </div>
-                        <div className="h-16 w-16 rounded-full bg-muted" />
-                      </div>
+          {shouldShowErrorState ? (
+            <div className="col-span-full">
+              <EmptyState
+                compact={true}
+                title="Latest readings could not be loaded"
+                description={
+                  errorMessage ||
+                  'Your favorites are saved. Refresh to try loading the latest readings again.'
+                }
+                action={
+                  onRefresh
+                    ? {
+                        label: 'Refresh',
+                        onClick: onRefresh,
+                        variant: 'outlined',
+                      }
+                    : undefined
+                }
+              />
+            </div>
+          ) : shouldShowSkeleton ? (
+            Array.from({ length: visiblePlaceholderCount }).map((_, index) => (
+              <div
+                key={`favorite-skeleton-${index}`}
+                className="h-[185px] rounded-md border border-border bg-card p-4 shadow-sm"
+                aria-hidden="true"
+              >
+                <div className="animate-pulse space-y-4">
+                  <div className="space-y-2">
+                    <div className="h-6 w-3/5 rounded bg-muted" />
+                    <div className="h-4 w-1/3 rounded bg-muted" />
+                  </div>
+                  <div className="flex items-center justify-between pt-8">
+                    <div className="space-y-3">
+                      <div className="h-5 w-8 rounded bg-muted" />
+                      <div className="h-8 w-20 rounded bg-muted" />
                     </div>
+                    <div className="h-16 w-16 rounded-full bg-muted" />
                   </div>
-                )
-              )
-            : sites
-                .slice(0, 4)
-                .map(site => (
-                  <AnalyticsCard
-                    key={site._id}
-                    siteData={site}
-                    className="w-full"
-                    showIcon={showIcon}
-                    selectedPollutant={selectedPollutant}
-                    onClick={onCardClick || (() => {})}
-                  />
-                ))}
+                </div>
+              </div>
+            ))
+          ) : (
+            sites
+              .slice(0, 4)
+              .map(site => (
+                <AnalyticsCard
+                  key={site._id}
+                  siteData={site}
+                  className="w-full"
+                  showIcon={showIcon}
+                  selectedPollutant={selectedPollutant}
+                  onClick={onCardClick || (() => {})}
+                />
+              ))
+          )}
 
           {shouldShowAddFavorite && (
             <button
diff --git a/src/platform/src/modules/analytics/hooks/index.ts b/src/platform/src/modules/analytics/hooks/index.ts
index d0b450318f..4bb3a9905a 100644
--- a/src/platform/src/modules/analytics/hooks/index.ts
+++ b/src/platform/src/modules/analytics/hooks/index.ts
@@ -115,8 +115,11 @@ export const useAnalyticsPreferences = (
   }, [currentPreference, preferencesLoading]);
 
   // Combined loading state - only show loading if we should fetch and are actually loading
+  const isWaitingForGroup = isEnabled && !resolvedGroupId;
   const isLoading =
-    userLoading || (shouldFetchPreferences && preferencesLoading);
+    userLoading ||
+    isWaitingForGroup ||
+    (shouldFetchPreferences && preferencesLoading);
 
   return {
     selectedSiteIds,
@@ -146,7 +149,7 @@ export const useAnalyticsChartData = (
   selectedSiteIds: string[] = EMPTY_SELECTED_SITE_IDS,
   enabled = true
 ) => {
-  const { activeGroup } = useUser();
+  const { user, activeGroup } = useUser();
 
   // Calculate date range based on filters
   const dateRange = useMemo(() => {
@@ -167,6 +170,7 @@ export const useAnalyticsChartData = (
     () => [
       'analytics',
       'chart-data',
+      user?.id ?? 'anonymous',
       activeGroupKey,
       chartType,
       selectedSiteIdsKey,
@@ -179,6 +183,7 @@ export const useAnalyticsChartData = (
       chartType,
       dateRange.endDate,
       dateRange.startDate,
+      user?.id,
       activeGroupKey,
       filters.frequency,
       filters.pollutant,
@@ -272,7 +277,7 @@ export const useAnalyticsSiteCards = ({
   enabled = true,
 }: AnalyticsSelections) => {
   const { filters } = useAnalytics();
-  const { activeGroup } = useUser();
+  const { user, activeGroup } = useUser();
   const selectedSiteIdsKey = useMemo(
     () => selectedSiteIds.join(','),
     [selectedSiteIds]
@@ -284,11 +289,12 @@ export const useAnalyticsSiteCards = ({
     () => [
       'analytics',
       'site-cards',
+      user?.id ?? 'anonymous',
       activeGroupKey,
       selectedSiteIdsKey,
       filters.pollutant,
     ],
-    [activeGroupKey, filters.pollutant, selectedSiteIdsKey]
+    [activeGroupKey, filters.pollutant, selectedSiteIdsKey, user?.id]
   );
   const currentRequestKey = useMemo(() => JSON.stringify(queryKey), [queryKey]);
   const lastSettledRequestKeyRef = useRef(currentRequestKey);
diff --git a/src/platform/src/modules/analytics/types/index.ts b/src/platform/src/modules/analytics/types/index.ts
index c7dcb7cd8c..1509d3d759 100644
--- a/src/platform/src/modules/analytics/types/index.ts
+++ b/src/platform/src/modules/analytics/types/index.ts
@@ -68,7 +68,7 @@ export interface QuickAccessLocationsProps {
   selectedPollutant?: PollutantType;
   isLoading?: boolean;
   placeholderCount?: number;
-  hasError?: boolean;
+  errorMessage?: string | null;
   onCardClick?: (site: SiteData) => void;
 }
 
diff --git a/src/platform/src/shared/components/auth/SelectedEmailCard.tsx b/src/platform/src/shared/components/auth/SelectedEmailCard.tsx
new file mode 100644
index 0000000000..f0ed16d5d9
--- /dev/null
+++ b/src/platform/src/shared/components/auth/SelectedEmailCard.tsx
@@ -0,0 +1,56 @@
+'use client';
+
+import React from 'react';
+import { Button } from '@/shared/components/ui';
+import { cn } from '@/shared/lib/utils';
+
+interface SelectedEmailCardProps {
+  email?: string;
+  onChangeEmail: () => void;
+  className?: string;
+  label?: string;
+  changeLabel?: string;
+}
+
+export default function SelectedEmailCard({
+  email,
+  onChangeEmail,
+  className,
+  label = 'Signing in as',
+  changeLabel = 'Change email',
+}: SelectedEmailCardProps) {
+  const displayEmail = email || 'your email address';
+
+  return (
+    <div
+      className={cn(
+        'rounded-xl border border-slate-200 bg-slate-50/90 px-4 py-3 shadow-sm dark:border-slate-700 dark:bg-slate-800/50 sm:px-5 sm:py-3',
+        className
+      )}
+    >
+      <div className="flex items-start justify-between gap-3 sm:items-center">
+        <div className="min-w-0 flex-1">
+          <div className="text-sm font-medium text-slate-600 dark:text-slate-400">
+            {label}
+          </div>
+          <div
+            className="mt-0.5 block truncate text-lg font-semibold text-slate-900 dark:text-white"
+            title={displayEmail}
+          >
+            {displayEmail}
+          </div>
+        </div>
+
+        <Button
+          type="button"
+          variant="outlined"
+          size="sm"
+          onClick={onChangeEmail}
+          className="h-9 shrink-0 rounded-lg border-blue-200 bg-white px-4 text-sm font-semibold text-blue-600 shadow-sm hover:border-blue-300 hover:bg-blue-50 hover:text-blue-700 dark:border-blue-500/40 dark:bg-slate-900 dark:text-blue-200 dark:hover:bg-slate-800"
+        >
+          {changeLabel}
+        </Button>
+      </div>
+    </div>
+  );
+}

From 116693551da41a2dc1d9ceaf4cdaa1ea09870514 Mon Sep 17 00:00:00 2001
From: Paul Ochieng Levi <ochiengpaul442@gmail.com>
Date: Wed, 20 May 2026 15:17:18 +0300
Subject: [PATCH 3/8] Refactor analytics hooks and components for improved data
 handling; enhance subscription management with mounted state checks; update
 chart components for better responsiveness and error handling; streamline
 user actions and service responses.

---
 .../src/modules/analytics/hooks/index.ts      | 146 ++++++++++----
 .../components/SubscriptionManagement.tsx     |  72 ++++---
 .../components/SubscriptionSection.tsx        |  24 ++-
 .../modules/billing/components/UsageStats.tsx |  29 ++-
 .../location-insights/more-insights.tsx       | 166 ++++++++++------
 .../charts/components/ChartContainer.tsx      |  38 ++--
 .../charts/components/charts/DynamicChart.tsx |  39 +++-
 .../src/shared/components/ui/wide-dialog.tsx  |   6 +
 .../src/shared/hooks/useUserActions.ts        |   8 +
 .../src/shared/services/deviceService.ts      | 187 ++++++++++++++----
 .../shared/services/subscriptionService.ts    |  19 +-
 11 files changed, 532 insertions(+), 202 deletions(-)

diff --git a/src/platform/src/modules/analytics/hooks/index.ts b/src/platform/src/modules/analytics/hooks/index.ts
index 4bb3a9905a..13b3dec1e7 100644
--- a/src/platform/src/modules/analytics/hooks/index.ts
+++ b/src/platform/src/modules/analytics/hooks/index.ts
@@ -9,7 +9,7 @@ import {
 } from '@/shared/hooks/usePreferences';
 import { useUser } from '@/shared/hooks/useUser';
 import { normalizeAirQualityData } from '@/shared/components/charts/utils';
-import { normalizeRecentReadingsToSiteData } from '../utils';
+import { generateTrend, getAirQualityLevel } from '../utils';
 import { useAnalytics } from './useAnalytics';
 import { analyticsService } from '@/shared/services/analyticsService';
 import type { SiteData, ChartData } from '../types';
@@ -17,7 +17,6 @@ import type {
   ChartDataPoint,
   DataDownloadRequest,
   Site,
-  RecentReading,
 } from '@/shared/types/api';
 import {
   buildDownloadFileContent,
@@ -34,6 +33,7 @@ const EMPTY_SELECTED_SITE_IDS: string[] = [];
 
 const ANALYTICS_QUERY_STALE_TIME_MS = 1000 * 60 * 5;
 const ANALYTICS_QUERY_GC_TIME_MS = 1000 * 60 * 60 * 12;
+const SITE_CARD_LOOKBACK_WINDOW_MS = 1000 * 60 * 60 * 24;
 
 const buildNoValueSiteCard = (
   selectedSite: Site,
@@ -55,6 +55,97 @@ const buildNoValueSiteCard = (
   percentageDifference: 0,
 });
 
+const buildSiteCardLocation = (selectedSite: Site) => {
+  return (
+    [selectedSite.city, selectedSite.region, selectedSite.country]
+      .filter(Boolean)
+      .join(', ') ||
+    selectedSite.country ||
+    'Unknown Country'
+  );
+};
+
+const createLatestSiteCardDateRange = () => {
+  const endDate = new Date();
+  const startDate = new Date(endDate.getTime() - SITE_CARD_LOOKBACK_WINDOW_MS);
+
+  return {
+    startDate: startDate.toISOString(),
+    endDate: endDate.toISOString(),
+  };
+};
+
+const buildSiteCardsFromChartPoints = (
+  chartPoints: ChartDataPoint[],
+  selectedSites: Site[],
+  pollutant: string
+): SiteData[] => {
+  if (!Array.isArray(chartPoints) || chartPoints.length === 0) {
+    return selectedSites.map(selectedSite =>
+      buildNoValueSiteCard(selectedSite, pollutant)
+    );
+  }
+
+  const pointsBySiteId = new Map<string, ChartDataPoint[]>();
+
+  chartPoints.forEach(point => {
+    if (!point?.site_id) {
+      return;
+    }
+
+    const sitePoints = pointsBySiteId.get(point.site_id) ?? [];
+    sitePoints.push(point);
+    pointsBySiteId.set(point.site_id, sitePoints);
+  });
+
+  return selectedSites.map(selectedSite => {
+    const sortedPoints = [...(pointsBySiteId.get(selectedSite._id) ?? [])].sort(
+      (left, right) =>
+        new Date(right.time).getTime() - new Date(left.time).getTime()
+    );
+    const latestPoint = sortedPoints[0];
+    const previousPoint = sortedPoints[1];
+    const latestValue = Number(latestPoint?.value);
+    const previousValue = Number(previousPoint?.value);
+
+    if (!latestPoint || !Number.isFinite(latestValue)) {
+      return buildNoValueSiteCard(selectedSite, pollutant);
+    }
+
+    const percentageDifference =
+      Number.isFinite(previousValue) && previousValue !== 0
+        ? ((latestValue - previousValue) / Math.abs(previousValue)) * 100
+        : 0;
+
+    return {
+      _id: selectedSite._id,
+      name:
+        selectedSite.search_name ||
+        selectedSite.name ||
+        selectedSite.formatted_name ||
+        selectedSite.generated_name ||
+        latestPoint.name ||
+        latestPoint.generated_name ||
+        'Unknown Site',
+      search_name:
+        selectedSite.search_name ||
+        selectedSite.name ||
+        latestPoint.name ||
+        latestPoint.generated_name,
+      location: buildSiteCardLocation(selectedSite),
+      country: selectedSite.country,
+      city: selectedSite.city,
+      region: selectedSite.region,
+      value: latestValue,
+      status: getAirQualityLevel(latestValue, pollutant),
+      pollutant,
+      unit: 'μg/m³',
+      trend: generateTrend(latestValue, previousValue),
+      percentageDifference,
+    };
+  });
+};
+
 interface AnalyticsPreferencesOptions {
   groupId?: string;
   userId?: string;
@@ -299,17 +390,28 @@ export const useAnalyticsSiteCards = ({
   const currentRequestKey = useMemo(() => JSON.stringify(queryKey), [queryKey]);
   const lastSettledRequestKeyRef = useRef(currentRequestKey);
 
-  const query = useQuery<RecentReading[], Error>({
+  const query = useQuery<SiteData[], Error>({
     queryKey,
     queryFn: async ({ signal }) => {
-      const response = await analyticsService.getRecentReadings(
+      const latestDateRange = createLatestSiteCardDateRange();
+      const response = await analyticsService.getChartData(
         {
-          site_id: selectedSiteIdsKey,
+          sites: selectedSiteIds,
+          startDate: latestDateRange.startDate,
+          endDate: latestDateRange.endDate,
+          chartType: 'line',
+          frequency: 'hourly',
+          pollutant: filters.pollutant.toLowerCase().replace('.', '_'),
+          organisation_name: '',
         },
         signal
       );
 
-      return response?.measurements ?? [];
+      return buildSiteCardsFromChartPoints(
+        response?.data ?? [],
+        selectedSites,
+        filters.pollutant
+      );
     },
     enabled: shouldFetch,
     networkMode: 'online',
@@ -342,39 +444,13 @@ export const useAnalyticsSiteCards = ({
     query.isFetching &&
     currentRequestKey !== lastSettledRequestKeyRef.current;
 
-  const measurementsBySiteId = useMemo(() => {
-    return new Map<string, RecentReading>(
-      (query.data ?? []).map(measurement => [measurement.site_id, measurement])
-    );
-  }, [query.data]);
-
-  const hasStableMeasurements = query.data !== undefined;
-
   const siteCards = useMemo(() => {
-    if (!shouldFetch || !hasStableMeasurements) {
+    if (!shouldFetch) {
       return [];
     }
 
-    return selectedSites.map(selectedSite => {
-      const measurement = measurementsBySiteId.get(selectedSite._id);
-
-      if (measurement) {
-        const normalized = normalizeRecentReadingsToSiteData(
-          [measurement],
-          filters.pollutant as 'pm2_5' | 'pm10'
-        );
-        return normalized[0];
-      }
-
-      return buildNoValueSiteCard(selectedSite, filters.pollutant);
-    });
-  }, [
-    filters.pollutant,
-    hasStableMeasurements,
-    measurementsBySiteId,
-    selectedSites,
-    shouldFetch,
-  ]);
+    return query.data ?? [];
+  }, [query.data, shouldFetch]);
 
   const refetchSiteCards = useCallback(async () => {
     if (!shouldFetch) {
diff --git a/src/platform/src/modules/billing/components/SubscriptionManagement.tsx b/src/platform/src/modules/billing/components/SubscriptionManagement.tsx
index d396c33e62..5b5e69c86e 100644
--- a/src/platform/src/modules/billing/components/SubscriptionManagement.tsx
+++ b/src/platform/src/modules/billing/components/SubscriptionManagement.tsx
@@ -17,39 +17,53 @@ const SubscriptionManagement: React.FC = () => {
   const [cancelling, setCancelling] = useState(false);
 
   useEffect(() => {
-    fetchSubscription();
-  }, []);
+    let isMounted = true;
 
-  const fetchSubscription = async () => {
-    try {
-      setLoading(true);
-      const data = await subscriptionService.getSubscription();
+    const fetchSubscription = async () => {
+      try {
+        setLoading(true);
+        const data = await subscriptionService.getSubscription();
 
-      if (data.success) {
-        const subscription = data.subscription || null;
-        const normalizedSubscription = subscription
-          ? {
-              ...subscription,
-              automaticRenewal:
-                subscription.automaticRenewal ??
-                subscription.autoRenewal ??
-                false,
-              autoRenewal:
-                subscription.autoRenewal ??
-                subscription.automaticRenewal ??
-                false,
-            }
-          : null;
+        if (!isMounted) {
+          return;
+        }
 
-        setSubscription(normalizedSubscription);
+        if (data.success) {
+          const subscription = data.subscription || null;
+          const normalizedSubscription = subscription
+            ? {
+                ...subscription,
+                automaticRenewal:
+                  subscription.automaticRenewal ??
+                  subscription.autoRenewal ??
+                  false,
+                autoRenewal:
+                  subscription.autoRenewal ??
+                  subscription.automaticRenewal ??
+                  false,
+              }
+            : null;
+
+          setSubscription(normalizedSubscription);
+        }
+      } catch (error) {
+        if (isMounted) {
+          console.error('Error fetching subscription:', error);
+          toast.error('Failed to load subscription information');
+        }
+      } finally {
+        if (isMounted) {
+          setLoading(false);
+        }
       }
-    } catch (error) {
-      console.error('Error fetching subscription:', error);
-      toast.error('Failed to load subscription information');
-    } finally {
-      setLoading(false);
-    }
-  };
+    };
+
+    void fetchSubscription();
+
+    return () => {
+      isMounted = false;
+    };
+  }, []);
 
   const handleToggleAutoRenewal = async () => {
     if (!subscription) return;
diff --git a/src/platform/src/modules/billing/components/SubscriptionSection.tsx b/src/platform/src/modules/billing/components/SubscriptionSection.tsx
index 96e59803d8..4b793b7eab 100644
--- a/src/platform/src/modules/billing/components/SubscriptionSection.tsx
+++ b/src/platform/src/modules/billing/components/SubscriptionSection.tsx
@@ -1,6 +1,12 @@
 'use client';
 
-import React, { useCallback, useEffect, useMemo, useState } from 'react';
+import React, {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
 import { AqCheck } from '@airqo/icons-react';
 import { Button, Card, LoadingSpinner, toast } from '@/shared/components/ui';
 import { formatDate } from '@/shared/utils';
@@ -72,6 +78,7 @@ const SubscriptionSection: React.FC = () => {
   const [runningAction, setRunningAction] = useState<
     'checkout' | 'enableAutoRenew' | 'disableAutoRenew' | 'cancel' | null
   >(null);
+  const isMountedRef = useRef(true);
 
   const currentTier: SubscriptionTier = subscription?.tier || 'Free';
   const currentStatus = subscription?.status || 'inactive';
@@ -85,6 +92,10 @@ const SubscriptionSection: React.FC = () => {
         subscriptionService.getPlans(),
       ]);
 
+      if (!isMountedRef.current) {
+        return;
+      }
+
       setSubscription(
         subscriptionResponse.success
           ? (subscriptionResponse.subscription ?? null)
@@ -102,12 +113,19 @@ const SubscriptionSection: React.FC = () => {
       );
       toast.error('Failed to load subscription data');
     } finally {
-      setLoading(false);
+      if (isMountedRef.current) {
+        setLoading(false);
+      }
     }
   }, []);
 
   useEffect(() => {
-    refreshData();
+    isMountedRef.current = true;
+    void refreshData();
+
+    return () => {
+      isMountedRef.current = false;
+    };
   }, [refreshData]);
 
   const currentPlan = useMemo(
diff --git a/src/platform/src/modules/billing/components/UsageStats.tsx b/src/platform/src/modules/billing/components/UsageStats.tsx
index d72754b541..089eea2785 100644
--- a/src/platform/src/modules/billing/components/UsageStats.tsx
+++ b/src/platform/src/modules/billing/components/UsageStats.tsx
@@ -29,24 +29,43 @@ const UsageStats: React.FC = () => {
   const [currentTime, setCurrentTime] = useState(() => Date.now());
 
   useEffect(() => {
+    let isActive = true;
+
     const fetchUsage = async () => {
       try {
         const data = await subscriptionService.getUsage();
+        if (!isActive) {
+          return;
+        }
+
         if (data.success) {
           setUsage(data.usage || null);
           setLiveUsage(data.live ?? true);
           setUsageMessage(data.message || '');
         }
       } catch (error) {
-        console.error('Error fetching usage stats:', error);
+        if (isActive) {
+          console.error('Error fetching usage stats:', error);
+        }
       } finally {
-        setLoading(false);
+        if (isActive) {
+          setLoading(false);
+        }
       }
     };
 
-    fetchUsage();
-    const interval = setInterval(fetchUsage, 5 * 60 * 1000);
-    return () => clearInterval(interval);
+    void fetchUsage();
+    const interval = setInterval(
+      () => {
+        void fetchUsage();
+      },
+      5 * 60 * 1000
+    );
+
+    return () => {
+      isActive = false;
+      clearInterval(interval);
+    };
   }, []);
 
   useEffect(() => {
diff --git a/src/platform/src/modules/location-insights/more-insights.tsx b/src/platform/src/modules/location-insights/more-insights.tsx
index 2b801d5cec..7f953b9348 100644
--- a/src/platform/src/modules/location-insights/more-insights.tsx
+++ b/src/platform/src/modules/location-insights/more-insights.tsx
@@ -59,7 +59,7 @@ export const MoreInsights: React.FC<MoreInsightsProps> = ({ activeTab }) => {
   const isOpen = useSelector(selectIsDialogOpen('more-insights'));
 
   // Get user data for personalized banner dismissal
-  const { user } = useUser();
+  const { user, activeGroup } = useUser();
 
   // Initialize default date range to last 7 days
   const getDefaultDateRange = () => {
@@ -104,6 +104,18 @@ export const MoreInsights: React.FC<MoreInsightsProps> = ({ activeTab }) => {
   const visibleSiteIds = useMemo(() => {
     return Array.from(visibleSites);
   }, [visibleSites]);
+  const dialogContextKey = useMemo(
+    () =>
+      [
+        activeGroup?.id || 'no-active-group',
+        activeTab || 'sites',
+        selectedSites
+          .map((site: SelectedSite) => site._id)
+          .sort()
+          .join(','),
+      ].join('::'),
+    [activeGroup?.id, activeTab, selectedSites]
+  );
 
   // Chart data hook - create a per-params SWR key to avoid cross-talk between
   // multiple chart instances elsewhere in the app.
@@ -186,79 +198,115 @@ export const MoreInsights: React.FC<MoreInsightsProps> = ({ activeTab }) => {
   // Chart data state
   const [chartData, setChartData] = useState<ChartData[]>([]);
 
-  // Fetch chart data when filters or visible sites change
-  const fetchChartData = useCallback(async () => {
-    // Only fetch if we have visible sites and a date range
-    if (visibleSiteIds.length === 0 || !dateRange?.from || !dateRange?.to) {
+  // Fetch data when dependencies change and ignore stale responses when the
+  // dialog closes or a different site/group context replaces the current one.
+  useEffect(() => {
+    let isActive = true;
+
+    if (
+      !isOpen ||
+      visibleSiteIds.length === 0 ||
+      !dateRange?.from ||
+      !dateRange?.to
+    ) {
       setChartData([]);
-      return;
+      return () => {
+        isActive = false;
+      };
     }
 
-    try {
-      const response = await getChartData({
-        sites: visibleSiteIds,
-        startDate: dateRange.from.toISOString().split('T')[0],
-        endDate: dateRange.to.toISOString().split('T')[0],
-        chartType: chartType,
-        frequency: frequency,
-        pollutant: pollutant.toLowerCase().replace('.', '_'),
-        organisation_name: '',
-      });
-
-      if (
-        response?.data &&
-        Array.isArray(response.data) &&
-        response.data.length > 0
-      ) {
-        // Transform API data to chart format
-        const transformed = normalizeAirQualityData(
-          response.data as ChartDataPoint[]
-        );
-        setChartData(transformed);
-      } else {
+    setChartData([]);
+
+    const run = async () => {
+      try {
+        const response = await getChartData({
+          sites: visibleSiteIds,
+          startDate: dateRange.from.toISOString().split('T')[0],
+          endDate: dateRange.to.toISOString().split('T')[0],
+          chartType: chartType,
+          frequency: frequency,
+          pollutant: pollutant.toLowerCase().replace('.', '_'),
+          organisation_name: '',
+        });
+
+        if (!isActive) {
+          return;
+        }
+
+        if (
+          response?.data &&
+          Array.isArray(response.data) &&
+          response.data.length > 0
+        ) {
+          const transformed = normalizeAirQualityData(
+            response.data as ChartDataPoint[]
+          );
+          setChartData(transformed);
+          return;
+        }
+
+        setChartData([]);
+      } catch (error) {
+        if (!isActive) {
+          return;
+        }
+
+        console.error('Error fetching chart data:', error);
         setChartData([]);
       }
-    } catch (error) {
-      console.error('Error fetching chart data:', error);
-      setChartData([]);
-    }
+    };
+
+    run();
+
+    return () => {
+      isActive = false;
+    };
   }, [
-    visibleSiteIds,
-    dateRange?.from,
-    dateRange?.to,
     chartType,
+    dateRange,
     frequency,
-    pollutant,
     getChartData,
+    isOpen,
+    pollutant,
+    visibleSiteIds,
   ]);
 
-  // Fetch data when dependencies change
-  useEffect(() => {
-    fetchChartData();
-  }, [fetchChartData]);
-
   // Initialize visible sites when selectedSites changes or dialog opens
   React.useEffect(() => {
-    if (isOpen && selectedSites.length > 0) {
-      // Smart initial selection: show only first N sites to avoid chart clutter
-      const initialVisibleCount = Math.min(
-        INITIAL_VISIBLE_SITES,
-        selectedSites.length
+    if (!isOpen) {
+      setChartData([]);
+      setVisibleSites(new Set());
+      setSearchQuery('');
+      return;
+    }
+
+    if (selectedSites.length === 0) {
+      setChartData([]);
+      setVisibleSites(new Set());
+      setSearchQuery('');
+      return;
+    }
+
+    // Smart initial selection: show only first N sites to avoid chart clutter
+    const initialVisibleCount = Math.min(
+      INITIAL_VISIBLE_SITES,
+      selectedSites.length
+    );
+    const initialVisibleSites = selectedSites
+      .slice(0, initialVisibleCount)
+      .map((site: SelectedSite) => site._id);
+    setVisibleSites(new Set(initialVisibleSites));
+    setSearchQuery('');
+    setChartData([]);
+
+    // Show toast notification if there are more sites available
+    if (selectedSites.length > INITIAL_VISIBLE_SITES) {
+      toast.info(
+        'Chart Optimized',
+        `Showing ${initialVisibleCount} of ${selectedSites.length} selected sites on chart. Use the sidebar to add more sites for comparison.`
       );
-      const initialVisibleSites = selectedSites
-        .slice(0, initialVisibleCount)
-        .map((site: SelectedSite) => site._id);
-      setVisibleSites(new Set(initialVisibleSites));
-
-      // Show toast notification if there are more sites available
-      if (selectedSites.length > INITIAL_VISIBLE_SITES) {
-        toast.info(
-          'Chart Optimized',
-          `Showing ${initialVisibleCount} of ${selectedSites.length} selected sites on chart. Use the sidebar to add more sites for comparison.`
-        );
-      }
     }
-  }, [selectedSites, isOpen]);
+  }, [dialogContextKey, isOpen, selectedSites]);
 
   // Handle site visibility toggle (for chart display)
   const handleSiteVisibilityToggle = (siteId: string) => {
diff --git a/src/platform/src/shared/components/charts/components/ChartContainer.tsx b/src/platform/src/shared/components/charts/components/ChartContainer.tsx
index 0d8a21a690..6edb4a2485 100644
--- a/src/platform/src/shared/components/charts/components/ChartContainer.tsx
+++ b/src/platform/src/shared/components/charts/components/ChartContainer.tsx
@@ -340,8 +340,14 @@ export const ChartContainer: React.FC<ChartContainerProps> = ({
         />
       )}
 
-      <CardContent ref={exportRef} className="pl-1 pb-2 flex-1">
-        <div className="relative w-full h-full flex justify-center items-center min-h-[400px]">
+      <CardContent
+        ref={exportRef}
+        className={cn(
+          'px-1 pb-2 flex-1',
+          !showTitle && !showMoreButton && 'pt-3'
+        )}
+      >
+        <div className="relative w-full min-h-[400px] min-w-0">
           {error && (
             <div className="flex items-center justify-center h-64 text-destructive">
               <div className="text-center">
@@ -359,18 +365,22 @@ export const ChartContainer: React.FC<ChartContainerProps> = ({
             </div>
           )}
 
-          {!error && React.isValidElement(children)
-            ? React.cloneElement(
-                children as React.ReactElement<{
-                  showReferenceLines?: boolean;
-                  standards?: string;
-                }>,
-                {
-                  showReferenceLines,
-                  standards: currentStandardsOrg,
-                }
-              )
-            : !error && children}
+          {!error && (
+            <div className="w-full h-full min-h-[400px] min-w-0">
+              {React.isValidElement(children)
+                ? React.cloneElement(
+                    children as React.ReactElement<{
+                      showReferenceLines?: boolean;
+                      standards?: string;
+                    }>,
+                    {
+                      showReferenceLines,
+                      standards: currentStandardsOrg,
+                    }
+                  )
+                : children}
+            </div>
+          )}
 
           {loading && !error && (
             <div
diff --git a/src/platform/src/shared/components/charts/components/charts/DynamicChart.tsx b/src/platform/src/shared/components/charts/components/charts/DynamicChart.tsx
index f719ed236a..8c08468acf 100644
--- a/src/platform/src/shared/components/charts/components/charts/DynamicChart.tsx
+++ b/src/platform/src/shared/components/charts/components/charts/DynamicChart.tsx
@@ -165,10 +165,38 @@ export const DynamicChart: React.FC<DynamicChartProps> = ({
     ...config,
   };
 
+  const resolvedMargin = useMemo(() => {
+    const margin = {
+      ...DEFAULT_CHART_CONFIG.margin,
+      ...chartConfig.margin,
+    };
+
+    return {
+      ...margin,
+      right: Math.max(margin.right ?? 0, 16),
+    };
+  }, [chartConfig.margin]);
+
+  const xAxisPadding = useMemo(() => {
+    if (chartType === 'bar') {
+      return { left: 8, right: 20 };
+    }
+
+    if (
+      chartType === 'line' ||
+      chartType === 'area' ||
+      chartType === 'scatter'
+    ) {
+      return { left: 4, right: 16 };
+    }
+
+    return { left: 0, right: 0 };
+  }, [chartType]);
+
   // Common props for all charts
   const commonProps = {
     data: chartData as unknown as NormalizedChartData[],
-    margin: chartConfig.margin,
+    margin: resolvedMargin,
     ...CHART_ANIMATIONS[chartType as keyof typeof CHART_ANIMATIONS],
   };
 
@@ -187,6 +215,8 @@ export const DynamicChart: React.FC<DynamicChartProps> = ({
   const renderXAxis = () => (
     <XAxis
       dataKey={config.xAxisKey || 'time'}
+      padding={xAxisPadding}
+      interval="preserveStartEnd"
       tick={AXIS_CONFIG.tick}
       tickLine={AXIS_CONFIG.tickLine}
       axisLine={AXIS_CONFIG.axisLine}
@@ -483,12 +513,7 @@ export const DynamicChart: React.FC<DynamicChartProps> = ({
   if (!chart) return null;
 
   return (
-    <div
-      className={cn(
-        'w-full flex justify-center items-center min-h-[300px] min-w-0',
-        className
-      )}
-    >
+    <div className={cn('w-full min-h-[300px] min-w-0', className)}>
       <Container {...containerProps}>{chart}</Container>
     </div>
   );
diff --git a/src/platform/src/shared/components/ui/wide-dialog.tsx b/src/platform/src/shared/components/ui/wide-dialog.tsx
index c108de572c..2e857eb0ad 100644
--- a/src/platform/src/shared/components/ui/wide-dialog.tsx
+++ b/src/platform/src/shared/components/ui/wide-dialog.tsx
@@ -96,6 +96,12 @@ const WideDialog: React.FC<WideDialogProps> = ({
     };
   }, [isOpen]);
 
+  useEffect(() => {
+    if (!isOpen) {
+      setSidebarOpen(false);
+    }
+  }, [isOpen]);
+
   // close on escape
   useEffect(() => {
     const onKey = (e: KeyboardEvent) => {
diff --git a/src/platform/src/shared/hooks/useUserActions.ts b/src/platform/src/shared/hooks/useUserActions.ts
index 5d8ebcf326..698aa7d1ab 100644
--- a/src/platform/src/shared/hooks/useUserActions.ts
+++ b/src/platform/src/shared/hooks/useUserActions.ts
@@ -4,6 +4,10 @@ import { useSWRConfig } from 'swr';
 import { usePostHog } from 'posthog-js/react';
 import { useQueryClient } from '@tanstack/react-query';
 import { setActiveGroup, setActiveGroupById } from '@/shared/store/userSlice';
+import {
+  clearSelectedSites,
+  closeAllDialogs,
+} from '@/shared/store/insightsSlice';
 import { useUser } from './useUser';
 import { useLogout } from './useLogout';
 import type { NormalizedGroup } from '@/shared/utils/userUtils';
@@ -165,6 +169,8 @@ export const useUserActions = () => {
 
       // Switch to new group
       dispatch(setActiveGroup(group));
+      dispatch(closeAllDialogs());
+      dispatch(clearSelectedSites());
 
       invalidateGroupScopedCache(previousGroupId, group.id);
     },
@@ -197,6 +203,8 @@ export const useUserActions = () => {
           toGroupId: groupId,
         });
         dispatch(setActiveGroupById(groupId));
+        dispatch(closeAllDialogs());
+        dispatch(clearSelectedSites());
         invalidateGroupScopedCache(previousGroupId, groupId);
       }
     },
diff --git a/src/platform/src/shared/services/deviceService.ts b/src/platform/src/shared/services/deviceService.ts
index 2b9e4fb01c..2cd2c83cc7 100644
--- a/src/platform/src/shared/services/deviceService.ts
+++ b/src/platform/src/shared/services/deviceService.ts
@@ -47,6 +47,55 @@ type LegacyCohortDevicesResponse = {
   cache_generated_at?: string;
 } & LegacyCohortPagination;
 
+type ApiEnvelope = {
+  success?: boolean;
+  message?: string;
+  data?: unknown;
+};
+
+const extractEnvelopeData = <T>(payload: unknown): T | null => {
+  if (!payload || typeof payload !== 'object') {
+    return null;
+  }
+
+  const envelope = payload as ApiEnvelope;
+  const data = envelope.data === undefined ? payload : envelope.data;
+
+  return data as T;
+};
+
+const extractGroupCohortIds = (payload: unknown): string[] => {
+  const unwrapped = extractEnvelopeData<unknown>(payload);
+
+  if (Array.isArray(unwrapped)) {
+    return unwrapped.filter(
+      (cohortId): cohortId is string => typeof cohortId === 'string'
+    );
+  }
+
+  if (
+    unwrapped &&
+    typeof unwrapped === 'object' &&
+    Array.isArray((unwrapped as { data?: unknown }).data)
+  ) {
+    return (unwrapped as { data: unknown[] }).data.filter(
+      (cohortId): cohortId is string => typeof cohortId === 'string'
+    );
+  }
+
+  if (
+    payload &&
+    typeof payload === 'object' &&
+    Array.isArray((payload as { data?: unknown }).data)
+  ) {
+    return (payload as { data: unknown[] }).data.filter(
+      (cohortId): cohortId is string => typeof cohortId === 'string'
+    );
+  }
+
+  return [];
+};
+
 const isAbortLikeError = (error: unknown): boolean => {
   const candidate = error as {
     name?: string;
@@ -108,17 +157,36 @@ const normalizeLegacyMeta = (
 };
 
 const normalizeSitesResponse = (
-  response: CohortSitesResponse | LegacyCohortSitesResponse
+  response: CohortSitesResponse | LegacyCohortSitesResponse,
+  envelope?: ApiEnvelope
 ): CohortSitesResponse => {
   if ('meta' in response) {
-    return response;
+    return {
+      ...response,
+      success:
+        typeof envelope?.success === 'boolean'
+          ? envelope.success
+          : response.success,
+      message:
+        typeof envelope?.message === 'string' && envelope.message.trim()
+          ? envelope.message
+          : response.message,
+    };
   }
 
+  const sites = response.sites ?? [];
+
   return {
-    success: response.success,
-    message: response.message,
-    meta: normalizeLegacyMeta(response, response.sites?.length ?? 0),
-    sites: response.sites ?? [],
+    success:
+      typeof envelope?.success === 'boolean'
+        ? envelope.success
+        : response.success,
+    message:
+      typeof envelope?.message === 'string' && envelope.message.trim()
+        ? envelope.message
+        : response.message,
+    meta: normalizeLegacyMeta(response, sites.length),
+    sites,
     ...(response.cache_generated_at
       ? { cache_generated_at: response.cache_generated_at }
       : {}),
@@ -126,17 +194,36 @@ const normalizeSitesResponse = (
 };
 
 const normalizeDevicesResponse = (
-  response: CohortDevicesResponse | LegacyCohortDevicesResponse
+  response: CohortDevicesResponse | LegacyCohortDevicesResponse,
+  envelope?: ApiEnvelope
 ): CohortDevicesResponse => {
   if ('meta' in response) {
-    return response;
+    return {
+      ...response,
+      success:
+        typeof envelope?.success === 'boolean'
+          ? envelope.success
+          : response.success,
+      message:
+        typeof envelope?.message === 'string' && envelope.message.trim()
+          ? envelope.message
+          : response.message,
+    };
   }
 
+  const devices = response.devices ?? [];
+
   return {
-    success: response.success,
-    message: response.message,
-    meta: normalizeLegacyMeta(response, response.devices?.length ?? 0),
-    devices: response.devices ?? [],
+    success:
+      typeof envelope?.success === 'boolean'
+        ? envelope.success
+        : response.success,
+    message:
+      typeof envelope?.message === 'string' && envelope.message.trim()
+        ? envelope.message
+        : response.message,
+    meta: normalizeLegacyMeta(response, devices.length),
+    devices,
     ...(response.cache_generated_at
       ? { cache_generated_at: response.cache_generated_at }
       : {}),
@@ -223,15 +310,18 @@ export class DeviceService {
       signal,
       suppressErrorLogging: true,
     });
-    const data = response.data;
+    const responsePayload = response.data;
 
-    if ('success' in data && !data.success) {
-      throw new Error(data.message || 'Failed to get cohort sites');
+    if ('success' in responsePayload && !responsePayload.success) {
+      throw new Error(responsePayload.message || 'Failed to get cohort sites');
     }
 
-    return normalizeSitesResponse(
-      data as CohortSitesResponse | LegacyCohortSitesResponse
-    );
+    const unwrapped =
+      extractEnvelopeData<CohortSitesResponse | LegacyCohortSitesResponse>(
+        responsePayload
+      ) || (responsePayload as CohortSitesResponse | LegacyCohortSitesResponse);
+
+    return normalizeSitesResponse(unwrapped, responsePayload);
   }
 
   async getCohortSitesLegacy(
@@ -243,13 +333,17 @@ export class DeviceService {
     const response = await this.authenticatedClient.post<
       LegacyCohortSitesResponse | ApiErrorResponse
     >(`${DEVICE_COHORTS_PATH}/sites`, request, { params, signal });
-    const data = response.data;
+    const responsePayload = response.data;
 
-    if ('success' in data && !data.success) {
-      throw new Error(data.message || 'Failed to get cohort sites');
+    if ('success' in responsePayload && !responsePayload.success) {
+      throw new Error(responsePayload.message || 'Failed to get cohort sites');
     }
 
-    return normalizeSitesResponse(data as LegacyCohortSitesResponse);
+    const unwrapped =
+      extractEnvelopeData<LegacyCohortSitesResponse>(responsePayload) ||
+      (responsePayload as LegacyCohortSitesResponse);
+
+    return normalizeSitesResponse(unwrapped, responsePayload);
   }
 
   // Get devices using cohort - authenticated endpoint
@@ -282,15 +376,21 @@ export class DeviceService {
       signal,
       suppressErrorLogging: true,
     });
-    const data = response.data;
+    const responsePayload = response.data;
 
-    if ('success' in data && !data.success) {
-      throw new Error(data.message || 'Failed to get cohort devices');
+    if ('success' in responsePayload && !responsePayload.success) {
+      throw new Error(
+        responsePayload.message || 'Failed to get cohort devices'
+      );
     }
 
-    return normalizeDevicesResponse(
-      data as CohortDevicesResponse | LegacyCohortDevicesResponse
-    );
+    const unwrapped =
+      extractEnvelopeData<CohortDevicesResponse | LegacyCohortDevicesResponse>(
+        responsePayload
+      ) ||
+      (responsePayload as CohortDevicesResponse | LegacyCohortDevicesResponse);
+
+    return normalizeDevicesResponse(unwrapped, responsePayload);
   }
 
   async getCohortDevicesLegacy(
@@ -302,13 +402,19 @@ export class DeviceService {
     const response = await this.authenticatedClient.post<
       LegacyCohortDevicesResponse | ApiErrorResponse
     >(`${DEVICE_COHORTS_PATH}/devices`, request, { params, signal });
-    const data = response.data;
+    const responsePayload = response.data;
 
-    if ('success' in data && !data.success) {
-      throw new Error(data.message || 'Failed to get cohort devices');
+    if ('success' in responsePayload && !responsePayload.success) {
+      throw new Error(
+        responsePayload.message || 'Failed to get cohort devices'
+      );
     }
 
-    return normalizeDevicesResponse(data as LegacyCohortDevicesResponse);
+    const unwrapped =
+      extractEnvelopeData<LegacyCohortDevicesResponse>(responsePayload) ||
+      (responsePayload as LegacyCohortDevicesResponse);
+
+    return normalizeDevicesResponse(unwrapped, responsePayload);
   }
 
   // Get active groups cohort ids - authenticated endpoint
@@ -320,23 +426,28 @@ export class DeviceService {
     const response = await this.authenticatedClient.get<
       GroupCohortsResponse | ApiErrorResponse
     >(`/users/groups/${groupId}/cohorts`, { signal });
-    const data = response.data;
+    const responsePayload = response.data;
 
-    if ('success' in data && !data.success) {
-      throw new Error(data.message || 'Failed to get group cohorts');
+    if ('success' in responsePayload && !responsePayload.success) {
+      throw new Error(responsePayload.message || 'Failed to get group cohorts');
     }
 
-    const groupCohortsData = data as GroupCohortsResponse;
     const normalizedCohortIds = Array.from(
       new Set(
-        (Array.isArray(groupCohortsData.data) ? groupCohortsData.data : [])
+        extractGroupCohortIds(responsePayload)
           .map(cohortId => cohortId?.trim())
           .filter((cohortId): cohortId is string => Boolean(cohortId))
       )
     );
 
+    const envelope = responsePayload as ApiEnvelope;
+
     return {
-      ...groupCohortsData,
+      success: typeof envelope.success === 'boolean' ? envelope.success : true,
+      message:
+        typeof envelope.message === 'string' && envelope.message.trim()
+          ? envelope.message
+          : 'Group cohorts retrieved successfully',
       data: normalizedCohortIds,
     };
   }
diff --git a/src/platform/src/shared/services/subscriptionService.ts b/src/platform/src/shared/services/subscriptionService.ts
index e74cd0a384..de5dce5ba0 100644
--- a/src/platform/src/shared/services/subscriptionService.ts
+++ b/src/platform/src/shared/services/subscriptionService.ts
@@ -96,10 +96,7 @@ type BackendTransaction = {
 type NormalizedSubscriptionStatus = UserSubscription['status'];
 type NormalizedRateLimits = NonNullable<UserSubscription['apiRateLimits']>;
 
-const USERS_PROFILE_CANDIDATE_PATHS = [
-  '/users/profile/enhanced',
-  '/users/me',
-] as const;
+const USERS_PROFILE_CANDIDATE_PATHS = ['/users/profile/enhanced'] as const;
 
 const RETRYABLE_PROFILE_STATUSES = new Set([400, 404, 405]);
 
@@ -323,7 +320,7 @@ const normalizeUsagePeriod = (
 
 const buildUsage = (
   payload?: UsagePayload | null,
-  fallbackRateLimits?: NormalizedRateLimits
+  fallbackRateLimits?: ApiRateLimitsPayload | NormalizedRateLimits | null
 ): ApiUsage => ({
   hourly: normalizeUsagePeriod(
     'hourly',
@@ -753,7 +750,9 @@ export class SubscriptionService {
   }> {
     let profile: UsersMePayload | null = null;
 
-    const getFallbackRateLimits = async () => {
+    const getFallbackRateLimits = async (): Promise<
+      ApiRateLimitsPayload | undefined
+    > => {
       if (!profile) {
         try {
           profile = await this.getUsersProfilePayload();
@@ -762,11 +761,7 @@ export class SubscriptionService {
         }
       }
 
-      const tier = normalizeTier(profile?.subscriptionTier);
-
-      return normalizeRateLimits(
-        mergeRateLimitsWithDefaults(tier, profile?.apiRateLimits)
-      );
+      return profile?.apiRateLimits ?? undefined;
     };
 
     try {
@@ -780,7 +775,7 @@ export class SubscriptionService {
       );
 
       const usagePayload = extractEnvelopeData<UsagePayload>(response.data);
-      let fallbackRateLimits: NormalizedRateLimits | undefined;
+      let fallbackRateLimits: ApiRateLimitsPayload | undefined;
       let usage = buildUsage(usagePayload);
 
       if (hasMissingUsageLimits(usage)) {

From 4fa16f78ba54bc9bf5d5ba59750176c214ecbfcb Mon Sep 17 00:00:00 2001
From: Paul Ochieng Levi <ochiengpaul442@gmail.com>
Date: Wed, 20 May 2026 15:38:18 +0300
Subject: [PATCH 4/8] Refactor site name handling across analytics components
 and utilities; introduce getSiteDisplayName utility for consistent site name
 resolution

---
 .../analytics/components/AnalyticsCard.tsx    |  5 ++-
 .../components/AnalyticsDashboard.tsx         | 25 +++++---------
 .../analytics/components/DownloadDialog.tsx   |  8 ++---
 .../src/modules/analytics/hooks/index.ts      | 24 +++-----------
 .../src/modules/analytics/utils/index.ts      | 16 +++++----
 .../location-insights/add-favorites.tsx       |  8 ++---
 .../location-insights/add-location.tsx        |  3 +-
 .../location-insights/more-insights.tsx       |  5 +--
 .../charts/components/charts/DynamicChart.tsx |  4 +--
 .../charts/components/ui/CustomTooltip.tsx    |  9 ++---
 .../shared/components/charts/types/index.ts   |  3 ++
 .../shared/components/charts/utils/index.ts   | 33 ++++++++++++++++++-
 src/platform/src/shared/utils/siteUtils.ts    | 33 +++++++++++--------
 13 files changed, 95 insertions(+), 81 deletions(-)

diff --git a/src/platform/src/modules/analytics/components/AnalyticsCard.tsx b/src/platform/src/modules/analytics/components/AnalyticsCard.tsx
index 82b6f53218..0cd82c6ecc 100644
--- a/src/platform/src/modules/analytics/components/AnalyticsCard.tsx
+++ b/src/platform/src/modules/analytics/components/AnalyticsCard.tsx
@@ -18,6 +18,7 @@ import type { PollutantType } from '@/shared/components/charts/types';
 import { useResizeObserver } from '@/shared/hooks';
 import { AqWind01 } from '@airqo/icons-react';
 import { anonymizeSiteData, trackEvent } from '@/shared/utils/analytics';
+import { getSiteDisplayName } from '@/shared/utils/siteUtils';
 
 export const AnalyticsCard: React.FC<AnalyticsCardProps> = memo(
   ({ siteData, className, showIcon = true, selectedPollutant, onClick }) => {
@@ -45,7 +46,6 @@ export const AnalyticsCard: React.FC<AnalyticsCardProps> = memo(
     useResizeObserver(locationRef.current, checkTruncation);
 
     const {
-      name,
       location,
       value,
       status: rawStatus,
@@ -69,8 +69,7 @@ export const AnalyticsCard: React.FC<AnalyticsCardProps> = memo(
     // Use selected pollutant for display, fallback to site data pollutant
     const displayPollutant = selectedPollutant || (pollutant as PollutantType);
 
-    // Format name for display by replacing underscores with spaces
-    const displayName = name.replace(/_/g, ' ');
+    const displayName = getSiteDisplayName(siteData);
 
     // Get appropriate icons
     // Narrow types before indexing into the icon maps to satisfy TS
diff --git a/src/platform/src/modules/analytics/components/AnalyticsDashboard.tsx b/src/platform/src/modules/analytics/components/AnalyticsDashboard.tsx
index ebd5b07549..d3c7aa6028 100644
--- a/src/platform/src/modules/analytics/components/AnalyticsDashboard.tsx
+++ b/src/platform/src/modules/analytics/components/AnalyticsDashboard.tsx
@@ -23,6 +23,7 @@ import type { SiteData } from '../types';
 import { openMoreInsights } from '@/shared/store/insightsSlice';
 import type { NormalizedChartData } from '@/shared/components/charts/types';
 import { trackEvent } from '@/shared/utils/analytics';
+import { getSiteDisplayName } from '@/shared/utils/siteUtils';
 import {
   useActiveGroupCohorts,
   useCohort,
@@ -195,15 +196,11 @@ export const AnalyticsDashboard: React.FC<AnalyticsDashboardProps> = ({
     return Array.from(uniqueSiteIds)
       .map(siteId => {
         const siteData = selectedSites.find(site => site._id === siteId);
+        const displayName = getSiteDisplayName(siteData || {});
         return {
           _id: siteId,
-          name:
-            siteData?.search_name ||
-            siteData?.name ||
-            siteData?.formatted_name ||
-            siteData?.generated_name ||
-            'Unknown Site',
-          search_name: siteData?.search_name,
+          name: displayName,
+          search_name: displayName,
           country: siteData?.country,
         };
       })
@@ -277,13 +274,8 @@ export const AnalyticsDashboard: React.FC<AnalyticsDashboardProps> = ({
       sites ||
       selectedSites.map(site => ({
         _id: site._id,
-        name:
-          site.search_name ||
-          site.name ||
-          site.formatted_name ||
-          site.generated_name ||
-          'Unknown Site',
-        search_name: site.search_name || site.name,
+        name: getSiteDisplayName(site),
+        search_name: getSiteDisplayName(site),
         country: site.country,
       }));
 
@@ -292,10 +284,11 @@ export const AnalyticsDashboard: React.FC<AnalyticsDashboardProps> = ({
 
   // Handle individual card click - open more insights for specific site
   const handleCardClick = (siteData: SiteData) => {
+    const displayName = getSiteDisplayName(siteData);
     const selectedSite = {
       _id: siteData._id,
-      name: siteData.search_name || siteData.name,
-      search_name: siteData.search_name || siteData.name,
+      name: displayName,
+      search_name: displayName,
       country: siteData.location,
     };
 
diff --git a/src/platform/src/modules/analytics/components/DownloadDialog.tsx b/src/platform/src/modules/analytics/components/DownloadDialog.tsx
index f3bb075f16..8ed2726641 100644
--- a/src/platform/src/modules/analytics/components/DownloadDialog.tsx
+++ b/src/platform/src/modules/analytics/components/DownloadDialog.tsx
@@ -12,6 +12,7 @@ import {
   FREQUENCY_LABELS,
   POLLUTANT_LABELS,
 } from '@/shared/components/charts/constants';
+import { getSiteDisplayName } from '@/shared/utils/siteUtils';
 
 interface DownloadDialogProps {
   isOpen: boolean;
@@ -180,12 +181,7 @@ export const DownloadDialog: React.FC<DownloadDialogProps> = ({
     () =>
       selectedSites.map(site => ({
         id: site._id,
-        displayName:
-          site.search_name ||
-          site.name ||
-          site.formatted_name ||
-          site.generated_name ||
-          `Site ${site._id.slice(-6)}`,
+        displayName: getSiteDisplayName(site),
         location: site.country || site.region || site.city || '',
       })),
     [selectedSites]
diff --git a/src/platform/src/modules/analytics/hooks/index.ts b/src/platform/src/modules/analytics/hooks/index.ts
index 13b3dec1e7..feccadf06f 100644
--- a/src/platform/src/modules/analytics/hooks/index.ts
+++ b/src/platform/src/modules/analytics/hooks/index.ts
@@ -10,6 +10,7 @@ import {
 import { useUser } from '@/shared/hooks/useUser';
 import { normalizeAirQualityData } from '@/shared/components/charts/utils';
 import { generateTrend, getAirQualityLevel } from '../utils';
+import { getSiteDisplayName } from '@/shared/utils/siteUtils';
 import { useAnalytics } from './useAnalytics';
 import { analyticsService } from '@/shared/services/analyticsService';
 import type { SiteData, ChartData } from '../types';
@@ -40,12 +41,7 @@ const buildNoValueSiteCard = (
   pollutant: string
 ): SiteData => ({
   _id: selectedSite._id,
-  name:
-    selectedSite.search_name ||
-    selectedSite.name ||
-    selectedSite.formatted_name ||
-    selectedSite.generated_name ||
-    'Unknown Site',
+  name: getSiteDisplayName(selectedSite),
   location: selectedSite.country || 'Unknown Country',
   value: 0,
   status: 'no-value',
@@ -116,22 +112,12 @@ const buildSiteCardsFromChartPoints = (
       Number.isFinite(previousValue) && previousValue !== 0
         ? ((latestValue - previousValue) / Math.abs(previousValue)) * 100
         : 0;
+    const displayName = getSiteDisplayName(selectedSite);
 
     return {
       _id: selectedSite._id,
-      name:
-        selectedSite.search_name ||
-        selectedSite.name ||
-        selectedSite.formatted_name ||
-        selectedSite.generated_name ||
-        latestPoint.name ||
-        latestPoint.generated_name ||
-        'Unknown Site',
-      search_name:
-        selectedSite.search_name ||
-        selectedSite.name ||
-        latestPoint.name ||
-        latestPoint.generated_name,
+      name: displayName,
+      search_name: displayName,
       location: buildSiteCardLocation(selectedSite),
       country: selectedSite.country,
       city: selectedSite.city,
diff --git a/src/platform/src/modules/analytics/utils/index.ts b/src/platform/src/modules/analytics/utils/index.ts
index fbf01ddd73..c34445a8f1 100644
--- a/src/platform/src/modules/analytics/utils/index.ts
+++ b/src/platform/src/modules/analytics/utils/index.ts
@@ -22,6 +22,7 @@ import {
 } from '@/shared/utils/airQuality';
 import { formatDistanceToNow, parseISO } from 'date-fns';
 import type { RecentReading } from '@/shared/types/api';
+import { getSiteDisplayName } from '@/shared/utils/siteUtils';
 
 // Re-export shared utilities for convenience
 export {
@@ -168,6 +169,11 @@ export const transformAnalyticsData = (
 
     const latestPoint = sortedPoints[0];
     const previousPoint = sortedPoints[1];
+    const displayName = getSiteDisplayName({
+      search_name: latestPoint.site_name,
+      name: latestPoint.site_name,
+      formatted_name: latestPoint.generated_name,
+    });
 
     const level = getAirQualityLevel(
       latestPoint.value,
@@ -177,8 +183,7 @@ export const transformAnalyticsData = (
 
     return {
       _id: siteId,
-      name:
-        latestPoint.site_name || latestPoint.generated_name || `Site ${siteId}`,
+      name: displayName || `Site ${siteId}`,
       location: latestPoint.generated_name || 'Unknown Location',
       value: latestPoint.value,
       status: level,
@@ -253,6 +258,7 @@ export const normalizeRecentReadingsToSiteData = (
 
   return measurements.map(measurement => {
     const { siteDetails, averages, pm2_5, pm10 } = measurement;
+    const displayName = getSiteDisplayName(siteDetails);
 
     // Get value based on active pollutant
     const pollutantValue =
@@ -275,11 +281,7 @@ export const normalizeRecentReadingsToSiteData = (
 
     return {
       _id: siteDetails?._id || measurement.site_id,
-      name:
-        siteDetails?.search_name ||
-        siteDetails?.name ||
-        siteDetails?.formatted_name ||
-        'Unknown Site',
+      name: displayName,
       location: siteDetails?.country || 'Unknown Country',
       value,
       status,
diff --git a/src/platform/src/modules/location-insights/add-favorites.tsx b/src/platform/src/modules/location-insights/add-favorites.tsx
index 09740e8683..dc265ffa30 100644
--- a/src/platform/src/modules/location-insights/add-favorites.tsx
+++ b/src/platform/src/modules/location-insights/add-favorites.tsx
@@ -20,6 +20,7 @@ import {
 import { useChecklistIntegration } from '@/modules/user-checklist';
 import type { Site } from '@/shared/types/api';
 import { trackEvent } from '@/shared/utils/analytics';
+import { getSiteDisplayName } from '@/shared/utils/siteUtils';
 
 const isCancellationError = (error: unknown) => {
   const candidate = error as {
@@ -338,12 +339,7 @@ const AddFavorites: React.FC<AddFavoritesProps> = ({ isOpen, onClose }) => {
                     transition={{ duration: 0.2, ease: 'easeOut' }}
                   >
                     <LocationCard
-                      locationName={
-                        location.search_name ||
-                        location.name ||
-                        location.generated_name ||
-                        ''
-                      }
+                      locationName={getSiteDisplayName(location)}
                       subtitle={`${location.city}, ${location.country}`}
                       isChecked={true}
                       showCloseButton={true}
diff --git a/src/platform/src/modules/location-insights/add-location.tsx b/src/platform/src/modules/location-insights/add-location.tsx
index eb2925efb7..2ea0b4ea45 100644
--- a/src/platform/src/modules/location-insights/add-location.tsx
+++ b/src/platform/src/modules/location-insights/add-location.tsx
@@ -21,6 +21,7 @@ import {
   trackLocationSelection,
   trackFeatureUsage,
 } from '@/shared/utils/enhancedAnalytics';
+import { getSiteDisplayName } from '@/shared/utils/siteUtils';
 
 const AddLocation: React.FC = () => {
   const dispatch = useDispatch();
@@ -220,7 +221,7 @@ const AddLocation: React.FC = () => {
                     transition={{ duration: 0.2, ease: 'easeOut' }}
                   >
                     <LocationCard
-                      locationName={siteData.name}
+                      locationName={getSiteDisplayName(siteData)}
                       country={siteData.country}
                       subtitle={siteData.city}
                       isChecked={true}
diff --git a/src/platform/src/modules/location-insights/more-insights.tsx b/src/platform/src/modules/location-insights/more-insights.tsx
index 7f953b9348..43aea83178 100644
--- a/src/platform/src/modules/location-insights/more-insights.tsx
+++ b/src/platform/src/modules/location-insights/more-insights.tsx
@@ -42,6 +42,7 @@ import { useUser } from '@/shared/hooks/useUser';
 import { useGetChartData } from '@/shared/hooks/useAnalytics';
 import { useDataDownload } from '@/modules/analytics/hooks';
 import { toast } from '@/shared/components/ui/toast';
+import { getSiteDisplayName } from '@/shared/utils/siteUtils';
 
 type MoreInsightsProps = {
   activeTab?: 'sites' | 'devices';
@@ -361,7 +362,7 @@ export const MoreInsights: React.FC<MoreInsightsProps> = ({ activeTab }) => {
     if (selectedSites.length === 0) {
       return 'Air Quality Insights';
     } else if (selectedSites.length === 1) {
-      return `Air Quality Insights - ${selectedSites[0].name}`;
+      return `Air Quality Insights - ${getSiteDisplayName(selectedSites[0])}`;
     } else {
       return `Air Quality Insights - ${selectedSites.length} Locations`;
     }
@@ -529,7 +530,7 @@ export const MoreInsights: React.FC<MoreInsightsProps> = ({ activeTab }) => {
           filteredSites.map((site: SelectedSite) => (
             <LocationCard
               key={site._id}
-              locationName={site.name}
+              locationName={getSiteDisplayName(site)}
               country={site.country}
               deviceName={site.device_name}
               isChecked={visibleSites.has(site._id)}
diff --git a/src/platform/src/shared/components/charts/components/charts/DynamicChart.tsx b/src/platform/src/shared/components/charts/components/charts/DynamicChart.tsx
index 8c08468acf..a60df1151e 100644
--- a/src/platform/src/shared/components/charts/components/charts/DynamicChart.tsx
+++ b/src/platform/src/shared/components/charts/components/charts/DynamicChart.tsx
@@ -141,9 +141,7 @@ export const DynamicChart: React.FC<DynamicChartProps> = ({
     (value: string | number | undefined, entry: LegendPayload) => {
       const seriesKey = String(entry.dataKey ?? entry.value ?? '').trim();
       const isHidden = seriesKey ? hiddenSeries.has(seriesKey) : false;
-      const formattedValue = String(value ?? '')
-        .replace(/_/g, ' ')
-        .trim();
+      const formattedValue = String(value ?? '').trim();
 
       return (
         <span
diff --git a/src/platform/src/shared/components/charts/components/ui/CustomTooltip.tsx b/src/platform/src/shared/components/charts/components/ui/CustomTooltip.tsx
index bf71fc87d1..013f662f2c 100644
--- a/src/platform/src/shared/components/charts/components/ui/CustomTooltip.tsx
+++ b/src/platform/src/shared/components/charts/components/ui/CustomTooltip.tsx
@@ -5,6 +5,7 @@ import { TooltipData } from '../../types';
 import { cn } from '@/shared/lib/utils';
 import { format, parseISO } from 'date-fns';
 import { getAirQualityInfo } from '@/shared/utils/airQuality';
+import { getChartLocationDisplayName } from '../../utils';
 
 interface CustomTooltipProps extends TooltipData {
   className?: string;
@@ -45,6 +46,7 @@ export const CustomTooltip: React.FC<CustomTooltipProps> = ({
   const primaryData = payload[0];
   const value = primaryData.value as number;
   const airQualityLevel = getAirQualityInfo(value, pollutant);
+  const locationName = getChartLocationDisplayName(primaryData.payload);
 
   return (
     <div
@@ -69,7 +71,7 @@ export const CustomTooltip: React.FC<CustomTooltipProps> = ({
                 style={{ backgroundColor: entry.color }}
               />
               <span className="text-sm font-medium text-foreground truncate max-w-[220px] block">
-                {String(entry.name || entry.dataKey || '').replace(/_/g, ' ')}
+                {String(entry.name || entry.dataKey || '').trim()}
               </span>
             </div>
             <div className="text-right ml-2 flex-shrink-0">
@@ -103,11 +105,10 @@ export const CustomTooltip: React.FC<CustomTooltipProps> = ({
         )}
 
       {/* Location info if available */}
-      {primaryData.payload?.site && (
+      {locationName !== 'Unknown Location' && (
         <div className="mt-2 pt-2 border-t border-border">
           <div className="text-xs text-muted-foreground">
-            <span className="font-medium">Location:</span>{' '}
-            {String(primaryData.payload.site || '').replace(/_/g, ' ')}
+            <span className="font-medium">Location:</span> {locationName}
           </div>
           {primaryData.payload?.device_id && (
             <div className="text-xs text-muted-foreground">
diff --git a/src/platform/src/shared/components/charts/types/index.ts b/src/platform/src/shared/components/charts/types/index.ts
index c4925d66da..272caa260b 100644
--- a/src/platform/src/shared/components/charts/types/index.ts
+++ b/src/platform/src/shared/components/charts/types/index.ts
@@ -6,6 +6,9 @@ export interface AirQualityDataPoint {
   generated_name: string;
   device_id: string;
   name: string;
+  search_name?: string;
+  location_name?: string;
+  formatted_name?: string;
 }
 
 export interface NormalizedChartData {
diff --git a/src/platform/src/shared/components/charts/utils/index.ts b/src/platform/src/shared/components/charts/utils/index.ts
index f3ced9af01..eae9c6b3e2 100644
--- a/src/platform/src/shared/components/charts/utils/index.ts
+++ b/src/platform/src/shared/components/charts/utils/index.ts
@@ -8,6 +8,32 @@ import {
 import { format, parseISO } from 'date-fns';
 import { CHART_TYPE_THRESHOLDS } from '../constants';
 
+type ChartLocationDisplaySource = {
+  search_name?: string;
+  location_name?: string;
+  name?: string;
+  formatted_name?: string;
+  generated_name?: string;
+  site?: string;
+};
+
+/**
+ * Resolves the display name for a chart site/location.
+ */
+export const getChartLocationDisplayName = (
+  source: ChartLocationDisplaySource
+): string => {
+  return (
+    source.search_name?.trim() ||
+    source.location_name?.trim() ||
+    source.name?.trim() ||
+    source.formatted_name?.trim() ||
+    source.site?.trim() ||
+    source.generated_name?.trim() ||
+    'Unknown Location'
+  );
+};
+
 /**
  * Normalizes air quality data for chart consumption
  */
@@ -22,10 +48,15 @@ export const normalizeAirQualityData = (
   return data.map(point => ({
     time: point.time,
     value: Math.round(point.value * 100) / 100, // Round to 2 decimal places
-    site: point.name || point.generated_name,
+    site: getChartLocationDisplayName(point),
     device_id: point.device_id,
     site_id: point.site_id,
     rawTime: point.time,
+    search_name: point.search_name,
+    location_name: point.location_name,
+    formatted_name: point.formatted_name,
+    name: point.name,
+    generated_name: point.generated_name,
   }));
 };
 
diff --git a/src/platform/src/shared/utils/siteUtils.ts b/src/platform/src/shared/utils/siteUtils.ts
index 932df2557e..d48f0c36e2 100644
--- a/src/platform/src/shared/utils/siteUtils.ts
+++ b/src/platform/src/shared/utils/siteUtils.ts
@@ -15,6 +15,24 @@ export interface RawSiteData {
   [key: string]: unknown;
 }
 
+/**
+ * Resolves the display label for a site/location using the shared precedence.
+ */
+export const getSiteDisplayName = (
+  site: Pick<
+    RawSiteData,
+    'search_name' | 'location_name' | 'name' | 'formatted_name'
+  >
+): string => {
+  return (
+    site.search_name?.trim() ||
+    site.location_name?.trim() ||
+    site.name?.trim() ||
+    site.formatted_name?.trim() ||
+    'Unknown Location'
+  );
+};
+
 // Normalized site data for table display
 export interface NormalizedSiteData {
   id: string;
@@ -35,12 +53,7 @@ export interface NormalizedSiteData {
  */
 export const normalizeSiteData = (site: RawSiteData): NormalizedSiteData => {
   // Extract location name with fallback priority
-  const location =
-    site.search_name ||
-    site.name ||
-    site.formatted_name ||
-    site.location_name ||
-    'Unknown Location';
+  const location = getSiteDisplayName(site);
 
   return {
     id: site._id,
@@ -75,13 +88,7 @@ export const getSiteDisplayValue = (
 ): string => {
   switch (property) {
     case 'location':
-      return (
-        site.search_name ||
-        site.name ||
-        site.formatted_name ||
-        site.location_name ||
-        'Unknown Location'
-      );
+      return getSiteDisplayName(site);
     case 'city':
       return site.city || 'Unknown City';
     case 'country':

From 74b974f1ec4f44c6d16123478b572e168b082290 Mon Sep 17 00:00:00 2001
From: Paul Ochieng Levi <ochiengpaul442@gmail.com>
Date: Wed, 20 May 2026 16:15:52 +0300
Subject: [PATCH 5/8] Enhance error handling in analytics and billing
 components; implement abort error detection and improve user feedback for
 loading states

---
 .../analytics/components/AnalyticsCard.tsx    |   4 +-
 .../analytics/components/QuickAccessCard.tsx  | 106 +++++++++++++++++-
 .../src/modules/analytics/hooks/index.ts      |   2 +-
 .../modules/billing/components/UsageStats.tsx |  55 ++++++++-
 .../shared/services/subscriptionService.ts    |  45 +++++++-
 5 files changed, 194 insertions(+), 18 deletions(-)

diff --git a/src/platform/src/modules/analytics/components/AnalyticsCard.tsx b/src/platform/src/modules/analytics/components/AnalyticsCard.tsx
index 0cd82c6ecc..b0b4196217 100644
--- a/src/platform/src/modules/analytics/components/AnalyticsCard.tsx
+++ b/src/platform/src/modules/analytics/components/AnalyticsCard.tsx
@@ -141,8 +141,8 @@ export const AnalyticsCard: React.FC<AnalyticsCardProps> = memo(
               <Tooltip
                 content={
                   percentageDifference !== undefined
-                    ? `Air quality ${percentageDifference > 0 ? 'worsened' : 'improved'} by ${Math.abs(percentageDifference).toFixed(1)}% compared to last week.`
-                    : 'Air quality trend compared to last week.'
+                    ? `Air quality ${percentageDifference > 0 ? 'worsened' : 'improved'} by ${Math.abs(percentageDifference).toFixed(1)}% compared with the previous reading.`
+                    : 'Air quality trend compared with the previous reading.'
                 }
                 className="bg-black"
               >
diff --git a/src/platform/src/modules/analytics/components/QuickAccessCard.tsx b/src/platform/src/modules/analytics/components/QuickAccessCard.tsx
index e36f01debf..fdb5bf7034 100644
--- a/src/platform/src/modules/analytics/components/QuickAccessCard.tsx
+++ b/src/platform/src/modules/analytics/components/QuickAccessCard.tsx
@@ -8,6 +8,99 @@ import type { QuickAccessLocationsProps } from '../types';
 import { AnalyticsCard } from './AnalyticsCard';
 import { LoadingSpinner } from '@/shared/components/ui/loading-spinner';
 import { EmptyState } from '@/shared/components/ui';
+import { getUserFriendlyErrorMessage } from '@/shared/utils/errorMessages';
+
+const QUICK_ACCESS_ERROR_MESSAGE =
+  'Your favorites are saved. Refresh to try loading the latest readings again.';
+
+const QUICK_ACCESS_ERROR_TECHNICAL_PATTERNS = [
+  /failed to fetch/i,
+  /request failed/i,
+  /internal server error/i,
+  /service unavailable/i,
+  /gateway timeout/i,
+  /axioserror/i,
+  /err_network/i,
+  /err_canceled/i,
+  /timeout/i,
+  /abort/i,
+  /exception/i,
+  /traceback/i,
+  /stack trace/i,
+  /token/i,
+  /session/i,
+  /unauthorized/i,
+  /forbidden/i,
+  /database/i,
+  /sql/i,
+];
+
+const isCancellationMessage = (message: string): boolean => {
+  const lowerMessage = message.toLowerCase();
+
+  return (
+    lowerMessage.includes('aborterror') ||
+    lowerMessage.includes('canceled') ||
+    lowerMessage.includes('cancelled') ||
+    lowerMessage.includes('request aborted') ||
+    lowerMessage.includes('request canceled') ||
+    lowerMessage.includes('request cancelled')
+  );
+};
+
+const redactSensitiveTokens = (message: string): string => {
+  return message
+    .replace(/Bearer\s+[A-Za-z0-9-._~+/]+=*/gi, '[redacted]')
+    .replace(
+      /\beyJ[A-Za-z0-9-._~+/]+=*\.[A-Za-z0-9-._~+/]+=*(?:\.[A-Za-z0-9-._~+/]+=*)?\b/g,
+      '[redacted]'
+    )
+    .replace(
+      /(token|session|accessToken|refreshToken)=([^&\s]+)/gi,
+      '$1=[redacted]'
+    )
+    .replace(/[\w.-]+@[\w.-]+\.\w+/g, '[redacted]')
+    .replace(
+      /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi,
+      '[redacted]'
+    )
+    .replace(/[A-Za-z]:\\[\\\w\s.-]+/g, '[redacted]')
+    .replace(/\s+/g, ' ')
+    .trim();
+};
+
+const getDisplayErrorMessage = (
+  errorMessage: string | null | undefined
+): string | null => {
+  if (!errorMessage?.trim()) {
+    return null;
+  }
+
+  const trimmedMessage = errorMessage.trim();
+  if (isCancellationMessage(trimmedMessage)) {
+    return null;
+  }
+
+  const friendlyMessage = getUserFriendlyErrorMessage(trimmedMessage).trim();
+  if (friendlyMessage !== trimmedMessage) {
+    const sanitizedFriendlyMessage = redactSensitiveTokens(friendlyMessage);
+    return sanitizedFriendlyMessage || QUICK_ACCESS_ERROR_MESSAGE;
+  }
+
+  const sanitizedMessage = redactSensitiveTokens(trimmedMessage);
+  if (
+    !sanitizedMessage ||
+    QUICK_ACCESS_ERROR_TECHNICAL_PATTERNS.some(pattern =>
+      pattern.test(sanitizedMessage)
+    )
+  ) {
+    return QUICK_ACCESS_ERROR_MESSAGE;
+  }
+
+  return sanitizedMessage.length > 140
+    ? `${sanitizedMessage.slice(0, 137)}...`
+    : sanitizedMessage;
+};
 
 export const QuickAccessCard: React.FC<QuickAccessLocationsProps> = memo(
   ({
@@ -29,8 +122,12 @@ export const QuickAccessCard: React.FC<QuickAccessLocationsProps> = memo(
     onCardClick,
   }) => {
     const visiblePlaceholderCount = Math.min(Math.max(placeholderCount, 1), 4);
-    const shouldShowSkeleton = visiblePlaceholderCount > 0 && isLoading;
-    const shouldShowErrorState = !isLoading && Boolean(errorMessage);
+    const hasUsableSites = sites.length > 0;
+    const displayErrorMessage = getDisplayErrorMessage(errorMessage);
+    const shouldShowSkeleton =
+      visiblePlaceholderCount > 0 && isLoading && !hasUsableSites;
+    const shouldShowErrorState =
+      !isLoading && !hasUsableSites && Boolean(displayErrorMessage);
     const shouldShowAddFavorite =
       !shouldShowSkeleton && !shouldShowErrorState && sites.length < 4;
 
@@ -72,10 +169,7 @@ export const QuickAccessCard: React.FC<QuickAccessLocationsProps> = memo(
               <EmptyState
                 compact={true}
                 title="Latest readings could not be loaded"
-                description={
-                  errorMessage ||
-                  'Your favorites are saved. Refresh to try loading the latest readings again.'
-                }
+                description={displayErrorMessage || QUICK_ACCESS_ERROR_MESSAGE}
                 action={
                   onRefresh
                     ? {
diff --git a/src/platform/src/modules/analytics/hooks/index.ts b/src/platform/src/modules/analytics/hooks/index.ts
index feccadf06f..f98fa699bb 100644
--- a/src/platform/src/modules/analytics/hooks/index.ts
+++ b/src/platform/src/modules/analytics/hooks/index.ts
@@ -111,7 +111,7 @@ const buildSiteCardsFromChartPoints = (
     const percentageDifference =
       Number.isFinite(previousValue) && previousValue !== 0
         ? ((latestValue - previousValue) / Math.abs(previousValue)) * 100
-        : 0;
+        : undefined;
     const displayName = getSiteDisplayName(selectedSite);
 
     return {
diff --git a/src/platform/src/modules/billing/components/UsageStats.tsx b/src/platform/src/modules/billing/components/UsageStats.tsx
index 089eea2785..e8cef3733f 100644
--- a/src/platform/src/modules/billing/components/UsageStats.tsx
+++ b/src/platform/src/modules/billing/components/UsageStats.tsx
@@ -1,6 +1,6 @@
 'use client';
 
-import React, { useEffect, useState } from 'react';
+import React, { useEffect, useRef, useState } from 'react';
 import {
   Card,
   InfoBanner,
@@ -11,6 +11,25 @@ import { AqRefreshCcw01 } from '@airqo/icons-react';
 import { subscriptionService } from '@/shared/services/subscriptionService';
 import type { ApiUsage } from '@/shared/types/api';
 
+const isAbortError = (error: unknown): boolean => {
+  const candidate = error as {
+    name?: string;
+    code?: string;
+    message?: string;
+  } | null;
+
+  if (!candidate) {
+    return false;
+  }
+
+  return (
+    candidate.name === 'AbortError' ||
+    candidate.name === 'CanceledError' ||
+    candidate.code === 'ERR_CANCELED' ||
+    candidate.message === 'canceled'
+  );
+};
+
 interface UsagePeriod {
   title: string;
   data: {
@@ -27,14 +46,28 @@ const UsageStats: React.FC = () => {
   const [liveUsage, setLiveUsage] = useState(true);
   const [usageMessage, setUsageMessage] = useState('');
   const [currentTime, setCurrentTime] = useState(() => Date.now());
+  const abortControllerRef = useRef<AbortController | null>(null);
+  const requestIdRef = useRef(0);
 
   useEffect(() => {
     let isActive = true;
 
     const fetchUsage = async () => {
+      const requestId = ++requestIdRef.current;
+      abortControllerRef.current?.abort();
+      const controller = new AbortController();
+      abortControllerRef.current = controller;
+
       try {
-        const data = await subscriptionService.getUsage();
-        if (!isActive) {
+        const data = await subscriptionService.getUsage({
+          signal: controller.signal,
+        });
+
+        if (
+          !isActive ||
+          controller.signal.aborted ||
+          requestId !== requestIdRef.current
+        ) {
           return;
         }
 
@@ -44,11 +77,23 @@ const UsageStats: React.FC = () => {
           setUsageMessage(data.message || '');
         }
       } catch (error) {
+        if (!isActive || isAbortError(error) || controller.signal.aborted) {
+          return;
+        }
+
         if (isActive) {
           console.error('Error fetching usage stats:', error);
         }
       } finally {
-        if (isActive) {
+        if (abortControllerRef.current === controller) {
+          abortControllerRef.current = null;
+        }
+
+        if (
+          isActive &&
+          !controller.signal.aborted &&
+          requestId === requestIdRef.current
+        ) {
           setLoading(false);
         }
       }
@@ -64,6 +109,8 @@ const UsageStats: React.FC = () => {
 
     return () => {
       isActive = false;
+      abortControllerRef.current?.abort();
+      abortControllerRef.current = null;
       clearInterval(interval);
     };
   }, []);
diff --git a/src/platform/src/shared/services/subscriptionService.ts b/src/platform/src/shared/services/subscriptionService.ts
index de5dce5ba0..9592c2911b 100644
--- a/src/platform/src/shared/services/subscriptionService.ts
+++ b/src/platform/src/shared/services/subscriptionService.ts
@@ -100,6 +100,25 @@ const USERS_PROFILE_CANDIDATE_PATHS = ['/users/profile/enhanced'] as const;
 
 const RETRYABLE_PROFILE_STATUSES = new Set([400, 404, 405]);
 
+const isAbortError = (error: unknown): boolean => {
+  const candidate = error as {
+    name?: string;
+    code?: string;
+    message?: string;
+  } | null;
+
+  if (!candidate) {
+    return false;
+  }
+
+  return (
+    candidate.name === 'AbortError' ||
+    candidate.name === 'CanceledError' ||
+    candidate.code === 'ERR_CANCELED' ||
+    candidate.message === 'canceled'
+  );
+};
+
 const getDefaultPlans = (): SubscriptionPlan[] => [
   {
     tier: 'Free',
@@ -607,7 +626,9 @@ export class SubscriptionService {
     return params;
   }
 
-  private async getUsersProfilePayload(): Promise<UsersMePayload> {
+  private async getUsersProfilePayload(
+    signal?: AbortSignal
+  ): Promise<UsersMePayload> {
     await this.ensureAuthenticated();
 
     const orderedPaths = this.resolvedUsersProfilePath
@@ -627,12 +648,17 @@ export class SubscriptionService {
           profilePath,
           {
             params: this.withTenant(),
+            signal,
           }
         );
 
         this.resolvedUsersProfilePath = profilePath;
         return resolveUsersProfilePayload(response.data);
       } catch (error) {
+        if (isAbortError(error)) {
+          throw error;
+        }
+
         const status =
           (error as { response?: { status?: number } })?.response?.status || 0;
 
@@ -742,7 +768,7 @@ export class SubscriptionService {
     };
   }
 
-  async getUsage(): Promise<{
+  async getUsage(options: { signal?: AbortSignal } = {}): Promise<{
     success: boolean;
     message: string;
     usage: ApiUsage;
@@ -755,8 +781,12 @@ export class SubscriptionService {
     > => {
       if (!profile) {
         try {
-          profile = await this.getUsersProfilePayload();
-        } catch {
+          profile = await this.getUsersProfilePayload(options.signal);
+        } catch (error) {
+          if (isAbortError(error)) {
+            throw error;
+          }
+
           profile = null;
         }
       }
@@ -771,6 +801,7 @@ export class SubscriptionService {
         '/users/transactions/usage',
         {
           params: this.withTenant(),
+          signal: options.signal,
         }
       );
 
@@ -792,7 +823,11 @@ export class SubscriptionService {
         usage,
         live: true,
       };
-    } catch {
+    } catch (error) {
+      if (isAbortError(error)) {
+        throw error;
+      }
+
       const fallbackRateLimits = await getFallbackRateLimits();
 
       return {

From a55735eb6e3be819b515111b156ad68ad3260f86 Mon Sep 17 00:00:00 2001
From: Paul Ochieng Levi <ochiengpaul442@gmail.com>
Date: Thu, 21 May 2026 00:35:03 +0300
Subject: [PATCH 6/8] Add user ID handling to checkout session creation;
 enhance error messaging for user identification

---
 .../components/SubscriptionSection.tsx        |  17 +++
 .../shared/services/subscriptionService.ts    | 126 +++++++++++++++---
 2 files changed, 121 insertions(+), 22 deletions(-)

diff --git a/src/platform/src/modules/billing/components/SubscriptionSection.tsx b/src/platform/src/modules/billing/components/SubscriptionSection.tsx
index 4b793b7eab..fa7a10f02a 100644
--- a/src/platform/src/modules/billing/components/SubscriptionSection.tsx
+++ b/src/platform/src/modules/billing/components/SubscriptionSection.tsx
@@ -7,6 +7,7 @@ import React, {
   useRef,
   useState,
 } from 'react';
+import { useSession } from 'next-auth/react';
 import { AqCheck } from '@airqo/icons-react';
 import { Button, Card, LoadingSpinner, toast } from '@/shared/components/ui';
 import { formatDate } from '@/shared/utils';
@@ -21,6 +22,10 @@ import CheckoutDialog from './CheckoutDialog';
 const BILLING_SERVICE_UNAVAILABLE_MESSAGE =
   'Billing service is temporarily unavailable. Please try again later.';
 
+interface ExtendedSessionUser {
+  _id?: string;
+}
+
 const statusBadgeStyles: Record<string, string> = {
   active:
     'bg-emerald-100 text-emerald-800 dark:bg-emerald-900/40 dark:text-emerald-200',
@@ -66,6 +71,7 @@ const getBillingErrorLogMessage = (error: unknown): string => {
 };
 
 const SubscriptionSection: React.FC = () => {
+  const { data: session } = useSession();
   const [subscription, setSubscription] = useState<UserSubscription | null>(
     null
   );
@@ -79,6 +85,8 @@ const SubscriptionSection: React.FC = () => {
     'checkout' | 'enableAutoRenew' | 'disableAutoRenew' | 'cancel' | null
   >(null);
   const isMountedRef = useRef(true);
+  const userId =
+    (session?.user as ExtendedSessionUser | null)?._id?.trim() || '';
 
   const currentTier: SubscriptionTier = subscription?.tier || 'Free';
   const currentStatus = subscription?.status || 'inactive';
@@ -151,11 +159,20 @@ const SubscriptionSection: React.FC = () => {
       return;
     }
 
+    if (!userId) {
+      toast.error(
+        'Unable to determine the current user. Please refresh and try again.'
+      );
+      return;
+    }
+
     try {
       setRunningAction('checkout');
 
       const payload = await subscriptionService.createCheckoutSession({
+        userId,
         tier: selectedPlan.tier,
+        currency: selectedPlan.currency?.trim() || 'USD',
       });
 
       if (!payload.success) {
diff --git a/src/platform/src/shared/services/subscriptionService.ts b/src/platform/src/shared/services/subscriptionService.ts
index 9592c2911b..0c3a6f0b13 100644
--- a/src/platform/src/shared/services/subscriptionService.ts
+++ b/src/platform/src/shared/services/subscriptionService.ts
@@ -61,7 +61,9 @@ interface UsagePayload {
 }
 
 interface CheckoutRequest {
+  userId: string;
   tier: SubscriptionTier;
+  currency: string;
 }
 
 interface CheckoutResponse {
@@ -517,7 +519,65 @@ const extractMessage = (payload: unknown, fallback: string): string => {
   }
 
   const message = (payload as { message?: unknown }).message;
-  return typeof message === 'string' && message.trim() ? message : fallback;
+  const validationErrors = (() => {
+    const errors = (payload as { errors?: unknown }).errors;
+
+    if (!Array.isArray(errors)) {
+      return [] as string[];
+    }
+
+    return errors
+      .map(error => {
+        if (typeof error === 'string') {
+          return error.trim();
+        }
+
+        if (!error || typeof error !== 'object') {
+          return '';
+        }
+
+        const candidate = error as {
+          param?: unknown;
+          field?: unknown;
+          message?: unknown;
+        };
+        const param =
+          typeof candidate.param === 'string' && candidate.param.trim()
+            ? candidate.param.trim()
+            : typeof candidate.field === 'string' && candidate.field.trim()
+              ? candidate.field.trim()
+              : '';
+        const errorMessage =
+          typeof candidate.message === 'string' && candidate.message.trim()
+            ? candidate.message.trim()
+            : '';
+
+        if (param && errorMessage) {
+          return `${param}: ${errorMessage}`;
+        }
+
+        return errorMessage || param;
+      })
+      .filter((item): item is string => Boolean(item));
+  })();
+
+  if (validationErrors.length) {
+    const normalizedMessage =
+      typeof message === 'string' ? message.trim().toLowerCase() : '';
+
+    if (
+      !normalizedMessage ||
+      normalizedMessage.includes('bad request') ||
+      normalizedMessage.includes('validation') ||
+      normalizedMessage === 'errors'
+    ) {
+      return validationErrors.join('; ');
+    }
+  }
+
+  return typeof message === 'string' && message.trim()
+    ? message.trim()
+    : fallback;
 };
 
 const isPaymentProviderUnavailable = (status: number, payload: unknown) => {
@@ -688,37 +748,47 @@ export class SubscriptionService {
         '/users/transactions/subscription-status',
         {
           params: this.withTenant(),
+          validateStatus: status =>
+            (status >= 200 && status < 300) ||
+            status === 400 ||
+            status === 404 ||
+            status === 405,
         }
       );
 
-      const statusData = extractEnvelopeData<SubscriptionStatusPayload>(
-        statusResponse.data
-      );
+      if (statusResponse.status < 200 || statusResponse.status >= 300) {
+        statusRateLimitsPayload = undefined;
+      } else {
+        const statusData = extractEnvelopeData<SubscriptionStatusPayload>(
+          statusResponse.data
+        );
 
-      const statusTier = statusData?.subscriptionTier ?? statusData?.tier;
-      const statusValue = statusData?.subscriptionStatus ?? statusData?.status;
+        const statusTier = statusData?.subscriptionTier ?? statusData?.tier;
+        const statusValue =
+          statusData?.subscriptionStatus ?? statusData?.status;
 
-      if (statusTier) {
-        tier = normalizeTier(statusTier);
-      }
+        if (statusTier) {
+          tier = normalizeTier(statusTier);
+        }
 
-      if (statusValue) {
-        status = normalizeStatus(statusValue);
-      }
+        if (statusValue) {
+          status = normalizeStatus(statusValue);
+        }
 
-      if (statusData?.nextBillingDate !== undefined) {
-        nextBillingDate = statusData.nextBillingDate ?? null;
-      }
+        if (statusData?.nextBillingDate !== undefined) {
+          nextBillingDate = statusData.nextBillingDate ?? null;
+        }
 
-      if (typeof statusData?.automaticRenewal === 'boolean') {
-        automaticRenewal = statusData.automaticRenewal;
-      }
+        if (typeof statusData?.automaticRenewal === 'boolean') {
+          automaticRenewal = statusData.automaticRenewal;
+        }
 
-      if (statusData?.currentSubscriptionId !== undefined) {
-        currentSubscriptionId = statusData.currentSubscriptionId ?? null;
-      }
+        if (statusData?.currentSubscriptionId !== undefined) {
+          currentSubscriptionId = statusData.currentSubscriptionId ?? null;
+        }
 
-      statusRateLimitsPayload = statusData?.apiRateLimits;
+        statusRateLimitsPayload = statusData?.apiRateLimits;
+      }
     } catch {
       // Fall back to profile details when status endpoint is unavailable.
     }
@@ -857,6 +927,14 @@ export class SubscriptionService {
   ): Promise<CheckoutResponse> {
     await this.ensureAuthenticated();
 
+    const userId = request.userId.trim();
+    if (!userId) {
+      return {
+        success: false,
+        message: 'User ID is required to create a checkout session',
+      };
+    }
+
     const tier = normalizeTier(request.tier);
     if (tier === 'Free') {
       return {
@@ -865,8 +943,12 @@ export class SubscriptionService {
       };
     }
 
+    const currency = request.currency.trim() || 'USD';
+
     const payload: Record<string, string> = {
+      user_id: userId,
       tier,
+      currency,
     };
 
     try {

From b964ff7a8da923fdf465a13dda68d15fe89788c0 Mon Sep 17 00:00:00 2001
From: Paul Ochieng Levi <ochiengpaul442@gmail.com>
Date: Thu, 21 May 2026 00:49:21 +0300
Subject: [PATCH 7/8] Refactor Dockerfile and package.json to streamline asset
 copying; remove obsolete script for standalone asset management

---
 src/platform/Dockerfile                       |  2 ++
 src/platform/package.json                     |  2 +-
 .../scripts/copy-standalone-assets.mjs        | 29 -------------------
 3 files changed, 3 insertions(+), 30 deletions(-)
 delete mode 100644 src/platform/scripts/copy-standalone-assets.mjs

diff --git a/src/platform/Dockerfile b/src/platform/Dockerfile
index 0824e594d2..0e81611998 100644
--- a/src/platform/Dockerfile
+++ b/src/platform/Dockerfile
@@ -36,6 +36,8 @@ COPY --from=builder /app/package.json ./package.json
 # Automatically leverage output traces to reduce image size
 # https://nextjs.org/docs/advanced-features/output-file-tracing
 COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/public ./public
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
 
 USER nextjs
 
diff --git a/src/platform/package.json b/src/platform/package.json
index 9671b61c0f..7993750445 100644
--- a/src/platform/package.json
+++ b/src/platform/package.json
@@ -5,7 +5,7 @@
   "scripts": {
     "dev": "next dev",
     "build": "next build",
-    "postbuild": "node scripts/copy-standalone-assets.mjs",
+    "postbuild": "node -e \"const fs=require('node:fs'); const path=require('node:path'); const projectRoot=process.cwd(); const standaloneRoot=path.join(projectRoot,'.next','standalone'); const publicSource=path.join(projectRoot,'public'); const publicTarget=path.join(standaloneRoot,'public'); const staticSource=path.join(projectRoot,'.next','static'); const staticTarget=path.join(standaloneRoot,'.next','static'); const copyDirectory=(source,target)=>{ if(!fs.existsSync(source)) return false; fs.mkdirSync(path.dirname(target),{recursive:true}); fs.rmSync(target,{recursive:true,force:true}); fs.cpSync(source,target,{recursive:true}); return true; }; if(!fs.existsSync(standaloneRoot)){ throw new Error(`Standalone output not found at ${standaloneRoot}. Run 'yarn build' first.`); } copyDirectory(publicSource, publicTarget); copyDirectory(staticSource, staticTarget);\"",
     "start": "node -e \"const { loadEnvConfig } = require('@next/env'); loadEnvConfig(process.cwd()); process.env.HOSTNAME='localhost'; require('./.next/standalone/server.js')\"",
     "lint": "next lint",
     "format": "prettier --write .",
diff --git a/src/platform/scripts/copy-standalone-assets.mjs b/src/platform/scripts/copy-standalone-assets.mjs
deleted file mode 100644
index 515b5e173a..0000000000
--- a/src/platform/scripts/copy-standalone-assets.mjs
+++ /dev/null
@@ -1,29 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-
-const projectRoot = process.cwd();
-const standaloneRoot = path.join(projectRoot, '.next', 'standalone');
-const publicSource = path.join(projectRoot, 'public');
-const publicTarget = path.join(standaloneRoot, 'public');
-const staticSource = path.join(projectRoot, '.next', 'static');
-const staticTarget = path.join(standaloneRoot, '.next', 'static');
-
-const copyDirectory = (source, target) => {
-  if (!fs.existsSync(source)) {
-    return false;
-  }
-
-  fs.mkdirSync(path.dirname(target), { recursive: true });
-  fs.rmSync(target, { recursive: true, force: true });
-  fs.cpSync(source, target, { recursive: true });
-  return true;
-};
-
-if (!fs.existsSync(standaloneRoot)) {
-  throw new Error(
-    `Standalone output not found at ${standaloneRoot}. Run \"yarn build\" first.`
-  );
-}
-
-copyDirectory(publicSource, publicTarget);
-copyDirectory(staticSource, staticTarget);

From 1e8751d58b4c4ea76f8ea8eba7d28ecaf25d02b8 Mon Sep 17 00:00:00 2001
From: Paul Ochieng Levi <ochiengpaul442@gmail.com>
Date: Thu, 21 May 2026 21:05:11 +0300
Subject: [PATCH 8/8] Integrate Paddle payment provider; add checkout handling
 and environment configuration

---
 src/platform/.env.example                     |  2 +
 src/platform/src/app/layout.tsx               |  2 +
 .../billing/components/CheckoutDialog.tsx     |  6 +-
 .../components/SubscriptionSection.tsx        | 84 ++++++++++++++++++-
 src/platform/src/shared/lib/paddle.ts         | 13 +++
 .../src/shared/providers/paddle-provider.tsx  | 68 +++++++++++++++
 .../shared/services/subscriptionService.ts    |  8 +-
 src/platform/src/shared/types/paddle.d.ts     | 30 +++++++
 8 files changed, 205 insertions(+), 8 deletions(-)
 create mode 100644 src/platform/src/shared/lib/paddle.ts
 create mode 100644 src/platform/src/shared/providers/paddle-provider.tsx
 create mode 100644 src/platform/src/shared/types/paddle.d.ts

diff --git a/src/platform/.env.example b/src/platform/.env.example
index 4c17dad757..f24b4e5468 100644
--- a/src/platform/.env.example
+++ b/src/platform/.env.example
@@ -42,5 +42,7 @@ NEXT_PUBLIC_PAYMENTS_STANDARD_PRICE_ID=
 PAYMENTS_STANDARD_PRICE_ID=
 NEXT_PUBLIC_PAYMENTS_PREMIUM_PRICE_ID=
 PAYMENTS_PREMIUM_PRICE_ID=
+NEXT_PUBLIC_PAYMENT_CLIENT_TOKEN=
+NEXT_PUBLIC_PAYMENT_ENVIRONMENT=
 
 
diff --git a/src/platform/src/app/layout.tsx b/src/platform/src/app/layout.tsx
index b9c0f080ac..8213c9bc0e 100644
--- a/src/platform/src/app/layout.tsx
+++ b/src/platform/src/app/layout.tsx
@@ -6,6 +6,7 @@ import { Inter } from 'next/font/google';
 import NextTopLoader from 'nextjs-toploader';
 import { ReduxProvider } from '@/shared/providers/redux-provider';
 import { AuthProvider } from '@/shared/providers/auth-provider';
+import PaddleProvider from '@/shared/providers/paddle-provider';
 import { PostHogProvider } from '@/shared/providers/posthog-provider';
 import { GoogleAnalyticsProvider } from '@/shared/providers/google-analytics-provider';
 import { Toaster } from '@/shared/components/ui';
@@ -52,6 +53,7 @@ export default function RootLayout({
         <ReduxProvider>
           <ErrorBoundary>
             <AuthProvider>
+              <PaddleProvider />
               <GoogleAnalyticsProvider>
                 <PostHogProvider>
                   <AppNetworkGate>
diff --git a/src/platform/src/modules/billing/components/CheckoutDialog.tsx b/src/platform/src/modules/billing/components/CheckoutDialog.tsx
index 99c0293112..08562b27b6 100644
--- a/src/platform/src/modules/billing/components/CheckoutDialog.tsx
+++ b/src/platform/src/modules/billing/components/CheckoutDialog.tsx
@@ -35,7 +35,7 @@ const CheckoutDialog: React.FC<CheckoutDialogProps> = ({
           : 'Select a subscription plan'
       }
       primaryAction={{
-        label: loading ? 'Redirecting...' : 'Proceed To Checkout',
+        label: loading ? 'Opening...' : 'Open Checkout',
         onClick: onConfirm,
         disabled: !plan || loading,
         loading,
@@ -51,8 +51,8 @@ const CheckoutDialog: React.FC<CheckoutDialogProps> = ({
       <div className="space-y-4">
         <div className="rounded-lg border border-primary/20 bg-primary/5 p-4">
           <p className="text-sm text-gray-700 dark:text-gray-200">
-            Payments are handled on our provider-hosted checkout page. No card
-            number or CVV is collected in this application.
+            Payments are handled in a secure checkout overlay. No card number or
+            CVV is collected in this application.
           </p>
         </div>
 
diff --git a/src/platform/src/modules/billing/components/SubscriptionSection.tsx b/src/platform/src/modules/billing/components/SubscriptionSection.tsx
index fa7a10f02a..178ab38f87 100644
--- a/src/platform/src/modules/billing/components/SubscriptionSection.tsx
+++ b/src/platform/src/modules/billing/components/SubscriptionSection.tsx
@@ -10,6 +10,7 @@ import React, {
 import { useSession } from 'next-auth/react';
 import { AqCheck } from '@airqo/icons-react';
 import { Button, Card, LoadingSpinner, toast } from '@/shared/components/ui';
+import { PADDLE_CHECKOUT_COMPLETED_EVENT } from '@/shared/lib/paddle';
 import { formatDate } from '@/shared/utils';
 import { subscriptionService } from '@/shared/services/subscriptionService';
 import type {
@@ -22,6 +23,9 @@ import CheckoutDialog from './CheckoutDialog';
 const BILLING_SERVICE_UNAVAILABLE_MESSAGE =
   'Billing service is temporarily unavailable. Please try again later.';
 
+const CHECKOUT_STATUS_POLL_INTERVAL_MS = 2000;
+const CHECKOUT_STATUS_MAX_ATTEMPTS = 6;
+
 interface ExtendedSessionUser {
   _id?: string;
 }
@@ -70,6 +74,11 @@ const getBillingErrorLogMessage = (error: unknown): string => {
   return 'Unknown billing error';
 };
 
+const delay = (milliseconds: number): Promise<void> =>
+  new Promise(resolve => {
+    setTimeout(resolve, milliseconds);
+  });
+
 const SubscriptionSection: React.FC = () => {
   const { data: session } = useSession();
   const [subscription, setSubscription] = useState<UserSubscription | null>(
@@ -149,6 +158,67 @@ const SubscriptionSection: React.FC = () => {
     currentStatus !== 'inactive' &&
     currentStatus !== 'cancelled';
 
+  const syncSubscriptionAfterCheckout = useCallback(async () => {
+    let latestSubscription: UserSubscription | null = null;
+
+    for (
+      let attempt = 0;
+      attempt < CHECKOUT_STATUS_MAX_ATTEMPTS;
+      attempt += 1
+    ) {
+      if (!isMountedRef.current) {
+        return latestSubscription;
+      }
+
+      const response = await subscriptionService.getSubscription();
+
+      if (!response.success) {
+        throw new Error(
+          response.message || 'Failed to refresh subscription status'
+        );
+      }
+
+      latestSubscription = response.subscription ?? null;
+
+      if (isMountedRef.current) {
+        setSubscription(latestSubscription);
+      }
+
+      if (latestSubscription?.status === 'active') {
+        return latestSubscription;
+      }
+
+      if (attempt < CHECKOUT_STATUS_MAX_ATTEMPTS - 1) {
+        await delay(CHECKOUT_STATUS_POLL_INTERVAL_MS);
+      }
+    }
+
+    return latestSubscription;
+  }, []);
+
+  useEffect(() => {
+    const handleCheckoutCompleted = () => {
+      void syncSubscriptionAfterCheckout().catch(error => {
+        console.error(
+          `Checkout sync error: ${getBillingErrorLogMessage(error)}`
+        );
+        toast.error('Payment completed, but the subscription sync failed');
+      });
+    };
+
+    window.addEventListener(
+      PADDLE_CHECKOUT_COMPLETED_EVENT,
+      handleCheckoutCompleted
+    );
+
+    return () => {
+      window.removeEventListener(
+        PADDLE_CHECKOUT_COMPLETED_EVENT,
+        handleCheckoutCompleted
+      );
+    };
+  }, [syncSubscriptionAfterCheckout]);
+
   const handleOpenCheckout = (plan: SubscriptionPlan) => {
     setSelectedPlan(plan);
     setDialogOpen(true);
@@ -184,12 +254,18 @@ const SubscriptionSection: React.FC = () => {
         throw new Error(payload.message || 'Failed to create checkout session');
       }
 
-      const checkoutUrl = payload?.data?.checkoutUrl;
-      if (!checkoutUrl) {
-        throw new Error('Checkout session did not return a redirect URL');
+      const sessionId = payload?.data?.sessionId;
+      if (!sessionId) {
+        throw new Error('Checkout session did not return a Paddle session ID');
+      }
+
+      if (typeof window === 'undefined' || !window.Paddle?.Checkout?.open) {
+        throw new Error('Checkout overlay is unavailable right now');
       }
 
-      window.location.assign(checkoutUrl);
+      window.Paddle.Checkout.open({
+        transactionId: sessionId,
+      });
     } catch (error) {
       console.error(`Checkout error: ${getBillingErrorLogMessage(error)}`);
       toast.error(
diff --git a/src/platform/src/shared/lib/paddle.ts b/src/platform/src/shared/lib/paddle.ts
new file mode 100644
index 0000000000..336edd877d
--- /dev/null
+++ b/src/platform/src/shared/lib/paddle.ts
@@ -0,0 +1,13 @@
+export const PADDLE_SCRIPT_ID = 'paddle-sdk';
+export const PADDLE_SCRIPT_SRC = 'https://cdn.paddle.com/paddle/v2/paddle.js';
+export const PADDLE_CHECKOUT_COMPLETED_EVENT =
+  'airqo:paddle-checkout-completed';
+export const PADDLE_CHECKOUT_CLOSED_EVENT = 'airqo:paddle-checkout-closed';
+
+export const getPaddleEnvironment = (): 'sandbox' | undefined =>
+  process.env.NEXT_PUBLIC_PAYMENT_ENVIRONMENT?.trim() === 'sandbox'
+    ? 'sandbox'
+    : undefined;
+
+export const getPaymentClientToken = (): string =>
+  process.env.NEXT_PUBLIC_PAYMENT_CLIENT_TOKEN?.trim() || '';
diff --git a/src/platform/src/shared/providers/paddle-provider.tsx b/src/platform/src/shared/providers/paddle-provider.tsx
new file mode 100644
index 0000000000..458076d50d
--- /dev/null
+++ b/src/platform/src/shared/providers/paddle-provider.tsx
@@ -0,0 +1,68 @@
+'use client';
+
+import { useCallback, useEffect, useRef } from 'react';
+import Script from 'next/script';
+import {
+  PADDLE_CHECKOUT_CLOSED_EVENT,
+  PADDLE_CHECKOUT_COMPLETED_EVENT,
+  PADDLE_SCRIPT_ID,
+  PADDLE_SCRIPT_SRC,
+  getPaddleEnvironment,
+  getPaymentClientToken,
+} from '@/shared/lib/paddle';
+
+const PaddleProvider = () => {
+  const initializedRef = useRef(false);
+  const paymentClientToken = getPaymentClientToken();
+  const paddleEnvironment = getPaddleEnvironment();
+
+  const initializePaddle = useCallback(() => {
+    if (
+      initializedRef.current ||
+      typeof window === 'undefined' ||
+      !paymentClientToken
+    ) {
+      return;
+    }
+
+    const paddle = window.Paddle;
+    if (!paddle || typeof paddle.Initialize !== 'function') {
+      return;
+    }
+
+    paddle.Initialize({
+      token: paymentClientToken,
+      ...(paddleEnvironment ? { environment: paddleEnvironment } : {}),
+      eventCallback: event => {
+        if (event.name === 'checkout.completed') {
+          window.dispatchEvent(new Event(PADDLE_CHECKOUT_COMPLETED_EVENT));
+        }
+
+        if (event.name === 'checkout.closed') {
+          window.dispatchEvent(new Event(PADDLE_CHECKOUT_CLOSED_EVENT));
+        }
+      },
+    });
+
+    initializedRef.current = true;
+  }, [paddleEnvironment, paymentClientToken]);
+
+  useEffect(() => {
+    initializePaddle();
+  }, [initializePaddle]);
+
+  if (!paymentClientToken) {
+    return null;
+  }
+
+  return (
+    <Script
+      id={PADDLE_SCRIPT_ID}
+      src={PADDLE_SCRIPT_SRC}
+      strategy="afterInteractive"
+      onLoad={initializePaddle}
+    />
+  );
+};
+
+export default PaddleProvider;
diff --git a/src/platform/src/shared/services/subscriptionService.ts b/src/platform/src/shared/services/subscriptionService.ts
index 0c3a6f0b13..2cd4712bb1 100644
--- a/src/platform/src/shared/services/subscriptionService.ts
+++ b/src/platform/src/shared/services/subscriptionService.ts
@@ -72,6 +72,7 @@ interface CheckoutResponse {
   comingSoon?: boolean;
   data?: {
     checkoutUrl?: string;
+    sessionId?: string;
   };
 }
 
@@ -960,7 +961,11 @@ export class SubscriptionService {
         }
       );
 
-      const data = extractEnvelopeData<{ checkoutUrl?: string }>(response.data);
+      const data = extractEnvelopeData<{
+        checkoutUrl?: string;
+        sessionId?: string;
+        session_id?: string;
+      }>(response.data);
 
       return {
         success: true,
@@ -970,6 +975,7 @@ export class SubscriptionService {
         ),
         data: {
           checkoutUrl: data?.checkoutUrl,
+          sessionId: data?.sessionId ?? data?.session_id,
         },
       };
     } catch (error) {
diff --git a/src/platform/src/shared/types/paddle.d.ts b/src/platform/src/shared/types/paddle.d.ts
new file mode 100644
index 0000000000..810971727b
--- /dev/null
+++ b/src/platform/src/shared/types/paddle.d.ts
@@ -0,0 +1,30 @@
+type PaddleCheckoutEvent = {
+  name: string;
+};
+
+interface PaddleCheckoutOpenOptions {
+  transactionId: string;
+}
+
+interface PaddleInitializeOptions {
+  token: string;
+  environment?: 'sandbox';
+  eventCallback?: (event: PaddleCheckoutEvent) => void;
+}
+
+interface PaddleCheckout {
+  open(options: PaddleCheckoutOpenOptions): void;
+}
+
+interface PaddleGlobal {
+  Initialize(options: PaddleInitializeOptions): void;
+  Checkout: PaddleCheckout;
+}
+
+declare global {
+  interface Window {
+    Paddle?: PaddleGlobal;
+  }
+}
+
+export {};