# homeflix-tv-app: Android TV Netflix-Style Structure Reference

## Overview
`azad25/homeflix-tv-app` is an open-source Android TV app with a clean Netflix-style UI built in Kotlin/Jetpack Compose. This reference documents its structure for 1:1 adaptation.

## Architecture
- **Language:** Kotlin
- **UI:** Jetpack Compose (Material 3 + TV Foundation)
- **DI:** Hilt
- **Network:** Retrofit + OkHttp + GSON
- **Player:** ExoPlayer 3 (Media3)
- **Images:** Coil
- **Cache:** SharedPreferences (24h TTL) + ContentCache
- **DB:** Room (planned)

## Navigation Structure (5 routes)
```
NavHost(startDestination = "home")
├── home → NetflixHomeScreen
├── search → SearchScreen
├── browse → BrowseScreen
├── my-list → MyListScreen
├── tv-shows → TvShowsScreen
├── details/{type}/{id} → DetailsScreen
├── player/{type}/{id} → VideoPlayerScreen
├── tv-series/{seriesId} → TvSeriesDetailsScreen
└── tv-series/{seriesId}/season/{seasonNumber} → TvSeriesSeasonScreen
```

## Key Components
| Component | File | Description |
|-----------|------|-------------|
| NetflixSideNavigation | NetflixSideNavigation.kt | 48dp sidebar, 5 Material icons, passive focus, red selected indicator |
| NetflixHeroSection | NetflixHeroSection.kt | Auto-sliding hero, crossfade 10s, backdrop + gradient + metadata |
| MediaRow | MediaRow.kt | Horizontal content rows with staggered fade-in animations |
| MediaCard | MediaCard.kt | Poster cards with focus scale + rating overlay |
| ContinueWatchingRow | ContinueWatchingRow.kt | Progress bars, resume functionality |
| VideoPlayer | VideoPlayer.kt | ExoPlayer 3 with custom controls, subtitle rendering |
| TopNavBar | TopNavBar.kt | Top navigation bar with title |

## Color System
```kotlin
val NetflixRed = Color(0xFFE50914)
val NetflixBlack = Color(0xFF000000)
val NetflixDarkGray = Color(0xFF141414)
val NetflixMediumGray = Color(0xFF2F2F2F)
val FocusedBorder = Color(0xFFFFFFFF)
val UnfocusedBorder = Color(0xFF333333)
val TextPrimary = Color(0xFFFFFFFF)
val TextSecondary = Color(0xFFB3B3B3)
val TextTertiary = Color(0xFF808080)
```

## Key UI Patterns
- **Passive focus:** Sidebar never steals focus. D-pad navigates naturally.
- **Focus areas:** Enums (SIDEBAR, HERO, CONTENT) for focus management
- **Staggered animations:** Content rows fade in with staggered delays
- **Crossfade hero:** 10-second auto-rotation with crossfade transitions
- **Genre-based rows:** Trending, Popular, Latest, Action, Drama, Sci-Fi, Horror
- **Continue Watching:** Local progress tracking with resume
- **Search:** Virtual QWERTY keyboard with genre filtering

## What We Copied
- `NetflixSideNavigation` → `NetflixSideNavigation.kt` in NexStream
- Color system → merged with existing NexColors
- Passive focus pattern → applied to new NavRail
- 5-item navigation → Search, Home, Browse, MyList, TV Shows

## What We Kept (NexStream-specific)
- Cloudflare Worker catalog backend (TMDB + MDBList)
- Debrid integration (Real-Debrid, AllDebrid, Premiumize, TorBox)
- Trakt integration
- Stremio addon protocol support
- Profile system
- Settings (progressive disclosure)
- Onboarding