add ard-011, edit arch-v1

2 files changed, 50 insertions, 3 deletions

diff --git a/requirements/architecture/arch-v1.md b/requirements/architecture/arch-v1.md
index 0d25e78..41fadca 100644
--- a/requirements/architecture/arch-v1.md
+++ b/requirements/architecture/arch-v1.md
@@ -26,7 +26,7 @@ Status: draft
 - There must be a CRDT sync server (ard-003)
 - There must be a REST API, which sends and receives messages to and from the
   desktop GUI and the Web GUI via HTTPS, and sends and receives messages to and
-  from the CRDT sync server via Unix sockets (ard-004)
+  from the CRDT sync server via Unix sockets (ard-004, ard-011)
 - The Web GUI must persist domain entities in IndexedDB (ard-005)
 - The CRDT sync server must persist domain entities in an SQLite file (ard-006)
 - There must be a backups bucket, running on a separate machine to the CRDT sync
@@ -42,9 +42,9 @@ Status: draft
   software on the server machine (ard-008)
 - There must be a Web app server, which serves a Web GUI over HTTPS (ard-009)
 - The Web GUI must persist config and caches to Local Storage (ard-010)
-- There must be an SMS API
+- There must be an SMS API (req-031, req-045, req-047, req-053)
 - The SMS API must send and receive messages to the CRDT sync server via Unix
-  sockets
+  sockets (ard-011)
 
 ## Gaps
 
diff --git a/requirements/architecture/ard-011.md b/requirements/architecture/ard-011.md
new file mode 100644
index 0000000..6fb47d3
--- /dev/null
+++ b/requirements/architecture/ard-011.md
@@ -0,0 +1,47 @@
+# ard-011: Unix sockets for IPC on the server machine
+
+## Problem
+
+The architecture already grants that the CRDT sync server, REST API and SMS API
+will run on the same machine (ard-008). Given that the REST API and SMS API are
+needed for read and write operations on the domain data (see e.g. req-031,
+req-047, req-021, req-048), and given that the domain data is stored in an
+SQLite file, the REST API and the SMS API need some way of accessing that SQLite
+file.
+
+## Options
+
+- The CRDT sync server does not run as an independent process
+  - The APIs access the SQLite file directly using file and SQLite APIs
+  - The APIs access the SQLite file using a CRDT sync library
+- The CRDT sync server runs as an independent process
+  - The APIs communicate with the CRDT sync server via Unix sockets
+  - The APIs communicate with the CRDT sync server via Unix pipes
+  - The APIs communicate with the CRDT sync server via TCP/UDP
+  - The APIs communicate with the CRDT sync server via files
+
+## Decision
+
+The APIs must communicate with the CRDT sync server running as an independent
+process via Unix sockets.
+
+## Discussion
+
+The option to have the CRDT sync server not running as an independent process
+implies that both the SMS API and the REST API will access the same SQLite file
+directly. I assume that it is not feasible to have the SMS API and the REST API
+run in the same process. It follows that this option implies the possibility of
+two processes trying to access the same file at the same time, which is very
+risky. That rules out that option.
+
+Unix pipes work best as one-directional, but we need two-directional
+communication, so that rules out that option.
+
+File-based communication is not great for real-time two-way communications. That
+rules out that option.
+
+There's not a huge amount between Unix sockets and TCP/UDP. But (a) I suspect
+that Unix sockets is simpler to implement, (b) I would like to try it out, as I
+haven't used Unix sockets before, and (c) Unix sockets is a standard solution
+for two-way ICP, and I'm not aware of any special requirements for this case, so
+this is therefore good enough.