OrionTV/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

OrionTV is a React Native TVOS application for streaming video content, built with Expo and designed specifically for TV platforms (Apple TV and Android TV). This is a frontend-only application that connects to external APIs and includes a built-in remote control server for external device control.

## Key Commands

### Development Commands

#### TV Development (Apple TV & Android TV)
- `yarn start-tv` - Start Metro bundler in TV mode (EXPO_TV=1)
- `yarn android-tv` - Build and run on Android TV
- `yarn ios-tv` - Build and run on Apple TV
- `yarn prebuild-tv` - Generate native project files for TV (run after dependency changes)
- `yarn build-tv` - Build Android APK for TV release

#### Mobile/Tablet Development (Responsive)
- `yarn start` or `yarn start-mobile` - Start Metro bundler for mobile/tablet
- `yarn android` or `yarn android-mobile` - Build and run on Android mobile/tablet
- `yarn ios` or `yarn ios-mobile` - Build and run on iOS mobile/tablet
- `yarn prebuild` or `yarn prebuild-mobile` - Generate native project files for mobile
- `yarn build` or `yarn build-mobile` - Build Android APK for mobile release

#### General Commands
- `yarn copy-config` - Copy TV-specific Android configurations
- `yarn build-debug` - Build Android APK for debugging
- `yarn lint` - Run linting checks
- `yarn typecheck` - Run TypeScript type checking
- `yarn test` - Run Jest tests with watch mode
- `yarn test-ci` - Run Jest tests for CI with coverage
- `yarn clean` - Clean cache and build artifacts
- `yarn clean-modules` - Reinstall all node modules

## Architecture Overview

### Frontend Structure

- **Expo Router**: File-based routing with screens in `/app` directory
- **State Management**: Zustand stores for global state (`/stores`)
- **TV-Specific Components**: Components optimized for TV remote control interaction
- **Services**: API layer, storage management, remote control server, and update service

### Key Technologies

- React Native TVOS (0.74.x) - TV-optimized React Native with TV-specific events
- Expo SDK 51 - Development platform and tooling
- TypeScript - Type safety throughout with `@/*` path mapping
- Zustand - Lightweight state management
- Expo AV - Video playback functionality

### State Management (Zustand Stores)

- `homeStore.ts` - Home screen content, categories, Douban API data, and play records
- `playerStore.ts` - Video player state, controls, and episode management
- `settingsStore.ts` - App settings, API configuration, and user preferences
- `remoteControlStore.ts` - Remote control server functionality and HTTP bridge
- `authStore.ts` - User authentication state
- `updateStore.ts` - Automatic update checking and version management
- `favoritesStore.ts` - User favorites management

### TV-Specific Features

- Remote control navigation (`useTVRemoteHandler` hook with HWEvent handling)
- TV-optimized UI components with focus management and `.tv.tsx` extensions
- Remote control server for external control via HTTP bridge (`remoteControlService.ts`)
- Gesture handling for TV remote interactions (select, left/right seeking, long press)
- TV-specific assets and icons for Apple TV and Android TV

### Service Layer Architecture

- `api.ts` - External API integration (search, video details, Douban data)
- `storage.ts` - AsyncStorage wrapper for local data persistence
- `remoteControlService.ts` - HTTP server for external device control
- `updateService.ts` - Automatic version checking and APK download
- `tcpHttpServer.ts` - TCP-based HTTP server implementation

## Development Workflow

### Responsive Development Notes

- Use TV commands (`*-tv` variants) with EXPO_TV=1 for TV development
- Use mobile/tablet commands (without EXPO_TV=1) for responsive mobile/tablet development
- Run `yarn prebuild-tv` after adding new dependencies for TV builds
- Run `yarn prebuild-mobile` after adding new dependencies for mobile builds
- Use `yarn copy-config` to apply TV-specific Android configurations (TV builds only)
- Test on both TV devices (Apple TV/Android TV) and mobile devices (phones/tablets)
- TV components require focus management and remote control support
- Mobile/tablet components use touch-optimized responsive design
- The same codebase supports all platforms through responsive architecture

### State Management Patterns

- Use Zustand stores for global state
- Stores follow a consistent pattern with actions and state
- API calls are centralized in the `/services` directory
- Storage operations use AsyncStorage wrapper in `storage.ts`

### Component Structure

- TV-specific components have `.tv.tsx` extensions
- Common components in `/components` directory
- Custom hooks in `/hooks` directory for reusable logic
- TV remote handling is centralized in `useTVRemoteHandler`

## Common Issues

### TV Platform Specifics

- TV apps require special focus management
- Remote control events need careful handling
- TV-specific assets and icons required
- Platform-specific build configurations

### Development Environment

- Ensure Xcode is installed for Apple TV development
- Android Studio required for Android TV development
- Metro bundler must run in TV mode (`EXPO_TV=1`)
- External API servers configured in settings for video content

## File Structure Notes

- `/app` - Expo Router screens and navigation
- `/components` - Reusable UI components (including `.tv.tsx` variants)
- `/stores` - Zustand state management stores
- `/services` - API, storage, remote control, and update services
- `/hooks` - Custom React hooks including `useTVRemoteHandler`
- `/constants` - App constants, theme definitions, and update configuration
- `/assets` - Static assets including TV-specific icons and banners

# important-instruction-reminders

Do what has been asked; nothing more, nothing less.
NEVER create files unless they're absolutely necessary for achieving your goal.
ALWAYS prefer editing an existing file to creating a new one.
NEVER proactively create documentation files (\*.md) or README files. Only create documentation files if explicitly requested by the User.
ALWAYS When plan mode switches to edit, the contents of plan and todo need to be output as a document.