From 8da54352e55717ee6f0dedfbee67660ce6d8b275 Mon Sep 17 00:00:00 2001
From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com>
Date: Fri, 6 Jul 2018 02:33:53 -0700
Subject: [PATCH] Document internal APIs and Application Services component
 (#499)

* Document internal APIs, app services in WIRING.md

* Add application services component to WIRING diagram

* Fix typo and clarify what mode internal APIs use HTTP
---
 WIRING.md | 39 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 38 insertions(+), 1 deletion(-)

diff --git a/WIRING.md b/WIRING.md
index 63ae2f611..bddb1614c 100644
--- a/WIRING.md
+++ b/WIRING.md
@@ -36,7 +36,11 @@ Diagram:
     |            |                          |        |                            |          |    |          |
     |            |                          |        |>==========================>|          |    |          |
     |            |                          |        |                            +----------+    |          |
-    |            |                          |        |                                            |          |
+    |            |                          |        |                     +---+                  |          |
+    |            |                          |        |       +-------------| R |                  |          |
+    |            |                          |        |>=====>| Application +---+                  |          |
+    |            |                          |        |       | Services     |                     |          |
+    |            |                          |        |       +--------------+                     |          |
     |            |                          |        |                                     +---+  |          |
     |            |                          |        |                            +--------| R |  |          |
     |            |                          |        |                            | Client +---+  |          |
@@ -190,3 +194,36 @@ choke-point to implement ratelimiting and backoff correctly.
  * Reads new events and the current state of the rooms from logs writeen by the Room Server.
  * Reads the position of the read marker from the Receipts Server.
  * Makes outbound HTTP hits to the push server for the client device.
+
+## Application Service
+
+ * Receives events from the Room Server.
+ * Filters events and sends them to each registered application service.
+ * Runs a separate goroutine for each application service.
+
+# Internal Component API
+
+Some dendrite components use internal APIs to communicate information back
+and forth between each other. There are two implementations of each API, one
+that uses HTTP requests and one that does not. The HTTP implementation is
+used in multi-process mode, so processes on separate computers may still
+communicate, whereas in single-process or Monolith mode, the direct
+implementation is used. HTTP is preferred here to kafka streams as it allows
+for request responses.
+
+Running `dendrite-monolith-server` will set up direct connections between
+components, whereas running each individual component (which are only run in
+multi-process mode) will set up HTTP-based connections.
+
+The functions that make HTTP requests to internal APIs of a component are
+located in `/<component name>/api/<name>.go`, named according to what
+functionality they cover. Each of these requests are handled in `/<component
+name>/<name>/<name>.go`.
+
+As an example, the `appservices` component allows other Dendrite components
+to query external application services via its internal API. A component
+would call the desired function in `/appservices/api/query.go`. In
+multi-process mode, this would send an internal HTTP request, which would
+be handled by a function in `/appservices/query/query.go`. In single-process
+mode, no internal HTTP request occurs, instead functions are simply called
+directly, thus requiring no changes on the calling component's end.