Architecture

​

Project Structure Overview

src/
├── App.jsx                 # Root component, manages boot/login/desktop screens
├── index.css               # Global styles
├── WinXP/                  # Core desktop environment
│   ├── index.jsx           # Main WinXP desktop component
│   ├── reducer.js          # State management reducer
│   ├── apps/               # Application registry and definitions
│   │   └── index.jsx       # App settings and default states
│   ├── constants/          # Action types and constants
│   │   ├── actions.js      # Action type constants
│   │   └── index.js        # Other constants (FOCUSING, POWER_STATE)
│   ├── Footer/             # Taskbar component
│   ├── Icons/              # Desktop icons component
│   ├── Modal/              # Power off/log off modals
│   └── Windows/            # Window manager component
├── components/             # Reusable UI components
│   ├── BSOD/               # Blue Screen of Death
│   ├── BootScreen/         # Boot animation
│   ├── LoginScreen/        # Login interface
│   ├── WelcomeScreen/      # Welcome animation
│   ├── ShutdownScreen/     # Shutdown animation
│   ├── DashedBox/          # Drag selection box
│   ├── Balloon/            # System tray notifications
│   ├── VolumeSlider/       # Volume control
│   ├── WindowDropDowns/    # Window menu dropdowns
│   └── SubMenu/            # Start menu submenus
├── context/                # React context providers
│   └── VolumeContext.jsx   # Global volume state
├── hooks/                  # Custom React hooks
└── assets/                 # Static assets
    ├── sounds/             # System sounds
    ├── windowsIcons/       # XP icons and images
    ├── userIcons/          # User avatars
    └── minesweeper/        # Minesweeper assets

​

Component Hierarchy

App (Root)
├── VolumeProvider (Context)
│   └── AppLogic
│       ├── BootScreen
│       ├── LoginScreen
│       ├── WelcomeScreen
│       ├── BSOD
│       ├── ShutdownScreen
│       └── WinXP (Desktop Environment)
│           ├── Icons (Desktop Icons)
│           ├── DashedBox (Selection Box)
│           ├── Windows (Window Manager)
│           │   └── [Multiple Window instances]
│           ├── Footer (Taskbar)
│           │   ├── Start Button
│           │   ├── SubMenu (Start Menu)
│           │   ├── App Buttons
│           │   ├── System Tray
│           │   ├── VolumeSlider
│           │   └── Clock
│           └── Modal (Power Options)

​

App Component (Root)

• Screen state management (boot → login → welcome → desktop → shutdown)
• User session tracking (logged out, logged in, active on desktop)
• Sound playback (startup, logon, logoff, shutdown sounds)
• Global error handling (catches errors and displays BSOD)
• Volume context provider wrapper

• screen: Current screen to display ('boot', 'login', 'welcome', 'desktop', 'shuttingDown', 'restarting', 'bsod')
• skillzSessionStatus: User session status tracking
• shutdownMessages: Messages displayed during shutdown
• crashError: Error message for BSOD

​

WinXP Component (Desktop)

• Desktop state management using useReducer
• Window operations (add, close, focus, minimize, maximize)
• Icon selection and interaction
• Drag-to-select functionality
• Start menu item handling
• Power state management (log off, shutdown, restart)

• Uses useMouse from react-use for mouse tracking
• Implements mobile device detection and warnings
• Manages z-index ordering for windows
• Handles desktop click events for deselecting icons

​

Windows Manager

• Window dragging and resizing
• Minimize, maximize, restore, close operations
• Z-index management for window stacking
• Window focus handling
• Per-window header with title and icon

​

Icons Component

• Click to select/focus icons
• Double-click to open applications
• Drag-to-select (rubber band) support
• Focus state visualization
• Icon positioning and layout

​

Footer (Taskbar)

• Start Button: Opens the start menu
• SubMenu: Nested start menu with application shortcuts
• App Buttons: Show running applications, click to minimize/restore
• System Tray: Volume control and clock
• VolumeSlider: Global volume control with mute
• Clock: Displays current time

​

Modal Component

• Log Off: Log off or switch user
• Turn Off: Shutdown, restart, or cancel

​

File Organization Principles

​

WinXP Directory

• Main desktop component (index.jsx)
• State management (reducer.js)
• Application registry (apps/)
• Desktop UI components (Footer/, Icons/, Windows/, Modal/)
• Constants and action types (constants/)

​

Components Directory

• Screen components (Boot, Login, Welcome, Shutdown, BSOD)
• UI utilities (DashedBox, Balloon, VolumeSlider)
• Dropdown menus (WindowDropDowns, SubMenu)

​

Assets Directory

• sounds/: System sound effects (WAV format)
• windowsIcons/: XP-style icons and images
• userIcons/: User avatar images
• minesweeper/: Game-specific assets

​

Tech Stack

​

Core Technologies

• React 18.3.1 - UI framework with hooks
• styled-components 6.1.14 - CSS-in-JS styling solution
• Vite 6.2.0 - Build tool and dev server

​

Key Libraries

• webamp 1.3.2-beta.2 - Winamp player implementation
• react-use 17.6.0 - Collection of React hooks (useMouse, etc.)
• lodash.samplesize 4.2.0 - Random sampling utility

​

Development Tools

• ESLint 8.0.0 - Code linting
• Prettier 1.18.2 - Code formatting
• @vitejs/plugin-react 4.3.4 - Vite React plugin

​

Design Patterns

​

State Management

​

Component Composition

• Container components manage state and logic
• Presentational components handle UI rendering
• Context providers manage global state (volume)

​

Event Handling

• onMouseDown for focus/selection
• onDoubleClick for opening apps
• onClick for menu items and buttons

​

Styling

• Component-scoped styles
• Dynamic styling based on props
• Keyframe animations for transitions
• No global CSS except index.css for resets

​

Mobile Support

const isMobile = () => {
  const userAgent = navigator.userAgent || navigator.vendor || window.opera;
  return (
    /android/i.test(userAgent) ||
    (/iPad|iPhone|iPod/.test(userAgent) && !window.MSStream)
  );
};

• Shows compatibility warning dialog
• Blocks certain apps (Minesweeper, Pinball)
• Adjusts window sizing for smaller screens