Frontend Architecture

The ScoreSaber Reloaded frontend is a modern Next.js 16 application using the App Router architecture with React 19.

Project Structure

projects/website/src/
├── app/                    # Next.js App Router
│   ├── (overlay)/         # Overlay layout group
│   │   └── overlay/       # OBS overlay pages
│   ├── (pages)/           # Main site layout group
│   │   ├── player/        # Player profile pages
│   │   ├── leaderboard/   # Leaderboard pages
│   │   ├── ranking/       # Global rankings
│   │   ├── scores/        # Score listings
│   │   └── settings/      # User settings
│   ├── layout.tsx         # Root layout
│   └── styles/            # Global CSS
├── components/            # React components
│   ├── api/              # API-related components
│   ├── player/           # Player-specific components
│   ├── score/            # Score display components
│   ├── leaderboard/      # Leaderboard components
│   ├── ui/               # Reusable UI components
│   └── providers/        # Context providers
├── common/               # Utilities and helpers
│   ├── database/         # Dexie database
│   ├── chart/            # Chart.js utilities
│   └── player/           # Player utilities
├── hooks/                # Custom React hooks
└── contexts/             # React contexts

Next.js Configuration

From next.config.ts:

const nextConfig: NextConfig = {
  reactStrictMode: true,
  output: "standalone",               // For Docker
  reactCompiler: true,                // React 19 compiler
  experimental: {
    optimizePackageImports: [         // Package-level tree shaking
      "@ssr/common",
      "@tanstack/react-query",
      "chart.js",
      "lucide-react",
      "zustand"
    ]
  },
  images: {
    unoptimized: true                 // Faster builds
  }
};

Routing Strategy

Route Groups

Next.js uses route groups to organize layouts without affecting URLs:

app/
├── (overlay)/           # Minimal layout for OBS overlays
│   └── overlay/page.tsx # URL: /overlay
└── (pages)/             # Main site layout with navigation
    ├── page.tsx         # URL: / (homepage)
    ├── player/[id]/     # URL: /player/76561198449793387
    └── ranking/         # URL: /ranking

Dynamic Routes

Player profiles use dynamic routing:

// app/(pages)/player/[id]/page.tsx
export default async function PlayerPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  
  return <PlayerProfile playerId={id} />;
}

Catch-all Routes

Rankings support optional segments:

// app/(pages)/ranking/[[...slug]]/page.tsx
// Matches: /ranking, /ranking/1, /ranking/global/1

State Management

1. TanStack Query (Server State)

Manages all API data fetching and caching:

// components/providers/query-provider.tsx
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 30,           // 30 seconds
      refetchInterval: 1000 * 60,     // 1 minute
      refetchIntervalInBackground: false,
      retry: true,
      retryDelay: 1000 * 5            // 5 seconds
    }
  }
});

Usage example:

import { useQuery } from '@tanstack/react-query';
import { ssrApi } from '@ssr/common/utils/ssr-api';

function PlayerProfile({ playerId }: { playerId: string }) {
  const { data: player, isLoading } = useQuery({
    queryKey: ['player', playerId],
    queryFn: () => ssrApi.getScoreSaberPlayer(playerId, 'full'),
    staleTime: 1000 * 60 * 5  // 5 minutes
  });
  
  if (isLoading) return <Loader />;
  return <div>{player.name}</div>;
}

2. Dexie (Client Persistence)

IndexedDB wrapper for offline-first user data:

// common/database/database.ts
export default class Database extends Dexie {
  settings!: EntityTable<Setting, "id">;
  cache!: EntityTable<CacheItem, "id">;

  constructor(before: number) {
    super("ssr");
    
    this.version(1).stores({
      settings: "id",
      cache: "id"
    });
  }
  
  // Get main player from IndexedDB
  async getMainPlayer(): Promise<ScoreSaberPlayer | undefined> {
    const id = await this.getMainPlayerId();
    if (!id) return undefined;
    
    // Check cache (6 hour TTL)
    return this.getCache<ScoreSaberPlayer>(
      `player:${id}`,
      DEFAULT_PLAYER_CACHE_TTL,
      async () => {
        return await ssrApi.getScoreSaberPlayer(id, "basic");
      }
    );
  }
}

Settings stored in Dexie:

Main player ID
Friends list
Background preferences
Overlay settings
Chart legend states

3. Zustand (Global State)

Lightweight state management for UI state:

import { create } from 'zustand';

interface AppState {
  sidebarOpen: boolean;
  toggleSidebar: () => void;
}

export const useAppStore = create<AppState>((set) => ({
  sidebarOpen: false,
  toggleSidebar: () => set((state) => ({ 
    sidebarOpen: !state.sidebarOpen 
  }))
}));

4. React Context

For component-tree scoped state:

// contexts/viewport-context.tsx
export const ViewportProvider = ({ children }: { children: ReactNode }) => {
  const [isMobile, setIsMobile] = useState(false);
  
  useEffect(() => {
    const checkViewport = () => {
      setIsMobile(window.innerWidth < 768);
    };
    
    checkViewport();
    window.addEventListener('resize', checkViewport);
    return () => window.removeEventListener('resize', checkViewport);
  }, []);
  
  return (
    <ViewportContext.Provider value={{ isMobile }}>
      {children}
    </ViewportContext.Provider>
  );
};

Component Architecture

Root Layout

// app/layout.tsx
export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body className={`${siteFont.className} h-full w-full antialiased`}>
        <Toaster />
        <PreloadResources />
        <LazyMotion features={domAnimation} strict>
          <PageTransitionProvider>
            <ViewportProvider>
              <QueryProvider>
                {children}
              </QueryProvider>
            </ViewportProvider>
          </PageTransitionProvider>
        </LazyMotion>
      </body>
    </html>
  );
}

Provider hierarchy:

LazyMotion: Lazy-loads Framer Motion features
PageTransitionProvider: Smooth page transitions
ViewportProvider: Responsive breakpoint detection
QueryProvider: TanStack Query client

Custom Hooks

Reusable logic extraction:

// hooks/use-database.ts
import { getDatabase } from '@/common/database/database';

export function useDatabase() {
  return getDatabase();
}

// hooks/use-background-cover.ts
export function useBackgroundCover() {
  const db = useDatabase();
  const [cover, setCover] = useState<string>("");
  
  useEffect(() => {
    db.getBackgroundCover().then(setCover);
  }, [db]);
  
  const updateCover = async (newCover: string) => {
    await db.setBackgroundCover(newCover);
    setCover(newCover);
  };
  
  return { cover, updateCover };
}

API Integration

All API calls go through the shared @ssr/common package:

// From @ssr/common/utils/ssr-api
export const ssrApi = {
  async getScoreSaberPlayer(id: string, type: DetailType) {
    const response = await axios.get(
      `${env.NEXT_PUBLIC_API_URL}/player/${id}`,
      { params: { type } }
    );
    return response.data;
  },
  
  async getPlayerScores(id: string, page: number) {
    const response = await axios.get(
      `${env.NEXT_PUBLIC_API_URL}/player/${id}/scores`,
      { params: { page } }
    );
    return response.data;
  }
};

Real-time Features

WebSocket Integration

import useWebSocket from 'react-use-websocket';

function LiveScores() {
  const { lastMessage } = useWebSocket('wss://api.ssr.fascinated.cc/scores/live', {
    onMessage: (event) => {
      const score = JSON.parse(event.data);
      console.log('New score:', score);
    },
    shouldReconnect: () => true
  });
  
  return <ScoreList scores={scores} />;
}

Performance Optimizations

1. React Compiler

Automatic memoization eliminates manual useMemo/useCallback:

// Automatically optimized by React Compiler
function ExpensiveComponent({ data }) {
  const processed = processData(data);  // Auto-memoized
  return <Display data={processed} />;
}

2. Code Splitting

Dynamic imports for heavy components:

import dynamic from 'next/dynamic';

const HeavyChart = dynamic(
  () => import('@/components/charts/heavy-chart'),
  { ssr: false, loading: () => <Loader /> }
);

3. Image Optimization

import Image from 'next/image';

<Image
  src={player.avatar}
  alt={player.name}
  width={128}
  height={128}
  priority={true}  // LCP optimization
/>

Styling

Tailwind CSS

Utility-first styling with v4:

<div className="flex items-center gap-4 rounded-lg bg-card p-4 shadow-md">
  <Avatar src={player.avatar} />
  <div>
    <h2 className="text-xl font-bold">{player.name}</h2>
    <p className="text-muted-foreground">Rank #{player.rank}</p>
  </div>
</div>

Radix UI Components

Accessible primitives with custom styling:

import * as Dialog from '@radix-ui/react-dialog';

function SettingsModal() {
  return (
    <Dialog.Root>
      <Dialog.Trigger>Settings</Dialog.Trigger>
      <Dialog.Portal>
        <Dialog.Overlay className="fixed inset-0 bg-black/50" />
        <Dialog.Content className="fixed left-1/2 top-1/2 ...">
          <SettingsForm />
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  );
}

Build Output

Standalone build for Docker:

npm run build

# Produces:
.next/standalone/        # Minimal Node.js server
.next/static/           # Static assets
public/                 # Public files

This creates a self-contained application with all dependencies bundled.

Overview

Core Features

Integrations

Architecture

Project Structure

Next.js Configuration

Routing Strategy

Route Groups

Dynamic Routes

Catch-all Routes

State Management

1. TanStack Query (Server State)

2. Dexie (Client Persistence)

3. Zustand (Global State)

4. React Context

Component Architecture

Root Layout

Custom Hooks

API Integration

Real-time Features

WebSocket Integration

Performance Optimizations

1. React Compiler

2. Code Splitting

3. Image Optimization

Styling

Tailwind CSS

Radix UI Components

Build Output

Build docs developers (and LLMs) love

Overview

Core Features

Integrations

Architecture

​Project Structure

​Next.js Configuration

​Routing Strategy

​Route Groups

​Dynamic Routes

​Catch-all Routes

​State Management

​1. TanStack Query (Server State)

​2. Dexie (Client Persistence)

​3. Zustand (Global State)

​4. React Context

​Component Architecture

​Root Layout

​Custom Hooks

​API Integration

​Real-time Features

​WebSocket Integration

​Performance Optimizations

​1. React Compiler

​2. Code Splitting

​3. Image Optimization

​Styling

​Tailwind CSS

​Radix UI Components

​Build Output

Build docs developers (and LLMs) love

Project Structure

Next.js Configuration

Routing Strategy

Route Groups

Dynamic Routes

Catch-all Routes

State Management

1. TanStack Query (Server State)

2. Dexie (Client Persistence)

3. Zustand (Global State)

4. React Context

Component Architecture

Root Layout

Custom Hooks

API Integration

Real-time Features

WebSocket Integration

Performance Optimizations

1. React Compiler

2. Code Splitting

3. Image Optimization

Styling

Tailwind CSS

Radix UI Components

Build Output