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 - Start Metro bundler in TV mode (EXPO_TV=1)
• yarn android - Build and run on Android TV
• yarn ios - Build and run on Apple TV
• yarn prebuild - Generate native project files for TV (run after dependency changes)
• yarn build - Build Android APK for TV release

Testing Commands

• yarn test - Run Jest tests with watch mode
• yarn test-ci - Run Jest tests for CI with coverage
• yarn test utils - Run tests for specific directory/file pattern
• yarn lint - Run ESLint checks
• yarn typecheck - Run TypeScript type checking

Build and Deployment

• yarn copy-config - Copy TV-specific Android configurations
• yarn build-debug - Build Android APK for debugging
• yarn clean - Clean cache and build artifacts
• yarn clean-modules - Reinstall all node modules

Architecture Overview

Multi-Platform Responsive Design

OrionTV implements a sophisticated responsive architecture supporting multiple device types:

• Device Detection: Width-based breakpoints (mobile <768px, tablet 768-1023px, TV ≥1024px)
• Component Variants: Platform-specific files with .tv.tsx, .mobile.tsx, .tablet.tsx extensions
• Responsive Utilities: DeviceUtils and ResponsiveStyles for adaptive layouts and scaling
• Adaptive Navigation: Different interaction patterns per device type (touch vs remote control)

State Management Architecture (Zustand)

Domain-specific stores with consistent patterns:

• 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

Service Layer Pattern

Clean separation of concerns across service modules:

• api.ts - External API integration with error handling and caching
• storage.ts - AsyncStorage wrapper with typed interfaces
• remoteControlService.ts - TCP-based HTTP server for external device control
• updateService.ts - Automatic version checking and APK download management
• tcpHttpServer.ts - Low-level TCP server implementation

TV Remote Control System

Sophisticated TV interaction handling:

• useTVRemoteHandler - Centralized hook for TV remote event processing
• Hardware Events - HWEvent handling for TV-specific controls (play/pause, seek, menu)
• Focus Management - TV-specific focus states and navigation flows
• Gesture Support - Long press, directional seeking, auto-hide controls

Key Technologies

• React Native TVOS (0.74.x) - TV-optimized React Native with TV-specific event handling
• Expo SDK 51 - Development platform providing native capabilities and build tooling
• TypeScript - Complete type safety with @/* path mapping configuration
• Zustand - Lightweight state management for global application state
• Expo Router - File-based routing system with typed routes
• Expo AV - Video playback with TV-optimized controls

Development Workflow

TV-First Development Pattern

This project uses a TV-first approach with responsive adaptations:

• Primary Target: Apple TV and Android TV with remote control interaction
• Secondary Targets: Mobile and tablet with touch-optimized responsive design
• Build Environment: EXPO_TV=1 environment variable enables TV-specific features
• Component Strategy: Shared components with platform-specific variants using file extensions

Testing Strategy

• Unit Tests: Comprehensive test coverage for utilities (utils/__tests__/)
• Jest Configuration: Expo preset with Babel transpilation
• Test Patterns: Mock-based testing for React Native modules and external dependencies
• Coverage Reporting: CI-compatible coverage reports with detailed metrics

Important Development Notes

• Run yarn prebuild after adding new dependencies for native builds
• Use yarn copy-config to apply TV-specific Android configurations
• TV components require focus management and remote control support
• Test on both TV devices (Apple TV/Android TV) and responsive mobile/tablet layouts
• All API calls are centralized in /services directory with error handling
• Storage operations use AsyncStorage wrapper in storage.ts with typed interfaces

Component Development Patterns

• Platform Variants: Use .tv.tsx, .mobile.tsx, .tablet.tsx for platform-specific implementations
• Responsive Utilities: Leverage DeviceUtils.getDeviceType() for responsive logic
• TV Remote Handling: Use useTVRemoteHandler hook for TV-specific interactions
• Focus Management: TV components must handle focus states for remote navigation
• Shared Logic: Place common logic in /hooks directory for reusability

Common Development Tasks

Adding New Components

1. Create base component in /components directory
2. Add platform-specific variants (.tv.tsx) if needed
3. Import and use responsive utilities from @/utils/DeviceUtils
4. Test across device types for proper responsive behavior

Working with State

1. Identify appropriate Zustand store in /stores directory
2. Follow existing patterns for actions and state structure
3. Use TypeScript interfaces for type safety
4. Consider cross-store dependencies and data flow

API Integration

1. Add new endpoints to /services/api.ts
2. Implement proper error handling and loading states
3. Use caching strategies for frequently accessed data
4. Update relevant Zustand stores with API responses

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.