How rdkcentral/lightning-sdk works
1. What this repo is
- Lightning-SDK is a reusable runtime SDK/library for building Lightning-based TV applications, not an app itself.
- It sits on top of the Lightning renderer and packages common app capabilities into installable modules.
2. Top-level architecture
- The code is organized as a set of feature modules under src/, each exposing a small public API through an index.js entrypoint.
- The root index.js and index.d.ts act as the package surface for consumers.
- Most features are independent plugins/utilities rather than a single monolith.
3. Core application bootstrap
- src/startApp.js, src/Application, and src/Launch form the startup path for consumer apps.
- This layer is responsible for wiring the SDK into a Lightning app lifecycle, so other subsystems can be registered and used consistently.
- support/startApp.js and support/index.html suggest a local/demo harness for exercising the SDK in a browser-like environment.
4. Navigation and screen composition
- src/Router is one of the main subsystems and likely the central control-flow boundary.
- It includes route models, history handling, transitions, loaders, provider helpers, and widget/component utilities.
- The router coordinates navigation between app “screens” and can trigger page transitions, deep linking, and history updates.
5. Media and content presentation
- src/VideoPlayer, src/AudioPlayer, src/Img, src/Subtitles, and src/MediaPlayer cover media playback and presentation concerns.
- src/Metadata and src/TV support content/device-specific features around media and television contexts.
- src/Img/ScaledImageTexture indicates image handling is integrated with Lightning textures rather than generic DOM rendering.
6. Accessibility and user experience utilities
- src/Accessibility contains accessibility-related functionality, including announcer logic and color-vision shaders.
- The shader set includes normal, color-shift, monochromacy, protanopia, deuteranopia, and tritanopia modes, so this subsystem can alter visual output for accessibility.
- src/FpsCounter, src/VersionLabel, and src/Log are supporting UI/debug utilities.
7. Platform services and app state
- src/Settings, src/Storage, src/Registry, src/Pin, src/Purchase, and src/Profile represent persistent or account/device-oriented services.
- src/Language and src/Locale handle language/localization concerns.
- src/Ads, src/Metrics, and src/Launch are integration points for monetization, telemetry, and startup behavior.
8. Lightning integration layer
- src/Lightning is the explicit bridge to the Lightning framework, and the README confirms Lightning is bundled into the SDK.
- src/Keyboard, src/Utils, and src/helpers/* provide lower-level shared behavior used across plugins.
- src/Accessibility/Announcer and related helpers show the repo favors reusable internal utilities over duplicated logic inside each plugin.
9. Internal data/control flow
- Consumer app code initializes through the app/bootstrap layer, then registers or configures plugins such as router, media, settings, and storage.
- Runtime events typically flow from input or app state into the router and platform services, then into Lightning UI components/widgets.
- The router and launcher are the main orchestration boundaries; media, accessibility, and storage are feature subsystems that plug into that flow.
10. Types and compatibility
- The repository is primarily JavaScript, but many modules include .d.ts files, so it ships with TypeScript typings for consumers.
- test-d/ contains TypeScript definition tests, which means the public API surface is versioned and type-checked as part of the contract.
11. Docs and developer tooling
- docs/ is a full documentation site with per-plugin pages, especially detailed for the router and accessibility subsystems.
- rollup.config.js, ESLint files, tsconfig.json, and .github/workflows/cla.yml indicate standard library tooling: bundling, linting, type validation, and contribution automation.
- The presence of package-lock.json and scripts/postinstall.js suggests install-time setup is part of the developer experience.
12. How to draw the architecture
- Model this repo as a plugin-based SDK centered on a Lightning app runtime.
- Put Application/Launch/startApp at the top as the entry path.
- Show Router as the central navigation orchestrator.
- Branch out from the core into Media, Accessibility, Localization, State/Persistence, Telemetry/Logging, and Platform integrations.
- Treat Utils and helpers as shared internal support layers rather than standalone features.
Main entry points: Router Router · index.js SDK surface · MediaPlayer Media player · Lightning Lightning
Components 34
Core runtime
Package entrypoints and Lightning app bootstrap.
- SDK surface · Root package API exposed to consumers.
index.js - Types · Package-level TypeScript declarations.
index.d.ts - Start app · Application startup entry for consumer apps.
src/startApp.js - Application · Main application lifecycle integration.
src/Application - Launch · Startup behavior and launch integration.
src/Launch
Navigation
Route handling and screen orchestration.
- Router · Navigation boundary coordinating routes, history, transitions, and deep links.
src/Router - Route model · Route and request data structures.
src/Router/model - Router utils · Provider, loader, widgets, history, and transition utilities.
src/Router/utils - Base router · Core router implementation surface.
src/Router/base.js
Media
Playback, image, subtitles, and content metadata.
- Media player · Shared playback abstraction.
src/MediaPlayer - Video player · Video playback integration.
src/VideoPlayer - Audio player · Audio playback integration.
src/AudioPlayer - Images · Lightning image handling and scaled textures.
src/Img - Subtitles · Subtitle component and rendering support.
src/Subtitles - Metadata · Content metadata integration.
src/Metadata - TV · TV-specific device and platform helpers.
src/TV
Services
State, persistence, identity, monetization, and telemetry.
- Platform services · Persistence, identity, monetization, language, and telemetry services.
- Settings · Application settings integration.
src/Settings - Storage · Persistent storage API.
src/Storage - Registry · Platform or device registry access.
src/Registry - PIN · Parental PIN or access control support.
src/Pin - Purchase · Purchase and entitlement integration.
src/Purchase - Profile · User profile integration.
src/Profile - Language · Language selection support.
src/Language - Locale · Locale formatting and localization helpers.
src/Locale - Ads · Advertising integration.
src/Ads - Metrics · Metrics and reporting integration.
src/Metrics
Accessibility
Assistive features and visual adaptation.
- Accessibility · Accessibility subsystem entrypoint.
src/Accessibility - Announcer · Speech and announcement helpers for accessibility.
src/Accessibility/Announcer - Shaders · Color-vision and monochromacy shader modes.
src/Accessibility/shaders
Shared support
Framework bridge, utilities, and low-level helpers.
Connections 44
- SDK surface → Start app: exports · Package surface exposes the app bootstrap path.
- SDK surface → Router: exports · Package surface exposes navigation APIs.
- SDK surface → Media player: exports · Package surface exposes media capabilities.
- SDK surface → Platform services: exports · Package surface exposes platform services.
- SDK surface → Accessibility: exports · Package surface exposes accessibility features.
- SDK surface → Shared support: exports · Package surface exposes shared framework support.
- SDK surface → Types: types · Type definitions accompany the JavaScript package API.
- Start app → Application: boots · Bootstrap initializes the application lifecycle.
- Start app → Launch: configures · Startup wiring feeds launch behavior.
- Application → Router: registers · Application lifecycle registers navigation subsystems.
- Application → Platform services: wires · Application lifecycle wires in persistent services.
- Launch → Router: coordinates · Launch behavior participates in navigation startup.
- Router → Base router: implements · Core router logic lives in the base implementation.
- Router → Route model: uses · Router relies on request and route models.
- Router → Router utils: uses · Router composition is supported by utility modules.
- Router → Lightning: renders on · Navigation ultimately drives Lightning UI rendering.
- Router utils → Base router: supports · Utilities extend and support the router core.
- Media player → Video player: specializes · Generic media playback is specialized for video.
- Media player → Audio player: specializes · Generic media playback is specialized for audio.
- Media player → Subtitles: coordinates · Media playback can coordinate subtitle rendering.
- Video player → Images: shares · Video and image presentation share Lightning rendering concepts.
- Images → Lightning: uses · Image textures are integrated with Lightning.
- Subtitles → Lightning: uses · Subtitle components render within Lightning.
- Metadata → TV: supports · Metadata and TV subsystems work together for device/content context.
- Accessibility → Announcer: contains · Accessibility includes speech announcement support.
- Accessibility → Shaders: contains · Accessibility includes visual adaptation shaders.
- Announcer → Utils: uses · Announcement logic reuses shared utilities.
- Shaders → Lightning: uses · Shader modes integrate with the Lightning rendering path.
- Platform services → Settings: contains · Settings is a primary platform service.
- Platform services → Storage: contains · Storage is a primary platform service.
- Platform services → Registry: contains · Registry is a primary platform service.
- Platform services → PIN: contains · PIN handling is part of the service layer.
- Platform services → Purchase: contains · Purchase flows are part of the service layer.
- Platform services → Profile: contains · Profile handling is part of the service layer.
- Platform services → Language: contains · Language selection is part of the service layer.
- Platform services → Locale: contains · Locale handling is part of the service layer.
- Platform services → Ads: contains · Advertising integration is part of the service layer.
- Platform services → Metrics: contains · Telemetry integration is part of the service layer.
- Shared support → Lightning: bridges · Support layer includes the Lightning framework bridge.
- Shared support → Utils: shares · Utilities provide common reusable behavior.
- Shared support → Helpers: shares · Helpers provide low-level shared functionality.
- Shared support → Router: supports · Shared utilities underpin the router and other subsystems.
- Shared support → Media player: supports · Shared utilities underpin media subsystems.
- Shared support → Accessibility: supports · Shared utilities underpin accessibility subsystems.