Add some basic arch diagrams/descriptions.

diff --git a/ARCH.md b/ARCH.md
new file mode 100644 (file)
index 0000000..dba91e7
--- /dev/null
+++ b/ARCH.md
@@ -0,0 +1,62 @@
+Rust-Lightning is broken into a number of high-level structures with APIs to hook them
+together, as well as APIs for you, the user, to provide external data.
+
+The two most important structures which nearly every application of Rust-Lightning will
+need to use are `ChannelManager` and `ChannelMonitor`. `ChannelManager` holds multiple
+channels, routes payments between them, and exposes a simple API to make and receive
+payments. Individual `ChannelMonitor`s monitor the on-chain state of a channel, punish
+counterparties if they misbehave, and force-close channels if they contain unresolved
+HTLCs which are near expiration. The `ManyChannelMonitor` API provides a way for you to
+receive `ChannelMonitorUpdate`s from `ChannelManager` and persist them to disk before the
+channel steps forward.
+
+There are two additional important structures that you may use either on the same device
+as the `ChannelManager` or on a separate one. `Router` handles receiving channel and node
+node announcements and calculates routes for sending payments. `PeerManager` handles the
+authenticated and encrypted communication protocol, monitoring for liveness of peers,
+routing messages to `ChannelManager` and `Router` instances directly, and receiving
+messages from them via the `EventsProvider` interface.
+
+These structs communicate with each other using a public API, so that you can easily add
+a proxy in between for special handling. Further, APIs for key generation, transaction
+broadcasting, block fetching, and fee estimation must be implemented and the data
+provided by you, the user.
+
+The library does not rely on the presence of a runtime environment outside of access to
+heap, atomic integers, and basic Mutex primitives. This means the library will never
+spawn threads or take any action whatsoever except when you call into it. Thus,
+`ChannelManager` and `PeerManager` have public functions which you should call on a timer,
+network reads and writes are external and provided by you, and the library relies only on
+block time for current time knowledge.
+
+At a high level, some of the common interfaces fit together as follows:
+
+
+```
+
+                     -----------------
+                     | KeysInterface |  --------------
+                     -----------------  | UserConfig |
+         --------------------       |   --------------
+  /------| MessageSendEvent |       |   |     ----------------
+ |       --------------------       |   |     | FeeEstimator |
+ |   (as MessageSendEventsProvider) |   |     ----------------
+ |                         ^        |   |    /          |      ------------------------
+ |                          \       |   |   /      ---------> | BroadcasterInterface |
+ |                           \      |   |  /      /     |     ------------------------
+ |                            \     v   v v      /      v        ^
+ |    (as                      ------------------       ----------------------
+ |    ChannelMessageHandler)-> | ChannelManager | ----> | ManyChannelMonitor |
+ v               /             ------------------       ----------------------
+--------------- /                ^         (as EventsProvider)   ^
+| PeerManager |-                 |              \     /         /
+---------------                  |        -------\---/----------
+ |              -----------------------  /        \ /
+ |              | ChainWatchInterface | -          v
+ |              -----------------------        ---------
+ |                            |                | Event |
+(as RoutingMessageHandler)    v                ---------
+  \                   ----------
+   -----------------> | Router |
+                      ----------
+```