From 5d2ebdd2b3e20fc3f828a005ba75f10e2eea62e7 Mon Sep 17 00:00:00 2001 From: Joe Carstairs Date: Fri, 18 Jul 2025 19:25:43 +0100 Subject: add ard-007, ard-008, edit ard-004, ard-006 --- requirements/architecture/arch-v1.md | 17 +++++++------ requirements/architecture/ard-004.md | 2 +- requirements/architecture/ard-006.md | 2 +- requirements/architecture/ard-007.md | 40 +++++++++++++++++++++++++++++++ requirements/architecture/ard-008.md | 46 ++++++++++++++++++++++++++++++++++++ requirements/assumptions/ass-018.md | 3 +++ 6 files changed, 101 insertions(+), 9 deletions(-) create mode 100644 requirements/architecture/ard-007.md create mode 100644 requirements/architecture/ard-008.md create mode 100644 requirements/assumptions/ass-018.md diff --git a/requirements/architecture/arch-v1.md b/requirements/architecture/arch-v1.md index d9874d3..857f988 100644 --- a/requirements/architecture/arch-v1.md +++ b/requirements/architecture/arch-v1.md @@ -12,6 +12,7 @@ Status: draft - Schist must persist buckets, pipes, drips, and transactions (req-034, req-056, req-057, req-058, req-051) - Schist's persisted data must be resilient and recoverable (req-064) +- Schist should have a Web GUI (ass-018) ## Decisions @@ -26,15 +27,15 @@ Status: draft from the CRDT sync server via Unix sockets (ard-004) - 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 backup service -- The backup service must communicate to the backups bucket via HTTPS -- There must be a backups bucket -- There must be a server machine -- The backups bucket and the server machine must be different machines +- There must be a backups bucket, running on a separate machine to the CRDT sync + server and the users' machines (ard-007) +- There must be a backup service, which makes regular backups of the CRDT sync + server from the same machine, and stores the backups in the backups bucket + over HTTPS (ard-007) - The server machine must host the CRDT sync server, the SQLite file, the backup - service, the REST API, the SMS API and the Web GUI + service, the REST API, the SMS API and the Web GUI (ard-008) - There must be documented processes for installing, updating and operating the - software on the server machine + software on the server machine (ard-008) - There must be documented processes for installing and updating the desktop GUI on the user's machine - There must be a documented process for recovering the server machine from a @@ -52,3 +53,5 @@ Status: draft (req-062) - Schist must not allow anybody other than the user to access its data in motion (req-063) +- Do we need or want any virtualisation or containerisation on the CRDT sync + server? diff --git a/requirements/architecture/ard-004.md b/requirements/architecture/ard-004.md index 9ce6d73..643dc7c 100644 --- a/requirements/architecture/ard-004.md +++ b/requirements/architecture/ard-004.md @@ -1,4 +1,4 @@ -# ard-004 +# ard-004: REST API for communication between UIs and the CRDT sync server ## Problem diff --git a/requirements/architecture/ard-006.md b/requirements/architecture/ard-006.md index da45169..78604cd 100644 --- a/requirements/architecture/ard-006.md +++ b/requirements/architecture/ard-006.md @@ -1,4 +1,4 @@ -# ard-006 +# ard-006: SQLite storage for the CRDT sync server ## Problem diff --git a/requirements/architecture/ard-007.md b/requirements/architecture/ard-007.md new file mode 100644 index 0000000..0df0480 --- /dev/null +++ b/requirements/architecture/ard-007.md @@ -0,0 +1,40 @@ +# ard-007: backup bucket and service on the CRDT sync server + +## Problem + +Schist's persisted data must be recoverable (req-067). + +It has already been decided that Schist will persist data in IndexedDB on the +Web GUI (ard-005), in SQLite on the desktop GUI (ard-001) and in SQLite on the +CRDT sync server (ard-006). + +## Decision + +Schist must have a backup bucket on separate storage media to the CRDT sync +server and the users' machines. Schist must have a backup service running on the +same machine as the CRDT sync server, which regularly makes backups and stores +them in the bucket. + +## Discussion + +In order for data to be recoverable, there must be backups. There are no +alternatives to this. + +The backups could be stored on the same media, but this is less secure than +storing it on separate media. + +You could back-up the Web GUI, the desktop GUI and the CRDT sync server. +However, once the CRDT sync server is working, all the other components can rely +on the CRDT sync server's back-ups, and in the meantime, the user can be +responsible for making the data on their own machines secure, for example, by +backing up their entire hard drive. It's generally not done for user apps to be +responsible for their own backups of local data for this reason. + +Therefore, we will have a bucket on its own media, backing up only the CRDT sync +server. In order for the backups to get stored there, we must have some service +making the backups. And in order for the service to have easy access to the +SQLite file which it is backing up, it makes sense for the service to run on the +same machine as the SQLite file, and therefore the same machine as the CRDT sync +server. + +HTTPS is an acceptable communications protocol. No alternatives were considered. diff --git a/requirements/architecture/ard-008.md b/requirements/architecture/ard-008.md new file mode 100644 index 0000000..f728642 --- /dev/null +++ b/requirements/architecture/ard-008.md @@ -0,0 +1,46 @@ +# ard-008: monolith architecture + +## Problem + +The architecture already contains the following software components running +remotely from the user: + +- A CRDT sync server (ard-003) +- An SQLite file which the CRDT sync server uses to store domain data (ard-006) +- A backup service (ard-007) +- A REST API (ard-004) +- An SMS API (req-031, req-045, req-047, req-053) +- A Web app server (ass-018) + +We need to decide how these components will be distributed across hardware. + +## Options + +- Microservice architecture +- Monolith architecture +- Something in-between + +## Decision + +Schist must have all the remote components - the CRDT sync server, the SQLite +file, the backup service, the REST API, the SMS API and the Web app server - +running on a single machine. + +## Discussion + +Dividing software components between hardware units is good for applications +where scalability and resilience are very important. However, Schist is likely +to be a low-risk application with at most one user, so these features are not +important. + +On the other hand, dividing software components between hardware units is +complicated to set up and maintain and more expensive to operate. + +For that reason, Schist will swing hard in the direction of monolith +architecture. This will keep things simple, and is appropriate in this low-risk, +small-scale application. + +## Consequences + +There must be documented processes for installing, updating and operating the +software on the server machine. diff --git a/requirements/assumptions/ass-018.md b/requirements/assumptions/ass-018.md new file mode 100644 index 0000000..6314e5c --- /dev/null +++ b/requirements/assumptions/ass-018.md @@ -0,0 +1,3 @@ +# ass-018 + +Schist should have a Web GUI. -- cgit v1.2.3