chore: add conceptual overview and minor content changes

README.md

@@ -9,7 +9,7 @@
 
 ## Plugin architecture
 
-The plugins are enabled via a message passing mechanism over GRPC. Each language implements a driver which provides the
+The plugins are enabled via a message passing mechanism over gRPC. Each language implements a driver which provides the
 mechanism to locate and load plugins, as well as a catalogue of features (like mock servers, matchers and provider
 verifiers) and a central message bus to enable communication between the language implementation and the plugins.
 
@@ -31,12 +31,12 @@ There are two implementations of plugin drivers: [JVM](drivers/jvm) and [Rust](d
 
 ### Plugins
 
-Plugins are required to start up a GRPC server when loaded, and respond to messages from the plugin driver. They provide
+Plugins are required to start up a gRPC server when loaded, and respond to messages from the plugin driver. They provide
 a manifest that describes the features they provide and the mechanism needed to load them.  
 
 Main responsibilities:
 * Have a plugin manifest that describes the plugin and how to load it.
-* Start a GRPC server on load and provide the port to the driver that loaded it.
+* Start a gRPC server on load and provide the port to the driver that loaded it.
 * Provide a catalogue of features the plugin provides when the driver requests it.
 * Respond to messages from the driver.
 
@@ -65,9 +65,7 @@ See [Pactflow Protobuf/gRPC plugin](https://github.com/pactflow/pact-protobuf-pl
 
 #### Plugins that provide matchers/generators (WIP)
 
-Plugins can also provide new matching rules and generators. 
-
-TODO, not implemented as part of the plugin MVC, and will be added in a later update.
+TODO 🚧
 
 ## Background
 

docs/plugin-driver-design.md

@@ -10,6 +10,24 @@ Main plugin driver responsibilities:
 * Provide a messaging bus to facilitate communication between the language implementation and the plugins.
 * Manage the plugin lifecycles.
 
+## Conceptual Overview
+
+![Conceptual Overview](conceptual-overview.png)
+
+
+1. Your code 😉
+2. The test framework executing tests e.g. Jest, JUnit
+3. The Pact Client library used in the test e.g. Pact JS, Pact JVM
+4. The Shared Core (Rust) or the Java Plugin Driver (for JVM projects) manages the lifecycle of a Pact test and provides key capabilities to client libraries. It oversees the use of plugins via the Plugin Driver
+
+5. Plugin driver is responsible for discovering, starting and orchestrating plugins.
+6. Plugin may communicate to/from the SUT e.g. in the case of a new transport it will serve as the mock server, and will also issue verification requests at the Provider API
+7. The pact file contains additional information
+   * Required plugins
+   * Transports
+   * Interaction type
+   * Markdown to display interactions
+
 ## Locating plugins
 
 Plugins must be stored on the system in a Pact plugins directory, defined either by the `PACT_PLUGIN_DIR` environment 

docs/writing-plugin-guide.md

@@ -15,11 +15,16 @@ The CSV plugin is written in Rust and the Protobuf one in Kotlin.
 
 ## Plugin Interface
 
-The first version of the plugin interface (version 1) supports adding matchers and generators for different types
-of content. Later versions will expand to add other things like protocol and transport implementations, but for now
-the plugins can only provide support for new types of content. This is for things like request/response bodies and
-message payloads and are based on specified MIME types. Refer to [Content Matchers and Generators](content-matcher-design.md) 
-for more details on the interface and gRPC methods that need to be implemented.
+The first version of the plugin interface (version 1) supports extending Pact with [Content](content-matcher-design.md) types, along with using Matchers and Generators to support flexible matching, and for adding new [Transport protocols](protocol-plugin-design.md).
+
+Content Matchers are for things like request/response bodies and message payloads and are based on specified MIME types, such as protobufs. 
+
+Transports allow you to communicate these new content types over a different wire protocol, such as gRPC or Websockets.
+
+Refer to for more details on the interface and gRPC methods that need to be implemented:
+
+- [Content Matchers and Generators](content-matcher-design.md)
+- [Transport protocols](protocol-plugin-design.md)
 
 You can find the [proto file](../proto/plugin.proto) that defines the plugin interface in the proto directory. Your 
 plugin will need to implement this interface.