> For the complete documentation index, see [llms.txt](https://stage-precision.gitbook.io/grid/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stage-precision.gitbook.io/grid/extensions/extension-philosophy.md).

# Extension Philosophy

Grid Extensions connect external hardware, software, services, and protocols with Grid.

Their purpose is not to reproduce an external API. Their purpose is to translate an external system into a clear and consistent Grid object.

{% hint style="success" %}
A great Extension does not expose an API.

A great Extension makes an external system feel like a native Grid object.
{% endhint %}

***

## Grid First

Design the Extension around how users work inside Grid.

The underlying system may use REST, TCP, UDP, WebSockets, OSC, or a proprietary protocol. These technical details should have as little influence as possible on the user experience.

Translate external functionality into:

* Parameters for configuration
* Entities for runtime state
* Actions for intentional operations
* Events for meaningful occurrences
* Connection States for availability
* Workflows for visible automation

Use understandable Grid terminology instead of raw API names, endpoints, field names, or internal identifiers.

***

## Build Useful Integrations

An Extension does not need to expose every function provided by the external system.

Focus on functionality that provides meaningful value for:

* control
* monitoring
* automation
* visualization
* workflow programming
* system integration

The available functionality should reflect the real capabilities of the external system.

A command-only integration is valid when no feedback is available.

A fully synchronized integration is preferable when reliable feedback exists.

***

## Hide Complexity, Not Behavior

Users should not need to understand:

* Python
* protocol implementation
* API endpoints
* authentication internals
* message parsing
* communication structures

They should still be able to understand:

* how the Extension is configured
* what data it provides
* which Actions are available
* which Events may occur
* what automatic behavior is running
* what the current Connection State means

Recurring operational behavior should remain visible through Standard Workflows wherever practical.

***

## Related Guidelines

The following pages define the detailed design rules:

* **Naming Conventions**
* **Discovery and Dynamic Data**
* **Error Handling**
* **Performance**
* **Compatibility and Public API Stability**
* **User Experience**