how to build a connector

docs/dev/connector_proxy.md

@@ -2,3 +2,31 @@
 
 A connector-proxy is an application that is generally deployed alongside frontend and backend.
 Please see [Connector Proxy in 5 mins](https://github.com/sartography/spiff-arena/wiki/Connector-Proxy-in-5-mins).
+
+```mermaid
+graph TD
+    subgraph ConnectorProxy[Connector Proxy Application]
+        direction TB
+        ConnectorA
+        ConnectorB
+    end
+
+    subgraph ConnectorA[Connector A]
+        direction TB
+        CommandA1[Command C]
+        CommandA2[Command D]
+    end
+
+    subgraph ConnectorB[Connector B]
+        direction TB
+        CommandB1[Command E]
+        CommandB2[Command F]
+    end
+
+```
+
+
+Connector Proxies are containers for connectors.
+Connectors are usually python libraries that are included in connector proxy codebases, but they can also be embedded directly inside of connector proxies.
+Our connector-proxy-demo includes a few connectors, including [connector-aws](https://github.com/sartography/connector-aws) and [connector-http](https://github.com/sartography/connector-http).
+Connector http can be used for many API interactions, but you can also [write your own connectors](/dev/how_to_build_a_connector).

docs/dev/how_to_build_a_connector.md

@@ -0,0 +1,23 @@
+# How to build a connector
+
+While exisiting connectors like connector-http are very flexible, you may choose to build a connector for a specific use case.
+
+To get an idea of what you are in for, take a look at existing connectors:
+* [connector-http](https://github.com/sartography/connector-http/blob/main/src/connector_http/commands/get_request_v2.py)
+* [connector-smtp](https://github.com/sartography/connector-smtp/blob/main/src/connector_smtp/commands/send_email.py)
+
+And there are [many more connectors](https://github.com/sartography?q=connector&type=public&language=python&sort=).
+
+A connector can implement many commands.
+Commands are also known as operators in the SpiffWorkflow frontend properties panel user interface.
+Like the above examples, you will want to inherit from the `ConnectorCommand` class.
+You will see that there are two important functions that your command class must implement:
+
+* `__init__`
+* `run`
+
+Code introspection is used based on the implementation of the `__init__` method to determine which parameters should be allowed in the properties panel.
+The `run` method is where the actual work is done (send http request, etc).
+
+If you end up writing a connector, please consider contributing it back to the community and please consider contributing to this documentation.
+Thank you!

docs/index.md

@@ -14,6 +14,7 @@ dev/setup.md
 dev/backend.md
 dev/frontend.md
 dev/connector_proxy.md
+dev/how_to_build_a_connector.md
 dev/process.md
 ```