chore(Docs): add diagrams to documentation

Author: ShadowApex

docs/index.md

@@ -17,12 +17,51 @@ InputPlumber is an open source input routing and control daemon for Linux. It ca
 be used to combine any number of input devices (like gamepads, mice, and keyboards)
 and translate their input to a variety of virtual device formats.
 
-### Features
+## Features
 
 * [x] Combine multiple input devices
 * [x] Emulate mouse, keyboard, and gamepad inputs
 * [x] Intercept and route input over DBus for overlay interface control
 * [x] Input mapping profiles to translate source input into the desired target input
 * [ ] Route input over the network
 
+## How it works
 
+InputPlumber is designed around the concept of a **Composite Device**, which
+is a logical collection of one or more **_source devices_** that InputPlumber
+reads input events from, then translates and routes those events to one or more
+**_target devices_**.
+
+```mermaid
+graph LR
+  A["Xbox Gamepad (event0)"] --> C{Composite Device};
+  B["Keyboard (event1)"] --> C{Composite Device};
+  C --> D["DualSense Gamepad"];
+  C --> F["Mouse"];
+  C --> G["Keyboard"];
+```
+
+### Input Event Flow
+
+When InputPlumber reads an event from  a **source device**, it first identifies any
+input events that may need to be interpreted differently using a **Capability Map**,
+which is a YAML configuration file that tells InputPlumber how it should interpret
+events from a source device. After the event is interpreted, it is sent to the
+**Composite Device**.
+
+Once the **Composite Device** receives the input event from the **source device**,
+the event is translated according to any **Profile** that might be loaded on
+the **Composite Device**. A **Profile** allows translating one kind of input
+(like a gamepad joystick) into another kind of input (like mouse motion).
+
+Finally, once the event is translated according to the **Profile**, it is routed
+to any **target device(s)** that support the input event.
+
+```mermaid
+sequenceDiagram
+  autonumber
+  Source Device->>Source Device: Interpret event with Capability Map
+  Source Device->>Composite Device: Input Event
+  Composite Device->>Composite Device: Translate event with Profile
+  Composite Device->>Target Device: Route to target device
+```

docs/usage.md

@@ -17,6 +17,14 @@ any other supported input event. Input profiles are defined as YAML configuratio
 files that can be loaded on-demand for any device that InputPlumber manages. The
 format of an input profile config is defined by the [Device Profile Schema](https://raw.githubusercontent.com/ShadowBlip/InputPlumber/main/rootfs/usr/share/inputplumber/schema/device_profile_v1.json) to make it easier to create profiles.
 
+```mermaid
+sequenceDiagram
+  autonumber
+  Composite Device->>Profile: Input Event
+  Profile->>Composite Device: Translated Event
+  Composite Device->>Target Device: Route to target device
+```
+
 Typically input profiles should be generated using an external tool, but you
 can manually create your own profiles using any text editor. If you use an editor
 that supports the [YAML Language Server](https://github.com/redhat-developer/yaml-language-server)
@@ -63,6 +71,15 @@ to stop input from reaching other running applications (like a game),
 allowing the overlay to process inputs without those inputs leaking into other
 running apps.
 
+```mermaid
+sequenceDiagram
+  autonumber
+  Composite Device->>Composite Device: Intercept Mode ALL
+  Composite Device->>Target Device: Input Event
+  Target Device-->Game: Input Blocked
+  Target Device->>Overlay App: DBus Event
+```
+
 You can set the intercept mode by setting the `InterceptMode` property on the
 input device you want to intercept input from. The intercept mode can be one
 of three values:
@@ -101,7 +118,18 @@ busctl call org.shadowblip.InputPlumber \
 One feature of InputPlumber is the ability to combine multiple input devices
 together into a single logical input device called a "Composite Device". This is
 often required for many handheld gaming PCs that have built-in gamepads with
-special non-standard buttons that show up as multiple independent input devices.
+special non-standard buttons that show up as multiple independent input devices,
+like a gamepad and a keyboard.
+
+```mermaid
+graph LR
+  A["Xbox Gamepad (event0)"] --> C{Composite Device};
+  B["Keyboard (event1)"] --> C{Composite Device};
+  C --> D["DualSense Gamepad"];
+  C --> F["Mouse"];
+  C --> G["Keyboard"];
+```
+
 
 Composite devices are defined as YAML configuration files that follow the
 [Composite Device Schema](https://raw.githubusercontent.com/ShadowBlip/InputPlumber/main/rootfs/usr/share/inputplumber/schema/composite_device_v1.json)
@@ -110,6 +138,15 @@ looks at all the input devices on the system and checks to see if they match a
 composite device configuration. If they do, the input devices are combined into
 a single logical composite device.
 
+```mermaid
+graph LR
+  A["Device Added"] --> B["InputPlumber"];
+  B --> C["Read Config"];
+  C --> D{"Device matches config?"};
+  D -->|No| C;
+  D -->|Yes| F["Create Composite Device"];
+```
+
 A composite device configuration looks like this:
 
 ```yaml

mkdocs.yml

@@ -37,6 +37,11 @@ markdown_extensions:
       pygments_lang_class: true
   - pymdownx.tasklist:
       custom_checkbox: true
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
   - pymdownx.inlinehilite
   - pymdownx.snippets
   - pymdownx.superfences