# Open-Source Streaming Reference Conversion

Use this when the user asks to study Kodi add-ons, web movie demos, TMDB apps, or other open-source streaming/catalog projects and "convert" useful ideas into a native Android TV app.

## Clean-room rule

Treat reference repos as architecture/UX/data-flow inspiration unless their license and implementation are both appropriate for direct reuse. Even with permissive/open-source code, prefer reimplementation in the target app's architecture rather than copying modules wholesale.

Safe to convert:

- Catalog taxonomy: row names, category hierarchy, endpoint classes, fallback ordering.
- UX/component boundaries: hero, media row/carousel, card, see-all grid, search-result flow.
- Data-layer patterns: symbolic catalog IDs, endpoint wrappers, request dedupe/cache, row-level loading/error states, pagination guards.
- Source-quality concepts: tags for resolution, WEB/BluRay/HDTV/DVD/REMUX, HDR/Dolby Vision, codec, audio, language, CAM/SCR penalties.

Do not copy without a separate explicit decision:

- Scraper/provider modules, resolver logic, hardcoded endpoints, bundled API keys/tokens, third-party app keys, assets, or credential storage.
- Provider fleets that would bypass the target app's clean add-on/provider contract.
- Decompiled/proprietary code even if behavior is visible.

## Audit sequence

1. Clone/reference-inspect into `/tmp` or another scratch directory, not the target repo.
2. Identify the repo's real data sources before assuming "API-less": official APIs, bundled keys, user tokens, local DB/library calls, web scraping, generated static files, or add-on manifests.
3. Write a clean-room audit doc in `docs/` before implementation.
4. Implement only small, high-value architecture-safe changes first.
5. Build/test after each batch.

## Reference Repo Classes

### Kodi Add-ons (Python)

**Example:** Umbrella (`umbrellaplug/umbrellaplug.github.io`)

Useful as a catalog/source-behavior reference, but their catalogs are not truly API-less. They use TMDB/Trakt/Simkl/MDBList/TVMaze APIs, Kodi JSON-RPC local-library metadata, some IMDb HTML/list scraping, caching layers, and a fallback bundled TMDB key. Reuse only taxonomy/fallback/caching/source-quality ideas. Do not copy provider/scraper modules, resolver internals, bundled keys, or endpoint lists.

### Web Movie Demos (Vue/React/TypeScript)

**Examples:** Nuxt/Movies (`nuxt/movies`), React TMDB apps

Useful for UX/component layout patterns: hero banner structure, carousel hierarchies, proxy patterns, CSS Grid layouts, and LRU caching. These are web apps with server-side proxy layers — adapt the visual layout concepts to Compose for TV, not the framework code. See `references/android-tv-cinematic-ui-patterns.md` for the full Nuxt/Movies → Compose adaptation.

### Electron Desktop Apps (JavaScript/HTML/CSS)

**Example:** Stream-Box (`jonbarrow/stream-box`)

These have no native Android/Kotlin code, but their HTML/CSS contains useful visual patterns: focus ring sizing, scale transforms, row title dividers, nav slider indicators, backdrop dimming, and dark theme values. Extract the visual measurements (px → dp, scale factors, colors) and reimplement in Compose idioms. Never copy HTML/CSS verbatim — the layout model is fundamentally different.

### Decompiled APKs (Smali/Java)

Treat as feature/UX references only. Never copy code, assets, API keys, extractor logic, bundled endpoints, or scraper fleets.

## Follow-on conversion patterns that worked

1. **Declarative catalog registry** — replace hardcoded Home rows with a registry of symbolic catalog definitions.
2. **Stremio-first row fallback** — call addon catalogs first, then native TMDB if addon fails.
3. **Clean-room source-quality scoring** — neutral release tag classification only.
4. **TV UI polish from web references** — adapt concepts, not code.

## API key handling during conversion

Never commit user/API keys into tracked Android source. For Gradle `BuildConfig` keys, place local dev secrets in user-level Gradle properties outside the repo.

## Verification

```bash
./gradlew testDebugUnitTest compileDebugKotlin --console=plain
./gradlew assembleDebug testDebugUnitTest --console=plain
```