# Competitor Source Architectures

How different apps find video stream links. All converge on the same core pipeline:

```
scrape/index → debrid resolve → play CDN URL
```

The differences are in execution model, plugin systems, and which layer they own vs delegate.

---

## Kodi Addons (Local Python Scrapers)

### Architecture
- **Video addons** (Seren, Fen, Umbrella) provide the UI and orchestration
- **Provider/scraper packages** (A4kScrapers, Cocoscrapers, EzScrapers) do the actual scraping
- Scrapers are Kodi addons themselves — registered as provider addons exposing a Python API
- The video addon imports them via `xbmcaddon.Addon('provider.addon.id')` and calls their `scrape(query)` function

### Scraping Flow
1. User selects a title → addon gets IMDb/TMDB ID via Trakt or TMDB metadata
2. Addon calls each enabled provider scraper in parallel (Python threads)
3. Scrapers parse 20+ torrent sites (1337x, TPB, TorrentGalaxy, RARBG clones) OR cached torrent indexes
4. Results returned with metadata: magnet link, quality, size, seeds, source site
5. Addon deduplicates by magnet hash, sorts by quality/seeds/cached status
6. For hoster links, a resolver (resolveurl, urlresolver) extracts direct media URLs from shorteners/ad pages

### Debrid Integration
- Send magnet to debrid API → if cached → get direct CDN URL → play
- If not cached → queue download (shown as "uncached")
- Debrid results prioritized over free sources

### Caching
- Local SQLite/JSON cache per IMDb ID with 15-60 minute TTL
- Debrid cache status queried before showing results
- Trakt lists pre-loaded for metadata

### Key Differences from Stremio
| Aspect | Kodi | Stremio |
|--------|------|---------|
| Scraping location | Client-side (Python, local CPU/RAM) | Server-side (HTTP addon services) |
| Performance | Heavy — parallel threads scraping live sites | Light — client only fetches results |
| Plugin model | Python addon modules | HTTP/HTTPS addon endpoints |
| Caching | Addon-specific local caches | Server-side (Torrentio caches per hash) |
| Scraper updates | User must update scraper addon | Addon maintainer updates server |

---

## HDCinema / Cinema HD (Embedded Scrapers)

### Architecture
- Standalone Android app with pre-packaged scraper modules (JS/JSON files embedded in APK)
- Each source = a scraper script targeting a specific streaming site (2embed, vidcloud, vidsrc, upcloud)
- Closed source — no community plugin system
- Scrapers updated by shipping a new APK

### Scraping Flow
1. User selects title → app maps to IMDb/TMDB ID
2. For each enabled source script: builds search URL → extracts response → finds embed page → extracts video URL
3. For torrent sources (YTS, RARBG mirrors): sends magnet/hash to debrid API
4. Results sorted by resolution with debrid links prioritized

### Debrid Integration
- Real-Debrid and AllDebrid fully integrated
- For cached torrents: gets direct CDN URL
- For non-debrid: falls back to free embedded sources (less stable)

### Key Differences from Kodi
| Aspect | HDCinema | Kodi |
|--------|----------|------|
| Scrapers | Pre-packaged in APK | Community addon modules |
| Updates | One APK fixes all | Must update each addon |
| Code | Closed source | Open source |
| Plugin model | None (fixed set of sources) | Full addon ecosystem |
| User control | Enable/disable sources | Full provider priority, custom addons |

---

## DebridStream (Addon/Scraper Architecture — Reverse-Engineered from APK v3.3.1)

> **Important:** The public addon documentation (debridstream.com/addon-documentation) lists addon types like `JSONMagnetAddOn`, `JSONImdbHashAddOn`, etc. but the **actual decompiled APK code** reveals a different config format. The code is authoritative.

### Actual Addon Types (from W2/z3.java)

**1. External Addons (`type: "json_imdb"`)**
- User-configurable URL with `%searchPattern` placeholder
- Response parsed using config-driven field extraction
- Fields: `url`, `jsonResultsKey`, `itemType` (info_hash/http_url), `sizeAttr`, `torrentNameTargetKey`, `httpUrlTargetKey`, `debridProvider`, `searchPattern` (movie + tv)
- No addon auth — just HTTP GET → JSON parse → extract links

**2. Registered Addons (`type: "reg_hash"`)**
- Uses DebridStream's own backend as a proxy
- POSTs a Torrentio-style config (with debrid tokens) to `registerUrl`
- Gets back encrypted config string
- Stream URL: `{baseUrl}/{mode}/{encrypted}/stream/%searchPattern.json`
- Default name: "Mediafusion"

### Key Difference from Public Docs
The public documentation mentions `JSONMagnetAddOn`, `JSONImdbHashAddOn`, etc. but the APK code shows **two actual types** with a unified config format. The public docs may be aspirational or for a different version.

### All Addons Come from Firebase Firestore
- Collection: `addOns` (document per user)
- Field: `addOns` (array of manifest URLs)
- Each URL is fetched (HTTP GET) and parsed as JSON
- The JSON contains one or more addon configs with the format above
- **No hardcoded addon URLs exist in the app**

### Debrid Provider Priority (C1125i.a())
| Provider | Score |
|----------|-------|
| realdebrid | 101 |
| alldebrid | 100 |
| premiumize | 50+ |
| torbox | 1 |
| offcloud | 2 |
| debrider | 3 |

See `references/debridstream-deep-architecture.md` for the complete reverse-engineered pipeline (N2.q scraper flow, U2.f config parser, C1125i quality detection, provider dispatch, remote kill-switch).

---

## Source Aggregators (Our Current Approach)

### Torrentio
- URL: `https://torrentio.strem.fun/stream/{type}/{id}.json`
- Returns: `{streams: [{infoHash, title, fileIdx, ...}]}`
- Best coverage for popular content
- Cloudflare bypass: browser User-Agent required
- Content: torrent index scrapes (1337x, TPB, RARBG, TorrentGalaxy)

### Comet (ElfHosted)
- URL: `https://comet.elfhosted.com/stream/{type}/{id}.json`
- Status: Currently returning 403 Forbidden (Cloudflare/rate limiting)
- Content: Torrentio + MediaFusion + DMM + optional Jackett

### MediaFusion (ElfHosted)
- URL: `https://mediafusion.elfhosted.com/stream/{type}/{id}.json`
- Status: Currently returning 403 Forbidden
- Content: Own scrapers + DMM hash lists

---

## Key Takeaways for Architecture

1. **All approaches converge on the same pipeline:** scrape → debrid resolve → CDN URL
2. **Source diversity matters more than debrid diversity** — more source providers → more hashes → higher chance RD has a cached copy → more results
3. **Our missing piece is source provider diversity** — we only have Torrentio working (Comet/MediaFusion 403). Adding DMM/Zilean hash databases and/or KnightCrawler/Annatar would immediately improve results
4. **A manifest-based addon model** (like Stremio or DebridStream) is the right long-term architecture, but the immediate need is fixing the broken aggregators and adding DMM fallback
5. **Kodi's approach is too heavy for our use case** — running Python scrapers on the client is unnecessary when HTTP-based aggregators exist. But Kodi's caching model (local cache per IMDb ID, 15-60 min TTL) is worth adopting
6. **HDCinema's approach is too closed** — pre-packaged scrapers in APK means every source fix requires a full app update. The Stremio/DebridStream addon model is superior