Architecture

The frontend is a Next.js 16 application using the App Router with React 19, TypeScript, and Material-UI.

Directory Structure

src/app/
├── layout.tsx          # Root layout: MUI theme, navigation bar
├── page.tsx            # Home page: experiment selection
├── calls.tsx           # Centralized API client (fetch wrappers for the Node API)
├── contexts/           # React contexts
│   └── PageRedirectContext.tsx
├── hooks/              # Custom React hooks
│   └── useWebSocket.ts # WebSocket hook for real-time experiment updates
├── components/         # Shared UI components
│   ├── Whobit.tsx      # Animated character that guides users
│   ├── HeaderBar.tsx   # Top navigation bar
│   └── ...
├── chsh/               # CHSH Bell test experiment (pages 1–3)
├── qf/                 # Quantum Fortune (pages 1–2)
├── qkd/                # Quantum Key Distribution
├── ssm/                # Secret Message Sharing (pages 1–4)
├── survey/             # Post-experiment user feedback
└── about/              # Project information page

Design Patterns

Page Layout

Each experiment page follows a consistent two-column layout:

• Left: Whobit character with step-by-step instructions

• Right: Interactive content (buttons, results, visualizations)

API Communication

All calls to the Node API are centralized in calls.tsx. This file exports typed functions for each endpoint, keeping API logic out of UI components.

Real-Time Updates

Experiment results are streamed from the backend via WebSocket. The useWebSocket hook in hooks/ manages the connection lifecycle and delivers updates to components.

Multi-Page Experiments

Multi-step experiments (e.g., CHSH has 3 pages, SSM has 4 pages) use PageRedirectContext to track progress and navigate between steps while preserving experiment state.

Key Technologies

Technology	Version	Purpose
Next.js	16	React framework with App Router
React	19	UI rendering
TypeScript	—	Type safety
Material-UI	—	Component library and theming