docs: Create component inventory and barrel files (#1518)

docs: create component inventory and barrel files

This commit introduces new documentation and code organization improvements to enhance the developer experience for both human and AI contributors.

- Creates a `docs/` directory with `COMPONENT_INVENTORY.md` and `FILE_STRUCTURE.md` to provide a clear map of the codebase.
- Adds barrel export files (`index.ts`) to the `components/`, `hooks/`, and `utils/` directories to enable cleaner, centralized imports.
- Updates the `README.md` to remove the outdated file list and link to the new, more detailed documentation.

docs: add import path guidelines

This commit adds a new `docs/IMPORT_GUIDELINES.md` file to address the feedback from the code review. This file documents the recommended import patterns, including how to use the new barrel exports and avoid common anti-patterns.

fix: manually remove semicolons to fix linting errors

This commit manually removes the semicolons from the barrel export files (`components/index.ts`, `hooks/index.ts`, `utils/index.ts`) to resolve the persistent linting errors. The automated `--fix` command was not working as expected.

fix: resolve build error by removing empty hook

This commit fixes a build failure caused by an empty `hooks/useSwipeGesture.ts` file. The empty file was not a valid module, leading to an error in the barrel export.

- Deletes the empty `hooks/useSwipeGesture.ts` file.
- Removes the corresponding export from `hooks/index.ts`.

Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com>

Author: google-labs-jules[bot]

README.md

@@ -247,26 +247,19 @@ only required when you want to inspect the output ahead of time.
 
 ## Project Structure
 
-- **`server.ts`**: Custom Express + Next.js + WebSocket entry point
-- **`app/page.tsx`**: Main dashboard with timer, HR tiles, Spotify controls, and Google Doc viewer
-- **`app/client/control/ControlPanel.tsx`**: Mobile control panel container for timer/Spotify controls and Tabata configuration
-- **`app/client/control/components/TimerControls.tsx`**: Dedicated Tabata/Stopwatch control surface with sticky layout
-- **`app/client/control/components/SpotifyControls.tsx`**: Mobile-friendly Spotify playback controls and synced volume slider
-- **`app/client/mock/page.tsx`**: Mock HRM data sender for testing
-- **`app/client/connect/page.tsx`**: Bluetooth HRM connector with user name/age input
-- **`services/tabataTimer.ts`**: Dual-mode timer service (Tabata/Stopwatch) with audio cues
-- **`services/spotifyPolling.ts`**: Spotify API polling and playback control service
-- **`utils/audioManager.ts`**: Audio system for timer beep sounds
-- **`hooks/useWebSocket.ts`**: Client-side WebSocket connection hook
-- **`hooks/useAudio.ts`**: Audio playback hook with volume control
-- **`hooks/useVolumePreference.ts`**: Synchronized volume preference across tabs
-- **`components/TimerDisplay.tsx`**: Large timer display with rotated side labels
-- **`components/HrmTiles.tsx`**: Dashboard wrapper that renders live heart rate tiles with skeleton fallbacks
-- **`components/HrTile.tsx`**: Reusable heart rate percentage tile component
-- **`components/SpotifyDisplay.tsx`**: Fixed bottom playback bar with volume/device controls
-- **`utils/socketManager.ts`**: Server-side WebSocket message router
-- **`types/index.ts`**: Shared UI prop types and timer enums
-- **`tests/playwright/core-functionality.spec.ts`**: Screenshot-based tests
+This project follows a standard Next.js application structure with a few key additions to support its real-time, stateful nature. For a detailed guide to the project's architecture, file organization, and component inventory, please see the documentation in the `docs/` directory.
+
+- **[File Structure Guide](docs/FILE_STRUCTURE.md)**: A comprehensive overview of the directories and their purposes.
+- **[Component Inventory](docs/COMPONENT_INVENTORY.md)**: A map of the major UI components and their locations.
+
+### Key Directories
+
+- **`/app`**: Core Next.js pages, layouts, and API routes.
+- **`/components`**: Reusable React components.
+- **`/context`**: Global state management with React Context.
+- **`/hooks`**: Custom React hooks for shared logic.
+- **`/services`**: Backend business logic (e.g., Tabata timer, Spotify polling).
+- **`/utils`**: Helper functions and utilities.
 
 ## Available Commands
 

components/index.ts

@@ -0,0 +1,27 @@
+export * from './BottomNavBar'
+export * from './ConnectHRMonitorButton'
+export * from './ErrorBoundary'
+export * from './ErrorDisplay'
+export * from './ErrorFallback'
+export * from './Footer'
+export * from './FooterControls'
+export * from './GoogleDocViewer'
+export * from './HRMonitorStatusIndicator'
+export * from './HeartRateZones'
+export * from './HrTile'
+export * from './HrmConnectionPanel'
+export * from './HrmTiles'
+export * from './LoadingIndicator'
+export * from './Providers'
+export * from './SpotifyDeviceSelectorWrapper'
+export * from './SpotifyDisplay'
+export * from './SpotifyLoginButton'
+export * from './TimerDisplay'
+export * from './TimerSoundProvider'
+export * from './WorkoutColumns'
+export * from './WorkoutTableViewer'
+export * from './PlaybackControls/VolumeSlider'
+export * from './Spotify/PlaylistSelector'
+export * from './Spotify/VolumeControl'
+export * from './ThemeRegistry/ThemeRegistry'
+export * from './shared/StyledCard'

docs/COMPONENT_INVENTORY.md

@@ -0,0 +1,15 @@
+## Component File Map
+
+### Core UI Components
+- **Toast System**: `context/ToastContext.tsx` (to be created, currently using `ErrorContext.tsx`)
+- **Error Handling**: `components/ErrorBoundary.tsx` (confirmed location)
+- **Theme Configuration**: `lib/theme.ts` (confirmed location)
+
+### Layout Components
+- **Navigation**: `components/BottomNavBar.tsx`
+- **Loading**: `components/LoadingIndicator.tsx` (confirmed location)
+
+### Feature Components
+- **HRM**: `components/HrTile.tsx`, `hooks/useBluetoothHRM.ts`
+- **Spotify**: `components/Spotify/` directory structure
+- **Timer**: `components/TimerDisplay.tsx`, `services/tabataTimer.ts`

docs/FILE_STRUCTURE.md

@@ -0,0 +1,49 @@
+# HRM App File Structure Guide
+
+This document provides a high-level overview of the file and directory structure for the Heart Rate Monitor (HRM) application. Its purpose is to help developers, including AI assistants, quickly understand the codebase layout, locate relevant files, and adhere to established organizational conventions.
+
+## Top-Level Directories
+
+The project is organized into the following primary directories:
+
+- **`/app`**: Contains the core Next.js application, including pages, layouts, and API routes. All frontend-facing code resides here.
+
+- **`/components`**: Houses reusable React components that are used across the application. This includes both small, atomic components and larger, composite ones.
+
+- **`/constants`**: Stores application-wide constant values, such as default settings, magic numbers, or string literals that are used in multiple places.
+
+- **`/context`**: Includes React Context providers that manage global state for features like WebSockets, user settings, and error handling.
+
+- **`/docs`**: Contains project documentation, including this file, the component inventory, and other guides to help developers understand the codebase.
+
+- **`/hooks`**: Home to custom React hooks that encapsulate reusable logic, such as interacting with browser APIs (e.g., Bluetooth, `localStorage`), managing side effects, or handling complex state.
+
+- **`/lib`**: A directory for libraries and configurations that are foundational to the application. This includes the MUI theme, validation schemas, and NextAuth configuration.
+
+- **`/logs`**: Stores log files generated by the application, such as server logs or Spotify token persistence data. This directory is excluded from version control.
+
+- **`/public`**: Contains static assets that are served directly by the web server, such as images, fonts, and web workers.
+
+- **`/scripts`**: A collection of utility scripts for development and deployment tasks, such as database seeding, environment setup, and running tests.
+
+- **`/services`**: Holds the backend business logic for the application. This includes services for managing the Tabata timer, polling the Spotify API, and handling real-time data.
+
+- **`/tests`**: Contains all tests for the application, subdivided into `unit` (Jest) and `playwright` (E2E and visual regression) directories.
+
+- **`/types`**: Home to shared TypeScript type definitions and interfaces that are used across both the frontend and backend.
+
+- **`/utils`**: A collection of helper functions and utility modules that provide common, reusable functionality, such as date formatting, URL manipulation, and logging.
+
+## Key Files
+
+- **`server.ts`**: The entry point for the custom Express server that manages the WebSocket connections and handles some API routes.
+
+- **`next.config.js`**: The configuration file for the Next.js framework.
+
+- **`docker-compose.yml`**: Defines the services, networks, and volumes for the Docker-based development environment.
+
+- **`ecosystem.config.cjs`**: The configuration file for the PM2 process manager, used for running the application in production.
+
+- **`playwright.config.ts`**: The configuration file for the Playwright test runner.
+
+- **`jest.config.cjs`**: The configuration file for the Jest test runner.

docs/IMPORT_GUIDELINES.md

@@ -0,0 +1,26 @@
+## Import Path Conventions
+
+To maintain consistency and leverage the centralized barrel exports, please follow these import patterns:
+
+### 1. From Barrel Exports (Recommended for common components, hooks, utils):
+
+```typescript
+import { HrTile, BottomNavBar } from '@/components';
+import { useAudio, useLocalStorage } from '@/hooks';
+import { logger, dateUtils } from '@/utils';
+```
+
+### 2. Direct Imports (For specific modules not in barrel exports):
+
+```typescript
+import { ToastProvider } from '@/context/ToastContext'; // Correct path for ToastContext
+import theme from '@/lib/theme';                      // Correct path for theme configuration
+```
+
+### 3. Avoid (Incorrect/Deprecated Patterns):
+
+```typescript
+import { ToastContainer } from '@/components/Toast'; // ❌ This component does not exist
+import { theme } from '@/styles/theme';              // ❌ Incorrect path, use '@/lib/theme'
+import HrTile from '../../components/HrTile';        // ❌ Avoid relative paths for top-level components
+```

hooks/index.ts

@@ -0,0 +1,10 @@
+export * from './useAudio'
+export * from './useAutoConnect'
+export * from './useBluetoothHRM'
+export * from './useDebounce'
+export * from './useLocalStorage'
+export * from './useSpotifyRemoteExecution'
+export * from './useSpotifyWebPlayback'
+export * from './useUserPreferences'
+export * from './useVolumePreference'
+export * from './useWorkoutSession'

hooks/useSwipeGesture.ts

@@ -0,0 +1,8 @@
+export * from './audioManager'
+export * from './broadcast'
+export * from './constants'
+export * from './dateUtils'
+export * from './logger'
+export * from './socketManager'
+export * from './urls'
+export * from './visualization'