Architecture

Understand the architectural model of OMSS Core and why its responsibilities are divided across plugins, hooks, providers, resolvers, extractors, and source services.

OMSS Core is built around a simple architectural idea: keep the runtime small and let specialized parts do specialized work. Instead of one monolithic server object containing transport logic, provider execution, resolution rules, extraction rules, and lifecycle state all at once, the system separates those responsibilities into distinct modules.

That separation makes the architecture easier to reason about. It also makes the system more adaptable, because each part can evolve for different reasons without forcing every other part to change alongside it.

Architectural shape

Simplified sequence diagram showing the architectural flow of an OMSS Core get sources request.

The different components

OMSSServer

Is the central runtime object. It holds shared state, coordinates lifecycle events, and exposes the public API for backend authors to register providers, resolvers, extractors, and other capabilities.

Plugins

Allow cross-cutting capabilities to be added to the runtime. For example, a plugin could add HTTP transport, caching, authentication and other features that are not part of the core runtime. Plugins can also register hooks, providers, resolvers, and extractors.

Hooks

Are a way for different parts of the system to observe and react to lifecycle events. Hooks allow another component to listen in on different phases of the runtime without requiring direct coupling to the core or other components.

Providers

Are the parts of the system that produce sources and subtitles from an upstream service/system. Providers are registered with the runtime and cannot be called directly by the core. Instead, they are invoked through the source pipeline.

Resolvers

Are responsible for turning OMSS IDs into structured metadata that can be used by providers. For example, a resolver could take a TMDB ID and return the title, year, and other relevant information needed to query a provider. Providers have to specify which resolvers they require, and the source pipeline will ensure that those resolvers are called before the provider is executed.

Extractors

Can be called by different providers to get media from an overlaping upstream system. For example, provider A and provider B found a link that belongs to Upstream System X. Instead of each provider implementing the logic to extract the media from Upstream System X, they can both call an extractor that is registered with the runtime to handle that specific upstream system.

Source pipeline

Is the heart of the runtime. It coordinates the flow of data from the initial request to the final response. It handles calling resolvers, executing providers, and aggregating results into a final response.

At the center is the OMSSServer class. Its job is to hold the system together. That includes maintaining shared state and expose different APIs for different features.

A system designed for extension

The architecture of OMSS Core makes the strongest statement not through what it includes, but through what it refuses to hard-code. That is the defining design position of the project.

A backend built on OMSS Core gains more features then you might think. With such an extensible architecture, the runtime can be extended in many ways without requiring changes to the core itself.