feat: implement production-ready web client and Google OAuth authentication

BREAKING CHANGES:
- Renamed 'backend' directory to 'server' across entire codebase
- Updated all documentation references from backend to server

Frontend Implementation (Next.js 15 + React 19):
- Built complete responsive web application with 165+ new files
- Implemented landing page with hero section, features showcase, and platform cards
- Created comprehensive UI component library using shadcn/ui (40+ components)
- Added animated gradient backgrounds, theme toggling, and shader effects
- Implemented dark/light mode support with theme persistence

Authentication & Authorization:
- Integrated Google OAuth 2.0 with Passport strategy
- Added OAuth callback handling with JWT token generation
- Created auth guards (GoogleAuthGuard) and DTOs (OAuthDto)
- Built complete auth UI with sign-in, sign-up, and forgot password flows
- Implemented protected routes with auth state management using Zustand
- Added comprehensive Google OAuth setup documentation

Contest Management UI:
- Created contest browsing interfaces (list, grid, detail views)
- Implemented real-time countdown timers for upcoming contests
- Added advanced filtering by platform, difficulty, type, and status
- Built contest search functionality with debouncing
- Created platform and difficulty badge components
- Added contest statistics charts and analytics visualization

Dashboard & User Features:
- Implemented user dashboard with widgets and quick actions
- Created profile management with tabs (Profile, Preferences, Security)
- Built notification center with filters, stats, and real-time updates
- Added user preference forms for notification channels and timing
- Implemented account deletion with confirmation dialogs

Admin Panel:
- Created admin layout with navigation and role-based access
- Built user management table with search and filtering
- Implemented contest sync panel for platform synchronization
- Added email composer for custom, bulk, and announcement emails
- Created admin settings page with system configuration

API Integration & State Management:
- Implemented complete API client with axios and request interceptors
- Added React Query for server state management and caching
- Created Zustand stores for auth and UI state
- Built type-safe service layers (auth, contests, notifications, users, admin)
- Implemented comprehensive TypeScript types matching server API schema
- Added automatic token refresh and error handling

Server Enhancements:
- Added 10 new notification endpoints (test channels, email operations)
- Enhanced contest controller with health check endpoint
- Implemented Google OAuth endpoints (/auth/google, /auth/google/callback)
- Added comprehensive environment configuration (.env.example)
- Updated config module for Google OAuth and frontend URL support
- Enhanced JWT payload and user schema for OAuth integration

Documentation:
- Created detailed Google OAuth setup guide (GOOGLE_OAUTH_SETUP.md)
- Added comprehensive UI structure documentation (UI_STRUCTURE.md)
- Migrated all backend documentation to server directory
- Updated 150+ documentation files with server references
- Enhanced API documentation with new endpoints
- Improved deployment and configuration guides

Development Experience:
- Configured Next.js 15 with TypeScript strict mode
- Set up Tailwind CSS 4 with custom configuration
- Added ESLint configuration for code quality
- Integrated PostCSS for CSS processing
- Added proper .gitignore for Next.js projects
- Set up comprehensive package.json with all dependencies

Dependencies Added:
- Frontend: next@15, react@19, react-hook-form, zod, zustand, @tanstack/react-query
- UI: tailwindcss@4, framer-motion, lucide-react, recharts
- Server: @nestjs/passport, passport-google-oauth20, passport types

Testing:
- Added comprehensive unit tests for Google OAuth strategy
- Enhanced auth service and controller test coverage
- Added test utilities for OAuth flows

Fixes:
- Fixed minor bugs from previous commits
- Corrected documentation UI inconsistencies
- Resolved user schema validation issues
- Fixed contest schema typing errors

Author: Celestial-0

client/web/UI_STRUCTURE.md

@@ -0,0 +1,123 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { useRouter } from "next/navigation";
+import { Loader2, CheckCircle, XCircle } from "lucide-react";
+import { toast } from "sonner";
+
+import { AuthService } from "@/lib/api/auth.service";
+import { useAuthStore } from "@/lib/store/auth-store";
+import { UserService } from "@/lib/api/user.service";
+
+type CallbackStatus = "loading" | "success" | "error";
+
+export default function OAuthCallbackPage() {
+  const router = useRouter();
+  const { setUser, setError } = useAuthStore();
+  const [status, setStatus] = useState<CallbackStatus>("loading");
+  const [errorMessage, setErrorMessage] = useState<string>("");
+
+  useEffect(() => {
+    const handleCallback = async () => {
+      try {
+        // Handle the OAuth callback - extract tokens from URL
+        const result = AuthService.handleOAuthCallback();
+
+        if (!result.success) {
+          setStatus("error");
+          setErrorMessage(result.error || "Authentication failed");
+          setError(result.error || "Authentication failed");
+          toast.error("Authentication failed", {
+            description: result.error || "Could not complete Google sign in",
+          });
+          
+          // Redirect to signin page after a delay
+          setTimeout(() => {
+            router.push("/auth/signin");
+          }, 3000);
+          return;
+        }
+
+        // Fetch user profile with the new tokens
+        try {
+          const userProfile = await UserService.getProfile();
+          setUser(userProfile);
+          
+          setStatus("success");
+          toast.success("Welcome!", {
+            description: `Signed in as ${userProfile.email}`,
+          });
+
+          // Redirect to dashboard
+          setTimeout(() => {
+            router.push("/dashboard");
+          }, 1500);
+        } catch (profileError) {
+          console.error("Failed to fetch user profile:", profileError);
+          // Even if profile fetch fails, tokens are stored, redirect to dashboard
+          setStatus("success");
+          toast.success("Signed in successfully!");
+          
+          setTimeout(() => {
+            router.push("/dashboard");
+          }, 1500);
+        }
+      } catch (error) {
+        console.error("OAuth callback error:", error);
+        setStatus("error");
+        const message = error instanceof Error ? error.message : "Authentication failed";
+        setErrorMessage(message);
+        setError(message);
+        
+        toast.error("Authentication failed", {
+          description: message,
+        });
+
+        setTimeout(() => {
+          router.push("/auth/signin");
+        }, 3000);
+      }
+    };
+
+    handleCallback();
+  }, [router, setUser, setError]);
+
+  return (
+    <div className="flex min-h-screen items-center justify-center bg-background">
+      <div className="flex flex-col items-center gap-4 text-center">
+        {status === "loading" && (
+          <>
+            <Loader2 className="h-12 w-12 animate-spin text-primary" />
+            <h1 className="text-2xl font-semibold">Completing sign in...</h1>
+            <p className="text-muted-foreground">
+              Please wait while we authenticate your account
+            </p>
+          </>
+        )}
+
+        {status === "success" && (
+          <>
+            <CheckCircle className="h-12 w-12 text-green-500" />
+            <h1 className="text-2xl font-semibold">Sign in successful!</h1>
+            <p className="text-muted-foreground">
+              Redirecting you to the dashboard...
+            </p>
+          </>
+        )}
+
+        {status === "error" && (
+          <>
+            <XCircle className="h-12 w-12 text-destructive" />
+            <h1 className="text-2xl font-semibold">Sign in failed</h1>
+            <p className="text-muted-foreground max-w-md">
+              {errorMessage || "An error occurred during authentication"}
+            </p>
+            <p className="text-sm text-muted-foreground">
+              Redirecting you back to sign in...
+            </p>
+          </>
+        )}
+      </div>
+    </div>
+  );
+}

client/web/app/auth/callback/page.tsx

@@ -1,5 +1,39 @@
-import { ReactNode } from "react";
+"use client";
+
+import { ReactNode, useEffect } from "react";
+import { Activity } from "react";
+import { useAuthStore } from "@/lib/store/auth-store";
+import { useRouter } from "next/navigation";
 
 export default function AuthLayoutPage({ children }: { children: ReactNode }) {
+  const { isAuthenticated, isLoading, initialize } = useAuthStore();
+  const router = useRouter();
+
+  useEffect(() => {
+    // ensure store initializes auth state on mount
+    initialize();
+  }, [initialize]);
+
+  useEffect(() => {
+    if (!isLoading && isAuthenticated) {
+      router.replace("/dashboard");
+    }
+  }, [isAuthenticated, isLoading, router]);
+
+  if (isLoading) {
+    return (
+      <div className="min-h-screen flex items-center justify-center">
+        <div className="flex items-center gap-2 text-muted-foreground">
+          <Activity>Checking your session…</Activity>
+        </div>  
+      </div>
+    );
+  }
+
+  if (isAuthenticated) {
+    // Render nothing while redirecting
+    return null;
+  }
+
   return <>{children}</>;
 }

client/web/app/auth/layout.tsx

@@ -6,8 +6,16 @@ import { Button } from '@/components/ui/button';
 import { ArrowLeft, Calendar, ExternalLink } from 'lucide-react';
 import { useContest } from '@/lib/hooks/use-contests';
 import { Skeleton } from '@/components/ui/skeleton';
-import { format } from 'date-fns';
+import { format, isValid } from 'date-fns';
 import { PLATFORM_CONFIG } from '@/lib/types/contest.types';
+import { downloadContestICS } from '@/lib/utils';
+
+// Helper function to safely format dates
+const formatDate = (date: Date | string | undefined, formatStr: string, fallback = 'TBD'): string => {
+  if (!date) return fallback;
+  const dateObj = typeof date === 'string' ? new Date(date) : date;
+  return isValid(dateObj) ? format(dateObj, formatStr) : fallback;
+};
 
 export default function ContestDetailPage() {
   const params = useParams();
@@ -22,58 +30,9 @@ export default function ContestDetailPage() {
   } = useContest(contestId);
 
   // Generate ICS file for calendar
-  const generateICS = () => {
+  const handleAddToCalendar = () => {
     if (!contest) return;
-
-    const startTime = new Date(contest.startTime);
-    const endTime = new Date(contest.endTime);
-
-    const formatDate = (date: Date) => {
-      return date
-        .toISOString()
-        .replace(/[-:]/g, '')
-        .replace(/\.\d{3}/, '');
-    };
-
-    const icsContent = [
-      'BEGIN:VCALENDAR',
-      'VERSION:2.0',
-      'PRODID:-//CodeNotify//Contest Calendar//EN',
-      'CALSCALE:GREGORIAN',
-      'METHOD:PUBLISH',
-      'X-WR-CALNAME:CodeNotify Contests',
-      'X-WR-TIMEZONE:UTC',
-      'BEGIN:VEVENT',
-      `DTSTART:${formatDate(startTime)}`,
-      `DTEND:${formatDate(endTime)}`,
-      `DTSTAMP:${formatDate(new Date())}`,
-      `UID:${contest.id}@codenotify.app`,
-      `SUMMARY:${contest.name}`,
-      `DESCRIPTION:${contest.platform} Contest\\n${contest.description || ''}\\n\\nRegistration: ${contest.registrationUrl || contest.websiteUrl || 'N/A'}`,
-      `LOCATION:${contest.websiteUrl || 'Online'}`,
-      `URL:${contest.websiteUrl || ''}`,
-      'STATUS:CONFIRMED',
-      'SEQUENCE:0',
-      'BEGIN:VALARM',
-      'TRIGGER:-PT30M',
-      'DESCRIPTION:Contest starts in 30 minutes',
-      'ACTION:DISPLAY',
-      'END:VALARM',
-      'END:VEVENT',
-      'END:VCALENDAR',
-    ].join('\r\n');
-
-    const blob = new Blob([icsContent], {
-      type: 'text/calendar;charset=utf-8',
-    });
-    const url = URL.createObjectURL(blob);
-    const link = document.createElement('a');
-    link.href = url;
-    link.download = `${contest.name.replace(/[^a-z0-9]/gi, '_').toLowerCase()}.ics`;
-    document.body.appendChild(link);
-    link.click();
-    document.body.removeChild(link);
-    URL.revokeObjectURL(url);
+    downloadContestICS(contest);
   };
 
   if (isLoading) {
@@ -122,12 +81,17 @@ export default function ContestDetailPage() {
     );
   }
 
-  const platformConfig = PLATFORM_CONFIG[contest.platform];
+  const platformConfig = PLATFORM_CONFIG[contest.platform] ?? {
+    name: contest.platform,
+    color: 'bg-gray-500',
+    textColor: 'text-gray-500',
+    icon: '?',
+  };
 
   return (
-    <div className="min-h-screen bg-background">
+    <div className="bg-background">
       {/* Header */}
-      <div className="border-b bg-background/95 backdrop-blur supports-backdrop-filter:bg-background/60 sticky top-0 z-40">
+      <div className="border-b bg-background/95 backdrop-blur supports-backdrop-filter:bg-background/60 sticky top-16 z-30">
         <div className="container mx-auto px-4 py-6">
           <Button
             variant="ghost"
@@ -143,8 +107,7 @@ export default function ContestDetailPage() {
             <div className="flex-1">
               <div className="flex items-center gap-2 mb-2">
                 <span
-                  className="px-2 py-1 rounded text-xs font-semibold text-white"
-                  style={{ backgroundColor: platformConfig.color }}
+                  className={`px-2 py-1 rounded text-xs font-semibold text-white ${platformConfig.color}`}
                 >
                   {platformConfig.icon} {contest.platform}
                 </span>
@@ -158,13 +121,13 @@ export default function ContestDetailPage() {
                 {contest.name}
               </h1>
               <p className="text-muted-foreground">
-                {format(new Date(contest.startTime), 'PPP p')} -{' '}
-                {format(new Date(contest.endTime), 'p')}
+                {formatDate(contest.startTime, 'PPP p')} -{' '}
+                {formatDate(contest.endTime, 'p')}
               </p>
             </div>
 
             <div className="flex flex-wrap gap-2">
-              <Button onClick={generateICS} variant="outline" size="sm">
+              <Button onClick={handleAddToCalendar} variant="outline" size="sm">
                 <Calendar className="h-4 w-4 mr-2" />
                 Add to Calendar
               </Button>
@@ -199,7 +162,7 @@ export default function ContestDetailPage() {
 
       {/* Contest Details */}
       <div className="container mx-auto px-4 py-6">
-        <ContestDetailView contest={contest} />
+        <ContestDetailView contest={contest} onAddToCalendar={handleAddToCalendar} />
       </div>
     </div>
   );

client/web/app/contests/[id]/page.tsx

@@ -0,0 +1,30 @@
+/**
+ * Contests Layout
+ * Layout for contest pages with navigation
+ * Shows different navbar for authenticated vs unauthenticated users
+ */
+
+"use client";
+
+import { DashboardNavbar } from "@/components/core/dashboard/dashboard-navbar";
+import { Navbar } from "@/components/core/landing/navbar";
+import { ContestsNav } from "@/components/core/contests/contests-nav";
+import { useAuthStore } from "@/lib/store/auth-store";
+
+export default function ContestsLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const { isAuthenticated } = useAuthStore();
+
+  return (
+    <div className="min-h-screen flex flex-col bg-background">
+      {isAuthenticated ? <DashboardNavbar /> : <Navbar />}
+      <ContestsNav />
+      <main className="flex-1">
+        {children}
+      </main>
+    </div>
+  );
+}

client/web/app/contests/layout.tsx

@@ -15,7 +15,8 @@ import type {
   DifficultyLevel,
 } from '@/lib/types/contest.types';
 import { useUIStore } from '@/lib/store/ui-store';
-import { cn } from '@/lib/utils';
+import { cn, downloadContestICS } from '@/lib/utils';
+import { ContestResponseDto } from '@/lib/types/contest.types';
 
 export default function ContestsPage() {
   const [showFilters, setShowFilters] = useState(false);
@@ -95,9 +96,9 @@ export default function ContestsPage() {
   ].filter(Boolean).length;
 
   return (
-    <div className="min-h-screen bg-background">
+    <div className="bg-background">
       {/* Header */}
-      <div className="border-b bg-background/95 backdrop-blur supports-backdrop-filter:bg-background/60 sticky top-0 z-40">
+      <div className="border-b bg-background/95 backdrop-blur supports-backdrop-filter:bg-background/60 sticky top-16 z-30">
         <div className="container mx-auto px-4 py-6">
           <div className="flex flex-col gap-4">
             <div className="flex items-center justify-between">
@@ -158,7 +159,7 @@ export default function ContestsPage() {
               showFilters ? 'block' : 'hidden'
             )}
           >
-            <div className="sticky top-24">
+            <div className="sticky top-40">
               <ContestFilters
                 filters={{
                   platform: query.platform as ContestPlatform | undefined,
@@ -193,6 +194,7 @@ export default function ContestsPage() {
                 onViewChange={handleViewChange}
                 pagination={contestsData?.pagination}
                 onPageChange={(offset) => handlePageChange(Math.floor(offset / (query.limit || 20)) + 1)}
+                onAddToCalendar={(contest: ContestResponseDto) => downloadContestICS(contest)}
               />
             )}
           </main>