feat: overhaul overview page by covering more key concepts in more detail

Author: nekename

src/overview.md

@@ -1,13 +1,64 @@
 # Overview
 
-OpenAction is an event-driven API that communicates over WebSocket.
+If you're a developer starting to work with the OpenAction API to create custom actions for a programmable control surface, you're going to be creating a plugin, which is a concept hopefully familiar to you as a user of an OpenAction server (like OpenDeck). This page hopes to cover other key concepts of the API that aren't as visible to the end user.
 
-Plugins provide actions, which can be instantiated by users on multiple profiles across multiple devices simultaneously. Each action instance is created from the properties specified in the plugin manifest, after which its states and settings can be mutated and these changes retained.
+### Plugin structure
 
-Each action may also be accompanied by a property inspector, a user interface displayed when the action is selected, where the user may customise the behaviour of the action. The `setSettings`, `getSettings`, `setGlobalSettings`, and `getGlobalSettings` events may be used by both the plugin and property inspector.
+In its distributed form, an OpenAction plugin is a regular filesystem directory (with a name ending in `.sdPlugin`, for backwards-compatibility with the Stream Deck SDK).
 
-Users may also configure "Multi Actions", where multiple actions are executed in sequence.
+This directory contains everything that the plugin needs, including:
 
-Events are represented in (stringified) JSON format, with a field to identify the event and an optional payload containing more information about the event, as well as an instance context if the event is instance-related in order to identify it.
+- A [plugin manifest file](manifest.md) (`manifest.json`), which describes the plugin and its actions to the server
+- Your plugin's compiled executable file(s) (or script files, if using an interpreted language)
+- Icons and images used by the plugin
+- Property inspector (action settings UI) files, if needed
 
-For more information about a specific event, consult the [clientbound events](api/clientbound/0_index.md) and [serverbound events](api/serverbound/0_index.md) pages.
+All of the user's installed plugins are stored together in a directory on their system, which varies depending on the OpenAction server and operating system being used. If you're using OpenDeck, you can locate this directory by clicking the "Open config directory" button in the OpenDeck settings view, then opening the `plugins` folder within.
+
+This is what a user's plugins directory might look like, with two plugins installed:
+
+```
+plugins/
+├── com.example.coolplugin.sdPlugin/
+│   ├── manifest.json                            # Plugin manifest file
+│   ├── oacoolplugin-x86_64-pc-windows-msvc.exe  # Compiled executables
+│   ├── oacoolplugin-aarch64-apple-darwin
+│   ├── oacoolplugin-x86_64-apple-darwin
+│   ├── oacoolplugin-x86_64-unknown-linux-gnu
+│   ├── oacoolplugin-aarch64-unknown-linux-gnu
+│   ├── icon.svg                                 # Plugin icon
+│   ├── actions/                                 # Action icons
+│   │   └── funaction.svg
+│   └── pi/                                      # Action property inspectors
+│       └── funaction.html
+├── com.example.lesscoolplugin.sdPlugin/         # Another plugin
+│   ├── manifest.json
+│   ├── oalesscoolplugin-x86_64-pc-windows-msvc.exe
+│   ├── icon.svg
+│   └── actions/
+│       └── lessfunaction.svg
+```
+
+### Actions, instances and contexts
+
+An OpenAction plugin can contain multiple actions, each of which provides different functionality to the user. For example, a [plugin for controlling media playback](https://github.com/OpenActionPlugins/mpris) might include actions for play/pause, previous, and next.
+
+When a user adds an action to their control surface (for example, by dragging it onto a button on one of their OpenDeck profiles), this creates an instance of that action. Multiple instances of the same action can exist independently, each with its own settings and state.
+
+Every action instance is identified by a unique context string, which is generated by the OpenAction server when the instance is created. This context is used in all communication between clients and the server to identify the instance an event pertains to. It is different from the action's UUID, which identifies all instances of that action.
+
+When the user edits the appearance (state) or settings of an instance, the OpenAction server persists these changes, and notifies the plugin of the changes. Because each instance becomes an independent copy of the action template, you may need to completely remove and re-add your instances when making changes to the action in your plugin's manifest file.
+
+### Property inspectors
+
+Many actions need the user to be able to configure settings specific to that action instance. This is done through a property inspector, which is a user interface provided as part of the plugin.
+
+Property inspectors are implemented using web technologies (HTML, CSS, and JavaScript), so that the OpenAction server can embed them in a webview. This is both due to the flexibility of web technologies for building user interfaces, and behaving in a consistent manner across different platforms.
+
+Property inspectors themselves are also direct consumers of the OpenAction API, making them the other kind of OpenAction client (alongside plugins). All communication between the property inspector and the plugin happens through the OpenAction server.
+
+However, property inspectors only have access to a limited subset of the events of the OpenAction API, primarily those related to reading and writing settings for the action instance they are associated with.
+
+### Next steps
+
+Now, you should have an understanding of the key concepts of the OpenAction API. The next page covers the requirements of the plugin manifest file, the creation of which being the first step in creating a plugin.