# rdkcentral/lightning-sdk architecture

> Architecture diagram of the GitHub repository rdkcentral/lightning-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rdkcentral/lightning-sdk
- Repository: https://github.com/rdkcentral/lightning-sdk

## Overview

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: [`src/Router`](https://github.com/rdkcentral/lightning-sdk/tree/master/src/Router) (Router), [`index.js`](https://github.com/rdkcentral/lightning-sdk/blob/master/index.js) (SDK surface), [`src/MediaPlayer`](https://github.com/rdkcentral/lightning-sdk/tree/master/src/MediaPlayer) (Media player), [`src/Lightning`](https://github.com/rdkcentral/lightning-sdk/tree/master/src/Lightning) (Lightning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core runtime"]
  node_pkg["SDK surface<br/>package entry<br/>[index.js]"]
  node_types["Types<br/>typing surface<br/>[index.d.ts]"]
  node_startapp["Start app<br/>bootstrap<br/>[startApp.js]"]
  node_application["Application<br/>app lifecycle"]
  node_launch["Launch<br/>startup hook"]
end

subgraph group_router["Navigation"]
  node_router["Router<br/>navigation core"]
  node_route_model["Route model<br/>routing model"]
  node_route_utils["Router utils<br/>routing helpers"]
  node_route_base["Base router<br/>routing base<br/>[base.js]"]
end

subgraph group_media["Media"]
  node_media_player["Media player<br/>media core"]
  node_video_player["Video player<br/>video playback"]
  node_audio_player["Audio player<br/>audio playback"]
  node_image["Images<br/>image rendering"]
  node_subtitles["Subtitles<br/>caption rendering"]
  node_metadata["Metadata"]
  node_tv["TV"]
end

subgraph group_services["Services"]
  node_services["Platform services<br/>state/services"]
  node_settings["Settings<br/>config service"]
  node_storage["Storage<br/>persistence"]
  node_registry["Registry"]
  node_pin["PIN<br/>access control"]
  node_purchase["Purchase<br/>commerce"]
  node_profile["Profile"]
  node_language["Language<br/>locale selection"]
  node_locale["Locale<br/>localization"]
  node_ads["Ads<br/>monetization"]
  node_metrics["Metrics<br/>telemetry"]
end

subgraph group_accessibility["Accessibility"]
  node_accessibility["Accessibility<br/>assistive features"]
  node_announcer["Announcer<br/>speech output"]
  node_shaders["Shaders<br/>visual adaptation"]
end

subgraph group_support["Shared support"]
  node_support["Shared support<br/>framework support"]
  node_lightning["Lightning<br/>framework bridge"]
  node_utils["Utils<br/>shared utilities"]
  node_helpers["Helpers"]
end

node_pkg -->|"exports"| node_startapp
node_pkg -->|"exports"| node_router
node_pkg -->|"exports"| node_media_player
node_pkg -->|"exports"| node_services
node_pkg -->|"exports"| node_accessibility
node_pkg -->|"exports"| node_support
node_pkg -.->|"types"| node_types
node_startapp -->|"boots"| node_application
node_startapp -->|"configures"| node_launch
node_application -->|"registers"| node_router
node_application -->|"wires"| node_services
node_launch -->|"coordinates"| node_router
node_router -->|"implements"| node_route_base
node_router -->|"uses"| node_route_model
node_router -->|"uses"| node_route_utils
node_router -->|"renders on"| node_lightning
node_route_utils -->|"supports"| node_route_base
node_media_player -->|"specializes"| node_video_player
node_media_player -->|"specializes"| node_audio_player
node_media_player -->|"coordinates"| node_subtitles
node_video_player -.->|"shares"| node_image
node_image -->|"uses"| node_lightning
node_subtitles -->|"uses"| node_lightning
node_metadata -->|"supports"| node_tv
node_accessibility -->|"contains"| node_announcer
node_accessibility -->|"contains"| node_shaders
node_announcer -.->|"uses"| node_utils
node_shaders -->|"uses"| node_lightning
node_services -->|"contains"| node_settings
node_services -->|"contains"| node_storage
node_services -->|"contains"| node_registry
node_services -->|"contains"| node_pin
node_services -->|"contains"| node_purchase
node_services -->|"contains"| node_profile
node_services -->|"contains"| node_language
node_services -->|"contains"| node_locale
node_services -->|"contains"| node_ads
node_services -->|"contains"| node_metrics
node_support -->|"bridges"| node_lightning
node_support -->|"shares"| node_utils
node_support -->|"shares"| node_helpers
node_support -.->|"supports"| node_router
node_support -.->|"supports"| node_media_player
node_support -.->|"supports"| node_accessibility

click node_pkg "https://github.com/rdkcentral/lightning-sdk/blob/master/index.js"
click node_types "https://github.com/rdkcentral/lightning-sdk/blob/master/index.d.ts"
click node_startapp "https://github.com/rdkcentral/lightning-sdk/blob/master/src/startApp.js"
click node_application "https://github.com/rdkcentral/lightning-sdk/tree/master/src/Application"
click node_launch "https://github.com/rdkcentral/lightning-sdk/tree/master/src/Launch"
click node_router "https://github.com/rdkcentral/lightning-sdk/tree/master/src/Router"
click node_route_model "https://github.com/rdkcentral/lightning-sdk/tree/master/src/Router/model"
click node_route_utils "https://github.com/rdkcentral/lightning-sdk/tree/master/src/Router/utils"
click node_route_base "https://github.com/rdkcentral/lightning-sdk/blob/master/src/Router/base.js"
click node_media_player "https://github.com/rdkcentral/lightning-sdk/tree/master/src/MediaPlayer"
click node_video_player "https://github.com/rdkcentral/lightning-sdk/tree/master/src/VideoPlayer"
click node_audio_player "https://github.com/rdkcentral/lightning-sdk/tree/master/src/AudioPlayer"
click node_image "https://github.com/rdkcentral/lightning-sdk/tree/master/src/Img"
click node_subtitles "https://github.com/rdkcentral/lightning-sdk/tree/master/src/Subtitles"
click node_metadata "https://github.com/rdkcentral/lightning-sdk/tree/master/src/Metadata"
click node_tv "https://github.com/rdkcentral/lightning-sdk/tree/master/src/TV"
click node_accessibility "https://github.com/rdkcentral/lightning-sdk/tree/master/src/Accessibility"
click node_announcer "https://github.com/rdkcentral/lightning-sdk/tree/master/src/Accessibility/Announcer"
click node_shaders "https://github.com/rdkcentral/lightning-sdk/tree/master/src/Accessibility/shaders"
click node_settings "https://github.com/rdkcentral/lightning-sdk/tree/master/src/Settings"
click node_storage "https://github.com/rdkcentral/lightning-sdk/tree/master/src/Storage"
click node_registry "https://github.com/rdkcentral/lightning-sdk/tree/master/src/Registry"
click node_pin "https://github.com/rdkcentral/lightning-sdk/tree/master/src/Pin"
click node_purchase "https://github.com/rdkcentral/lightning-sdk/tree/master/src/Purchase"
click node_profile "https://github.com/rdkcentral/lightning-sdk/tree/master/src/Profile"
click node_language "https://github.com/rdkcentral/lightning-sdk/tree/master/src/Language"
click node_locale "https://github.com/rdkcentral/lightning-sdk/tree/master/src/Locale"
click node_ads "https://github.com/rdkcentral/lightning-sdk/tree/master/src/Ads"
click node_metrics "https://github.com/rdkcentral/lightning-sdk/tree/master/src/Metrics"
click node_lightning "https://github.com/rdkcentral/lightning-sdk/tree/master/src/Lightning"
click node_utils "https://github.com/rdkcentral/lightning-sdk/tree/master/src/Utils"
click node_helpers "https://github.com/rdkcentral/lightning-sdk/tree/master/src/helpers"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_pkg,node_types,node_startapp,node_application,node_launch toneBlue
class node_router,node_route_model,node_route_utils,node_route_base toneAmber
class node_media_player,node_video_player,node_audio_player,node_image,node_subtitles,node_metadata,node_tv toneMint
class node_services,node_settings,node_storage,node_registry,node_pin,node_purchase,node_profile,node_language,node_locale,node_ads,node_metrics toneRose
class node_accessibility,node_announcer,node_shaders toneIndigo
class node_support,node_lightning,node_utils,node_helpers toneTeal
```

## Components

### Core runtime

Package entrypoints and Lightning app bootstrap.

- [SDK surface](https://github.com/rdkcentral/lightning-sdk/blob/master/index.js): package entry · Root package API exposed to consumers. · `index.js`
- [Types](https://github.com/rdkcentral/lightning-sdk/blob/master/index.d.ts): typing surface · Package-level TypeScript declarations. · `index.d.ts`
- [Start app](https://github.com/rdkcentral/lightning-sdk/blob/master/src/startApp.js): bootstrap · Application startup entry for consumer apps. · `src/startApp.js`
- [Application](https://github.com/rdkcentral/lightning-sdk/tree/master/src/Application): app lifecycle · Main application lifecycle integration. · `src/Application`
- [Launch](https://github.com/rdkcentral/lightning-sdk/tree/master/src/Launch): startup hook · Startup behavior and launch integration. · `src/Launch`

### Navigation

Route handling and screen orchestration.

- [Router](https://github.com/rdkcentral/lightning-sdk/tree/master/src/Router): navigation core · Navigation boundary coordinating routes, history, transitions, and deep links. · `src/Router`
- [Route model](https://github.com/rdkcentral/lightning-sdk/tree/master/src/Router/model): routing model · Route and request data structures. · `src/Router/model`
- [Router utils](https://github.com/rdkcentral/lightning-sdk/tree/master/src/Router/utils): routing helpers · Provider, loader, widgets, history, and transition utilities. · `src/Router/utils`
- [Base router](https://github.com/rdkcentral/lightning-sdk/blob/master/src/Router/base.js): routing base · Core router implementation surface. · `src/Router/base.js`

### Media

Playback, image, subtitles, and content metadata.

- [Media player](https://github.com/rdkcentral/lightning-sdk/tree/master/src/MediaPlayer): media core · Shared playback abstraction. · `src/MediaPlayer`
- [Video player](https://github.com/rdkcentral/lightning-sdk/tree/master/src/VideoPlayer): video playback · Video playback integration. · `src/VideoPlayer`
- [Audio player](https://github.com/rdkcentral/lightning-sdk/tree/master/src/AudioPlayer): audio playback · Audio playback integration. · `src/AudioPlayer`
- [Images](https://github.com/rdkcentral/lightning-sdk/tree/master/src/Img): image rendering · Lightning image handling and scaled textures. · `src/Img`
- [Subtitles](https://github.com/rdkcentral/lightning-sdk/tree/master/src/Subtitles): caption rendering · Subtitle component and rendering support. · `src/Subtitles`
- [Metadata](https://github.com/rdkcentral/lightning-sdk/tree/master/src/Metadata): content metadata · Content metadata integration. · `src/Metadata`
- [TV](https://github.com/rdkcentral/lightning-sdk/tree/master/src/TV): tv integration · TV-specific device and platform helpers. · `src/TV`

### Services

State, persistence, identity, monetization, and telemetry.

- **Platform services**: state/services · Persistence, identity, monetization, language, and telemetry services.
- [Settings](https://github.com/rdkcentral/lightning-sdk/tree/master/src/Settings): config service · Application settings integration. · `src/Settings`
- [Storage](https://github.com/rdkcentral/lightning-sdk/tree/master/src/Storage): persistence · Persistent storage API. · `src/Storage`
- [Registry](https://github.com/rdkcentral/lightning-sdk/tree/master/src/Registry): device registry · Platform or device registry access. · `src/Registry`
- [PIN](https://github.com/rdkcentral/lightning-sdk/tree/master/src/Pin): access control · Parental PIN or access control support. · `src/Pin`
- [Purchase](https://github.com/rdkcentral/lightning-sdk/tree/master/src/Purchase): commerce · Purchase and entitlement integration. · `src/Purchase`
- [Profile](https://github.com/rdkcentral/lightning-sdk/tree/master/src/Profile): user profile · User profile integration. · `src/Profile`
- [Language](https://github.com/rdkcentral/lightning-sdk/tree/master/src/Language): locale selection · Language selection support. · `src/Language`
- [Locale](https://github.com/rdkcentral/lightning-sdk/tree/master/src/Locale): localization · Locale formatting and localization helpers. · `src/Locale`
- [Ads](https://github.com/rdkcentral/lightning-sdk/tree/master/src/Ads): monetization · Advertising integration. · `src/Ads`
- [Metrics](https://github.com/rdkcentral/lightning-sdk/tree/master/src/Metrics): telemetry · Metrics and reporting integration. · `src/Metrics`

### Accessibility

Assistive features and visual adaptation.

- [Accessibility](https://github.com/rdkcentral/lightning-sdk/tree/master/src/Accessibility): assistive features · Accessibility subsystem entrypoint. · `src/Accessibility`
- [Announcer](https://github.com/rdkcentral/lightning-sdk/tree/master/src/Accessibility/Announcer): speech output · Speech and announcement helpers for accessibility. · `src/Accessibility/Announcer`
- [Shaders](https://github.com/rdkcentral/lightning-sdk/tree/master/src/Accessibility/shaders): visual adaptation · Color-vision and monochromacy shader modes. · `src/Accessibility/shaders`

### Shared support

Framework bridge, utilities, and low-level helpers.

- **Shared support**: framework support · Lightning bridge, utilities, and shared helpers.
- [Lightning](https://github.com/rdkcentral/lightning-sdk/tree/master/src/Lightning): framework bridge · Explicit bridge to the Lightning framework. · `src/Lightning`
- [Utils](https://github.com/rdkcentral/lightning-sdk/tree/master/src/Utils): shared utilities · Common utility helpers used across modules. · `src/Utils`
- [Helpers](https://github.com/rdkcentral/lightning-sdk/tree/master/src/helpers): internal helpers · Reusable low-level helper functions. · `src/helpers`

## Connections

- 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.