> ## Documentation Index
> Fetch the complete documentation index at: https://omss.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```mermaid theme={"theme":"material-theme-darker"}
sequenceDiagram
    autonumber

    participant Client as Consumer Project
    participant Backend as OMSS Core
    participant SourceService as SourceService
    participant Providers as ProviderRegistry
    participant SourceCore as SourceCore
    participant Resolvers
    participant Provider as Registered Provider(s)

    Note over Client,Provider: Phase 1 - startup and provider registration

    Client->>Backend: Create OMSSServer(config)
    Backend->>Providers: Initialize provider registry
    Providers-->>Backend: Provider registry ready

    Client->>Backend: Register provider(s)
    Backend->>Providers: register(provider)
    Providers-->>Backend: Provider available

    Note over Client,Provider: Phase 2 - get sources request

    Client->>Backend: Get Sources(OMSSid)

    Backend->>SourceService: getSources(OMSSid)
    SourceService->>SourceCore: getSources(OMSSid)
    SourceCore->>Providers: Get providers supporting this OMSSid
    Providers-->>SourceCore: List of eligible providers
    SourceCore->>Resolvers: Resolve metadata from OMSSid
    Resolvers-->>SourceCore: Resolved metadata

    loop for each eligible provider
        Note over SourceCore,Provider: There are more features available here, but they will be covered in later sections.
        SourceCore->>Provider: Execute provider with resolved metadata
        Provider-->>SourceCore: Emitted provider result(s)
    end

    SourceCore-->>SourceService: Aggregated sources
    SourceService-->>Backend: Final source response
    Backend-->>Client: Sources returned
```

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

## The different components

<AccordionGroup>
  <Accordion title="OMSSServer" icon="server" defaultOpen>
    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.
  </Accordion>

  <Accordion title="Plugins" icon="plug">
    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.
  </Accordion>

  <Accordion title="Hooks" icon="webhook">
    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.
  </Accordion>

  <Accordion title="Providers" icon="database">
    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.
  </Accordion>

  <Accordion title="Resolvers" icon="search">
    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.
  </Accordion>

  <Accordion title="Extractors" icon="scissors">
    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.
  </Accordion>

  <Accordion title="Source pipeline" icon="workflow">
    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.
  </Accordion>
</AccordionGroup>

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.


## Related topics

- [OMSS v1.0 Specification](/spec/v1.0/ref/spec.md)
- [Why OMSS?](/spec/explanation/features.md)
- [Introduction to OMSS v1.0](/spec/v1.0/ref/introduction.md)