Improve architecture documentation

1 files changed, 51 insertions, 7 deletions

diff --git a/docs/architecture.md b/docs/architecture.md
index c0186f76c9..3c61dcfba1 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -1,3 +1,6 @@
+
+
+
 # Mullvad VPN app architecture
 
 This document describes the code architecture and how everything fits together.
@@ -15,12 +18,48 @@ My thought was that after this section every aspect of the app is explained
 under either the Mullvad or the Talpid header. So it's clear which part they
 belong to. I yet don't know if this makes sense though.
 
+## The daemon
+The client consists of two main parts - the daemon and the GUI, but there's also a CLI. The daemon
+is the process that's responsible for upholding the security guarantees of the client, it consists
+of an actor system so that it can drive many processes asynchronously, allowing for a multiplicity
+of clients.
+
+<img src="diagrams/daemon-components.png">
+
+The daemon receives commands from the [front-ends](#frontends) (GUI and CLI) via the management
+interface and these are serviced asynchronously via the daemon, often interacting via various other
+components during and after the RPC has been finished. There are various dependencies between the
+different components and it's important to ensure no deadlocks occur, and some executions flows that
+provide essential behavior can be hard to trace.
+
+<img src="diagrams/update-relay-constraints.png">
+
 
 ## Mullvad part of daemon
 
 ### Frontend <-> system service communication
+This is done via GRPC ([here's](../mullvad-management-interface/proto/management_interface.proto)
+the relevant proto file) over a Unix domain socket on desktop platforms and via a JNI on Android. In
+both cases, the frontends end up sending a message to the daemon that it then services. The
+servicing of any message must never block any other message. Frontends can also subscribe to
+messages from the daemon, to receive updates about the tunnel state, new settings, new relay lists,
+version information and device events.
+
 
-### Talking to api.mullvad.net
+### Talking to api.mullvad.net.
+Reaching the API is done via a direct TLS connection to the API host or via a shadowsocks bridge, to
+increase censorship resistance. There are multiple components that interact with the API in an
+asynchronous fashion, so to manage them all, there's an actor that specifically deals with sending
+REST requests to the API.
+
+The API must be reachable in secured states even if a tunnel is not up, so the API runtime interacts
+with the [tunnel state machine](#tunnel-state-machine) to send over the currently used API endpoint.
+This can be a source of deadlocks, so no actor should ever be blocked by an API request if the TSM
+relies on it to change states.
+
+All API requests can be dropped in flight to allow for resetting the connection whenever a tunnel is
+established. The API requests can also be blocked when in the offline state or when it's assumed
+that the user hasn't used our client for a period of time.
 
 ### Selecting relay and bridge servers
 See [this document](relay-selector.md).
@@ -92,7 +131,14 @@ A high-level overview of the tunnel state machine can be seen in the diagram bel
 #### State machine inputs
 
 There are two types of inputs that the tunnel state machine react to. The first one is commands sent
-to the state machine, and the second is external events that the state machine listens to.
+to the state machine, and the second is external events that the state machine listens to. Reacting
+to any event can result in the state machine transitioning away to a different state.
+
+<img src="diagrams/tsm-connecting-enter.png">
+
+
+
+
 
 ##### Tunnel commands
 
@@ -176,11 +222,9 @@ Linux.
 
 #### macOS
 
-On macOS,  the offline monitor uses [`SCNetworkReachability`] callbacks to detect changes in
-connectivity and then enumerates network interfaces via [`SCDynamicStore`] and assumes connectivity
-if an active physical interface exists. The interfaces are enumerated because sometimes
-`SCNetworkReachability` can trigger a callback signalling full connectivity even when there exists
-no default route.
+On macOS,  the offline monitor uses `route -n monitor -` to listen for changes in the routing table,
+reasserting that a default route exists any time a change is detected. It's only assumed that the
+host is offline if a default route doesn't exist.
 
 ##### Issues