# Umbrella Add-on — Catalog Architecture Analysis

**Date:** 2026-05-21  
**Repo:** https://github.com/umbrellaplug/umbrellaplug.github.io  
**Analyzed:** `piers/plugin.video.umbrella/resources/lib/modules/`

## Key Finding: Umbrella Is NOT API-Less

The common assumption that umbrellaplug "gets catalogs without an API" is false. Umbrella uses standard REST APIs extensively:

### API Sources Used

| API | Module | Auth Method | Notes |
|-----|--------|-------------|-------|
| TMDB v4 | `tmdb4.py` | Bearer token (user auth) | Full OAuth flow with QR code polling, access + read tokens |
| Trakt | `trakt.py` | OAuth2 Bearer token | Full user auth with client ID, token refresh, scrobble |
| MDBList | `mdblist.py` | Bearer token + embedded client ID | Hardcoded client ID: `YVFS6WW6GT4c2LvaHxHGa8YlB6u9zGgL6KjtDsHg` |
| Simkl | `simkl.py` | OAuth2 device flow | Client ID: `cecec23773dff71d940876860a316a4b74666c4c31ad719fe0af8bb3064a34ab` |
| TVMaze | `tvmaze.py` | None (free API) | Show/episode lookup, no key needed |
| TVDB | `tvmaze.py` | API key (user-configured) | Used for `thetvdb.com` episode absolute numbering |
| IMDb | `client.py` (via tools) | HTML scraping | No API — scrapes IMDb for fallback data |

### The "Catalog Magic" Revealed

Umbrella's catalog menu system works by:

1. **Multi-source aggregation** — Each menu section queries a different API (TMDB for trending, Trakt for watchlist, MDBList for community lists, Simkl for alt tracking)
2. **Local SQLite caching** — Every API response is cached in Kodi's local SQLite DB (`database/cache`, `database/traktsync`, `database/simklsync`, `database/mdbsync`)
3. **Unified menu rendering** — All sources merged into Kodi's native list view via `control.addDirectoryItem()` calls
4. **User-configured fallback** — Users provide their own API keys for TMDB v4, Trakt, MDBList; the addon bundles default keys as fallback

### Architectural Pattern (Clean-Room Adaptation)

The pattern worth adapting for NexStream:

1. **Multi-source aggregation with server-side key protection** — Use the Cloudflare Worker as the aggregation layer, keeping all API keys server-side
2. **Local response caching with TTL** — Edge cache on Cloudflare (already implemented) + optional Android-side Room cache
3. **Declarative row registry** — Map catalog IDs to API sources in a single registry (already in `TmdbCatalogRepository`)
4. **Graceful degradation** — Each source fails independently; show what loaded, retry what failed

### What NOT to Copy

- Umbrella's embedded API keys (MDBList client ID, Simkl client ID)
- Umbrella's scraper/provider source code or endpoint URLs
- Umbrella's Kodi-specific view/skin code (`views.py`)
- Any decompiled provider internals

### Useful Taxonomy to Adapt

Umbrella's menu organization is informative:
- **Movies:** Trending, Popular, Top Rated, Now Playing, Upcoming, By Genre, By Year, By Network
- **TV:** Trending, Popular, Top Rated, On the Air, By Genre, By Network, By Year
- **My Lists:** Trakt Watchlist, Trakt Collection, Trakt History, MDBList Lists, Simkl Lists
- **Discover:** People, Keywords, Networks, Genres, Years

The taxonomy (not the code) can inform NexStream's catalog row registry.