# Addon System

The Addon System defines how addons are declared and connected to OMS.

An addon is a modular integration unit that groups related features and customizes the runtime context used by those features.

***

### Overview

An addon is responsible for:

* Providing a unique addon identifier
* Customizing its runtime context
* Registering one or more features during the OMS lifecycle

An addon does **not** execute runtime behavior by itself. Runtime behavior is implemented by features registered through the addon’s `FeatureManager`.

***

### Core Types

#### OmsAddon

`OmsAddon` is the base class for defining an OMS addon.

Responsibilities:

* Declaring the addon ID
* Optionally customizing the `AddonContextSpec`
* Registering features during the addon lifecycle phase

{% @github-files/github-code-block url="<https://github.com/c0nnor263/OperateMyServer/blob/main/oms-api/src/main/kotlin/io/conboi/oms/api/foundation/addon/OmsAddon.kt>" %}

***

#### AddonRegistry

`AddonRegistry` is the registration entry point exposed by OMS during the addon lifecycle.

It is used to register addon instances:

{% @github-files/github-code-block url="<https://github.com/c0nnor263/OperateMyServer/blob/main/oms-api/src/main/kotlin/io/conboi/oms/api/foundation/addon/AddonRegistry.kt>" %}

Notes:

* Provided only during the addon registration lifecycle event
* Addons must be registered strictly within that phase
* Does not define storage or lookup behavior

***

#### AddonContext

`AddonContext` provides access to addon-specific runtime infrastructure.

It is supplied by OMS and used as the primary integration point between the addon and the OMS runtime.

{% @github-files/github-code-block url="<https://github.com/c0nnor263/OperateMyServer/blob/main/oms-api/src/main/kotlin/io/conboi/oms/api/foundation/addon/AddonContext.kt>" %}

***

#### AddonContextSpec

`AddonContextSpec` defines how the `AddonContext` is constructed.

Allows overriding selected factories while keeping default OMS behavior.

{% @github-files/github-code-block url="<https://github.com/c0nnor263/OperateMyServer/blob/main/oms-api/src/main/kotlin/io/conboi/oms/api/foundation/addon/AddonContextSpec.kt>" %}

***

### Lifecycle

During OMS initialization:

1. OMS opens the addon registration phase and emits `OMSLifecycle.Addon.RegisterEvent`
2. Addons are registered via `AddonRegistry`
3. A default `AddonContextSpec` is created per addon
4. The addon may modify it via `configureContext`
5. OMS builds the `AddonContext`
6. `onRegisterFeatures(context)` is invoked
7. Features are registered using `context.featureManager`

After this phase, runtime execution is handled entirely by features.

***

### Notes

* Addons are integration containers, not runtime executors
* Features contain all runtime logic
* `AddonContext` is intentionally minimal
* Context customization is done via `AddonContextSpec`
* Addon registration is strictly lifecycle-bound

***

### Important Clarifications

The current API does **not** guarantee that `AddonContext` provides:

* server instance access
* config system access

These should only be documented when explicitly exposed by the public API.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://conboi.gitbook.io/oms-wiki/developer-guide/core-architecture/addon-system.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.