iptvnator/docs/architecture/stalker-portal.md

Stalker Portal Architecture

This document describes the Stalker portal implementation in IPTVnator and where each feature is integrated.

Related Docs

• Stalker Portal EPG Architecture
• Playlist Backup/Restore Architecture
• Portal Detail Navigation
• Embedded Inline Playback
• Remote Control Architecture
• Download Manager
• Category Management
• Stalker Store API Baseline

Scope

Stalker support covers:

• Live TV (itv)
• Radio (radio)
• VOD (vod)
• Series (series)
• VOD-as-series flows (is_series=1 and embedded series[])
• Favorites and recently viewed collections
• Search
• External player playback (shared Xtream player infrastructure)
• Remote control for live ITV navigation

Routing Structure

Primary route tree lives in /Users/4gray/Code/iptvnator/libs/portal/stalker/feature/src/lib/stalker-feature.routes.ts.

• /stalker/:id/vod
• /stalker/:id/series
• /stalker/:id/itv
• /stalker/:id/radio
• /stalker/:id/favorites
• /stalker/:id/recent
• /stalker/:id/search
• /stalker/:id/downloads (shared downloads module from Xtream UI)

Runtime Architecture

1. Angular Stalker screens call methods/resources in StalkerStore.
2. StalkerStore builds request params based on selected content type and current view state.
3. Requests go through DataService.sendIpcEvent(STALKER_REQUEST, ...) or StalkerSessionService (full portal auth).
4. Electron main process handles STALKER_REQUEST in /Users/4gray/Code/iptvnator/apps/electron-backend/src/app/events/stalker.events.ts.
5. Axios calls Stalker load.php API with required headers/cookies and returns normalized payloads to renderer.

Main UI Components

• /Users/4gray/Code/iptvnator/libs/portal/stalker/feature/src/lib/stalker-main-container.component.ts
  • Category + content layout for vod and series
• /Users/4gray/Code/iptvnator/libs/portal/stalker/feature/src/lib/stalker-live-stream-layout/stalker-live-stream-layout.component.ts
  • ITV live playback, radio playback, channel/station navigation, EPG panel integration
• /Users/4gray/Code/iptvnator/libs/ui/playback/src/lib/audio-player/audio-player.component.ts
  • Shared inline audio player used by M3U radio channels and Stalker radio stations
• /Users/4gray/Code/iptvnator/libs/ui/components/src/lib/stalker-series-view/stalker-series-view.component.ts
  • Season/episode UI for all Stalker series modes
• /Users/4gray/Code/iptvnator/libs/portal/stalker/feature/src/lib/stalker-favorites/stalker-favorites.component.ts
• /Users/4gray/Code/iptvnator/libs/portal/stalker/feature/src/lib/recently-viewed/recently-viewed.component.ts
• /Users/4gray/Code/iptvnator/libs/portal/stalker/feature/src/lib/stalker-search/stalker-search.component.ts

Store and Data Flow

Stalker store is now feature-composed:

• Facade: /Users/4gray/Code/iptvnator/libs/portal/stalker/data-access/src/lib/stalker.store.ts
• Feature slices: /Users/4gray/Code/iptvnator/libs/portal/stalker/data-access/src/lib/stores/features/*
• Shared helpers: /Users/4gray/Code/iptvnator/libs/portal/stalker/data-access/src/lib/*

Important store responsibilities:

• Selected content/category/item state
• Category and paginated content resources
• ITV channel list + pagination
• Radio category/station list + pagination
• Regular series seasons resource
• VOD-series (is_series=1) seasons + episodes resources
• Playback link creation (create_link flow)
• Favorites and recently viewed persistence helpers

Internal structure to preserve:

• stalker.store.ts stays as the thin facade that composes feature slices.
• Cross-slice contracts live in stores/stalker-store.contracts.ts so feature dependencies are declared instead of repeated unknown casts.
• Request execution is centralized in stores/utils/stalker-request.utils.ts for both authenticated full-portal calls and simple IPC-backed requests.
• Playback link resolution and Stalker collection persistence live in dedicated stores/utils/ helpers so player/favorites/recent slices stay focused on orchestration.
• Category/content resources stay internal to the store slices. Feature consumers should read getCategoryResource() and getPaginatedContent(), which now always return arrays, and pair them with isCategoryResourceFailed() / isPaginatedContentFailed() for explicit error handling.

Failure-handling rule:

• Failed category or content requests must degrade into empty/error UI state, not undefined collections or renderer exceptions. The workspace Stalker context panel and live layout rely on this guarantee.

Stalker Identity Policy

Full Stalker/Ministra portal authentication defaults to MAC-only identity. The import UI can capture optional serial number, device IDs, and signatures, but blank fields are not generated or forwarded to get_profile.

• User-provided sn, device_id, device_id2, signature, and signature2 values are trimmed, persisted under the canonical stalker* playlist fields, and reused for initial auth, token refresh, retry auth, normal API requests, and same-origin playback headers.
• Empty optional identity fields remain absent. IPTVnator must not generate a device ID from the MAC address or duplicate device_id2 from device_id1.
• The legacy default serial value BEDACD4569BAF is treated as absent at runtime so older blank imports do not keep sending a synthetic serial number.
• Playback headers use the same serial normalization, so the legacy default is not sent as SN or as a serial-derived __cfduid. MAC-only API and playback requests do not synthesize __cfduid; when a real serial is present, same-origin playback uses a canonical 32-character __cfduid protocol cookie.
• Generated MAG-like identity remains a future explicit setting. It must not be the default because strict portals can bind accounts to the first device fingerprint they receive.

Live TV and Radio

The Stalker live route and radio route intentionally share StalkerLiveStreamLayoutComponent:

• itv uses type=itv&action=get_ordered_list, stores results in itvChannels, resolves playback through resolveItvPlayback(...), and keeps the EPG panel visible.
• radio uses type=radio&action=get_ordered_list, stores results in radioChannels, resolves playback through resolveRadioPlayback(...), and renders AudioPlayerComponent instead of a video player.
• Radio hides the EPG panel and must not call Stalker EPG endpoints because radio stations do not have EPG data.
• Radio always uses the inline audio player. External player settings are ignored for Stalker radio, matching M3U radio behavior.
• Radio stations opened from favorites or recently viewed remain live collection items with radio: 'true'; the shared collection resolver uses create_link with type=radio, skips EPG loading, and renders the same AudioPlayerComponent layout instead of the Stalker VOD detail layout.
• Some Stalker portals do not expose radio categories. Radio category loading falls back to a synthetic PORTALS.ALL_RADIO category with category_id: '*' so the station list can still be loaded.

VOD/Series Modes

Stalker has multiple real-world data shapes. The current implementation supports all three:

1. Regular Series (/series):

• Seasons come from API resource (serialSeasonsResource).
• Episodes are derived from season payload.

2. VOD with Embedded series[]:

• Item is opened under VOD, but already contains episodes.
• StalkerSeriesViewComponent creates a pseudo-season and renders episodes directly.

3. VOD with is_series=1 (Ministra plugin behavior):

• Treated as series flow from VOD context.
• Seasons are fetched lazily.
• Episodes are fetched on season select.
• The series quick-start CTA can load the first unloaded VOD-series season before playback. Unloaded seasons are considered unplayed in full season order, so an earlier unloaded season is not skipped just because a later season was loaded manually. If all currently loaded episodes are watched and more season metadata exists, quick start loads the next unloaded season instead of showing the completed state. After a lazy load, quick start is recomputed from the mapped episodes before playback so provider episode ordering cannot start the wrong episode.
• For unloaded VOD-series seasons, the CTA target label is derived from season metadata and rendered as SxxE01 until episode details are loaded.
• Uses unique generated tracking IDs for episode playback position compatibility.

Core decision logic and normalization are centralized in:

• /Users/4gray/Code/iptvnator/libs/portal/stalker/data-access/src/lib/stalker-vod.utils.ts
• /Users/4gray/Code/iptvnator/libs/portal/stalker/data-access/src/lib/models/*.ts

Favorites and Recently Viewed

Current implementation is shared via Stalker-specific helpers:

• createPortalCollectionResource(...) generic collection loader
• createPortalFavoritesResource(...) favorites wrapper
• createStalkerDetailViewState(...) unified "open detail" decision
• toggleStalkerVodFavorite(...) shared add/remove behavior
• normalizeStalkerEntityId(...) and normalizeStalkerEntityIdAsNumber(...) for stable ID matching
• matchesFavoriteById(...) for cross-shape favorite matching

Where this is used:

• /Users/4gray/Code/iptvnator/libs/portal/stalker/feature/src/lib/stalker-favorites/stalker-favorites.component.ts
• /Users/4gray/Code/iptvnator/libs/portal/stalker/feature/src/lib/recently-viewed/recently-viewed.component.ts
• /Users/4gray/Code/iptvnator/libs/portal/stalker/feature/src/lib/stalker-search/stalker-search.component.ts
• /Users/4gray/Code/iptvnator/libs/ui/components/src/lib/stalker-favorites-button/stalker-favorites-button.component.ts

Navigation rule to preserve:

• Stalker favorites, recently viewed, and search stay in their current screen and open inline detail state.
• They should not redirect into a canonical content/category/item route because Stalker detail rendering is currently store-state/inline driven, not route driven.
• Stalker radio favorites/recent items are the exception to VOD/series inline detail opening: they are normalized as live items and must open through the shared live collection audio-player path.
• VOD-backed series favorites can be displayed in series collections, but detail opening must preserve their VOD origin: is_series=1 favorites set the selected content type to vod so the lazy Ministra season/episode resources run, and embedded series[] favorites render through the embedded VOD-series branch.
• See Portal Detail Navigation.

Backup and Restore

Versioned playlist backups include Stalker connection metadata plus playlist- scoped favorites/recent snapshots.

Exported fields:

• portalUrl
• macAddress
• isFullStalkerPortal
• optional username / password
• optional request headers (userAgent, referrer, origin)
• full-portal serial/device/signature fields when present
• favorites and recently viewed collections

Excluded fields:

• stalkerToken
• stalkerAccountInfo
• playback positions in backup v1

Import rule:

• backups restore the saved portal definition and replace the stored favorites/recent state for the matched playlist
• a fresh handshake must happen after import for full-portal sessions; imported backups never trust a serialized token

Remote Control Integration

Stalker live remote control is implemented in:

• /Users/4gray/Code/iptvnator/libs/portal/stalker/feature/src/lib/stalker-live-stream-layout/stalker-live-stream-layout.component.ts

Supported today:

• Channel up/down
• Numeric channel selection (list-position based)
• Status publish for remote UI (portal/channel/current program)

See full backend and web-remote flow in Remote Control Architecture.

EPG Integration

Stalker ITV now splits EPG usage:

• active channel panel: bulk get_epg_info cached once per playlist and rendered through shared app-epg-list
• channel row preview: no pre-playback network requests; previews are derived from cached bulk EPG only after the first active-channel fetch succeeds
• active panel fallback: get_short_epg when bulk EPG is missing or unsupported

Full details are documented in Stalker Portal EPG Architecture.

Shared/Reusable Infrastructure

Stalker reuses some Xtream UI infrastructure deliberately:

• Category content rendering route uses Xtream category content component
• Season container for episodes uses shared Xtream season UI component
• Playback position handling for series episodes reuses Xtream store position mechanisms
• Downloads route reuses shared downloads feature

This reduces duplicate UI logic across portal types and keeps compatibility behavior aligned.

Regression Coverage

Focused regression tests for Stalker VOD mode branching live in:

• /Users/4gray/Code/iptvnator/libs/portal/stalker/data-access/src/lib/stalker-vod.utils.spec.ts

Covered scenarios include:

• Embedded series[] opens series view state
• is_series=1 opens lazy series state
• VOD-backed series favorites keep VOD-series loading semantics when opened from favorites/global favorites
• Favorite toggle helper path invokes the expected add/remove flow