# stremio/stremio-addon-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/stremio/stremio-addon-sdk
- Repository: https://github.com/stremio/stremio-addon-sdk

## Overview

This SDK turns an addon manifest and resource handlers into an HTTP protocol service: addon authors register catalog, metadata, stream, subtitle, or addon-catalog behavior; Stremio calls the resulting endpoints and receives JSON responses. It also provides an install/configuration landing page, Express-router embedding, and optional publishing to Stremio’s central collection. The runtime is small, so the graph focuses on those product capabilities. Relationships are grounded in the README and sampled sources; addon-specific data sources are described by the README but are outside this repository.

Main entry points: [`src/builder.js`](https://github.com/stremio/stremio-addon-sdk/blob/master/src/builder.js) (Addon interface), [`src/getRouter.js`](https://github.com/stremio/stremio-addon-sdk/blob/master/src/getRouter.js) (Protocol router), [`src/serveHTTP.js`](https://github.com/stremio/stremio-addon-sdk/blob/master/src/serveHTTP.js) (HTTP server), [`src/publishToCentral.js`](https://github.com/stremio/stremio-addon-sdk/blob/master/src/publishToCentral.js) (Central publisher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_addon["Addon Definition"]
  node_builder["Manifest and handlers<br/>[builder.js]"]
  node_catalog["Catalog handlers<br/>[builder.js]"]
  node_metadata["Metadata handlers<br/>[builder.js]"]
  node_streams["Stream handlers<br/>[builder.js]"]
  node_subtitles["Subtitle handlers<br/>[builder.js]"]
  node_addon_catalog["Addon catalog handlers<br/>[builder.js]"]
  node_interface["Addon interface<br/>[builder.js]"]
end

subgraph group_http["HTTP Serving"]
  node_router["Protocol router<br/>[getRouter.js]"]
  node_server["HTTP server<br/>[serveHTTP.js]"]
  node_landing["Install/config page<br/>[landingTemplate.js]"]
end

subgraph group_install["Install and Publish"]
  node_publisher["Central publisher"]
end

node_stremio(("Stremio app"))
node_author(("Addon author"))
node_express["Express host"]
node_addon_data["Addon data sources"]
node_central[("Public addon collection")]

node_author -->|"defines manifest"| node_builder
node_builder -->|"builds interface"| node_interface
node_author -->|"registers handler"| node_catalog
node_author -->|"registers handler"| node_metadata
node_author -->|"registers handler"| node_streams
node_author -->|"registers handler"| node_subtitles
node_author -->|"registers handler"| node_addon_catalog
node_interface -->|"dispatches requests"| node_catalog
node_interface -->|"dispatches requests"| node_metadata
node_interface -->|"dispatches requests"| node_streams
node_interface -->|"dispatches requests"| node_subtitles
node_interface -->|"dispatches requests"| node_addon_catalog
node_author -->|"starts service"| node_server
node_server -->|"mounts router"| node_router
node_server -->|"renders page"| node_landing
node_author -->|"mounts in Express"| node_router
node_express -->|"hosts router"| node_router
node_router -->|"calls get"| node_interface
node_router -->|"returns protocol JSON"| node_stremio
node_stremio -->|"requests resources"| node_server
node_catalog -.->|"queries sources"| node_addon_data
node_metadata -.->|"queries sources"| node_addon_data
node_streams -.->|"queries sources"| node_addon_data
node_subtitles -.->|"queries sources"| node_addon_data
node_author -->|"publishes URL"| node_publisher
node_publisher -->|"submits addon"| node_central

click node_builder "https://github.com/stremio/stremio-addon-sdk/blob/master/src/builder.js"
click node_catalog "https://github.com/stremio/stremio-addon-sdk/blob/master/src/builder.js"
click node_metadata "https://github.com/stremio/stremio-addon-sdk/blob/master/src/builder.js"
click node_streams "https://github.com/stremio/stremio-addon-sdk/blob/master/src/builder.js"
click node_subtitles "https://github.com/stremio/stremio-addon-sdk/blob/master/src/builder.js"
click node_addon_catalog "https://github.com/stremio/stremio-addon-sdk/blob/master/src/builder.js"
click node_interface "https://github.com/stremio/stremio-addon-sdk/blob/master/src/builder.js"
click node_router "https://github.com/stremio/stremio-addon-sdk/blob/master/src/getRouter.js"
click node_server "https://github.com/stremio/stremio-addon-sdk/blob/master/src/serveHTTP.js"
click node_landing "https://github.com/stremio/stremio-addon-sdk/blob/master/src/landingTemplate.js"
click node_publisher "https://github.com/stremio/stremio-addon-sdk/blob/master/src/publishToCentral.js"

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_builder,node_catalog,node_metadata,node_streams,node_subtitles,node_addon_catalog,node_interface toneBlue
class node_router,node_server,node_landing,node_central toneAmber
class node_publisher toneMint
class node_stremio,node_author,node_express,node_addon_data toneIndigo
```

## Components

### Addon Definition

- [Manifest and handlers](https://github.com/stremio/stremio-addon-sdk/blob/master/src/builder.js): `src/builder.js`
- [Catalog handlers](https://github.com/stremio/stremio-addon-sdk/blob/master/src/builder.js): `src/builder.js`
- [Metadata handlers](https://github.com/stremio/stremio-addon-sdk/blob/master/src/builder.js): `src/builder.js`
- [Stream handlers](https://github.com/stremio/stremio-addon-sdk/blob/master/src/builder.js): `src/builder.js`
- [Subtitle handlers](https://github.com/stremio/stremio-addon-sdk/blob/master/src/builder.js): `src/builder.js`
- [Addon catalog handlers](https://github.com/stremio/stremio-addon-sdk/blob/master/src/builder.js): `src/builder.js`
- [Addon interface](https://github.com/stremio/stremio-addon-sdk/blob/master/src/builder.js): `src/builder.js`

### HTTP Serving

- [Protocol router](https://github.com/stremio/stremio-addon-sdk/blob/master/src/getRouter.js): `src/getRouter.js`
- [HTTP server](https://github.com/stremio/stremio-addon-sdk/blob/master/src/serveHTTP.js): `src/serveHTTP.js`
- [Install/config page](https://github.com/stremio/stremio-addon-sdk/blob/master/src/landingTemplate.js): `src/landingTemplate.js`

### Install and Publish

- [Central publisher](https://github.com/stremio/stremio-addon-sdk/blob/master/src/publishToCentral.js): `src/publishToCentral.js`

### Other components

- **Stremio app**
- **Addon author**
- **Express host**
- **Addon data sources**
- **Public addon collection**

## Connections

- Addon author → Manifest and handlers: defines manifest (evidence: `README.md`)
- Manifest and handlers → Addon interface: builds interface (evidence: `src/builder.js`)
- Addon author → Catalog handlers: registers handler (evidence: `README.md`)
- Addon author → Metadata handlers: registers handler (evidence: `README.md`)
- Addon author → Stream handlers: registers handler (evidence: `README.md`)
- Addon author → Subtitle handlers: registers handler (evidence: `README.md`)
- Addon author → Addon catalog handlers: registers handler (evidence: `README.md`)
- Addon interface → Catalog handlers: dispatches requests (evidence: `src/builder.js`)
- Addon interface → Metadata handlers: dispatches requests (evidence: `src/builder.js`)
- Addon interface → Stream handlers: dispatches requests (evidence: `src/builder.js`)
- Addon interface → Subtitle handlers: dispatches requests (evidence: `src/builder.js`)
- Addon interface → Addon catalog handlers: dispatches requests (evidence: `src/builder.js`)
- Addon author → HTTP server: starts service (evidence: `README.md`)
- HTTP server → Protocol router: mounts router (evidence: `src/serveHTTP.js`)
- HTTP server → Install/config page: renders page (evidence: `src/serveHTTP.js`)
- Addon author → Protocol router: mounts in Express (evidence: `README.md`)
- Express host → Protocol router: hosts router (evidence: `README.md`)
- Protocol router → Addon interface: calls get (evidence: `src/getRouter.js`)
- Protocol router → Stremio app: returns protocol JSON (evidence: `README.md`)
- Stremio app → HTTP server: requests resources (evidence: `README.md`)
- Catalog handlers → Addon data sources: queries sources
- Metadata handlers → Addon data sources: queries sources
- Stream handlers → Addon data sources: queries sources
- Subtitle handlers → Addon data sources: queries sources
- Addon author → Central publisher: publishes URL (evidence: `README.md`)
- Central publisher → Public addon collection: submits addon (evidence: `src/publishToCentral.js`)
