From 0d88998f4f5e682452b587fb6fda84861ff34a9b Mon Sep 17 00:00:00 2001
From: Rebecca Thompson <33927854+rebecca-thompson@users.noreply.github.com>
Date: Fri, 13 Feb 2026 12:51:44 +0000
Subject: [PATCH 1/2] update readme

---
 README.md | 50 ++++++++++++++++++++++++++++++++++----------------
 1 file changed, 34 insertions(+), 16 deletions(-)

diff --git a/README.md b/README.md
index 4bf71e3..e9af7af 100644
--- a/README.md
+++ b/README.md
@@ -1,44 +1,62 @@
 ### Editorial Collaboration
 
-This is a Node application written in TypeScript.
+This is a monorepo for a set of tools related to collaboration in the newsroom. 
 
-#### Setup
-You will need Brew and Docker installed on your machine to run the setup script.
+It currently has one project (not in production), which will support displaying edit history and multi-user collaboration for a document.
+
+The vision is it will be adopted into Composer (and perhaps other tools), improving the speed, efficiency and confidence in our text editors.
+
+#### Local development
+To run this locally you will need:
+
+- Brew and Docker installed on your development machine
+- AWS credentials for the Composer account.
+
+Once you have these, run:
 
-To set up, run the following command:
 ```bash
 ./scripts/setup
 ```
 
-#### Start
-To start, run the following command:
+And then:
 ```bash
 ./scripts/start
 ```
 
 #### Testing
 
-Tests for the API are written using Jest. To run the tests, run the following command from the Collab directory:
+Tests for the API are written using Jest. To run the tests, run the following command from the collab directory:
 
 ```bash
 npm run test
 ```
 
-or for live updates
+Or for live updates:
 
 ```bash
 npm run test-watch
 ```
 
-#### Architecture
+#### Architecture & Technology
 
-The Node server runs on an EC2 instance. We persist edit history steps in an RDS managed Postgres database. 
+The API is a Node server running on an EC2 instance. We persist steps in an RDS managed Postgres database.
 
 ```mermaid
-flowchart
-    N["Node Server \n <i>EC2</i>"]
-    P[("Postgres DB \n <i>RDS</i>")]
-    subgraph VPC
-        N --persists edit history--> P
-    end
+flowchart LR
+    C["Client (e.g. Composer)"]
+N["Collab API (<i>Node on EC2</i>)"]
+P[("Postgres DB (<i>RDS</i>)")]
+C<-->N
+subgraph VPC
+N <--read/writes--> P
+end
 ```
+
+We use [Prosemirror](https://prosemirror.net/) as our rich text editor, which has a plugin to support [collaborative editing](https://prosemirror.net/) in the browser.
+
+For those new to Prosemirror and collaborative editing, here is some further reading/viewing, which may be of interest:
+
+- [Intro to ProseMirror](https://marijnhaverbeke.nl/blog/prosemirror.html)
+- [Collaborative Editing in ProseMirror](https://marijnhaverbeke.nl/blog/collaborative-editing.html)
+- [Edit history spike – knowledge sharing recording](https://drive.google.com/file/d/1V8t8AtSMSJTIc-P7QbU4pwTh9lPL9dQg/view)
+- [Slides from knowledge sharing recording](https://docs.google.com/presentation/d/15lVehN3EVA8ed2NqxF1Hz1s--E18h4QE8Wcf-zvgNE0)

From 7496e3f2674dd37a63d8d56d27d66c4429d415b6 Mon Sep 17 00:00:00 2001
From: Rebecca Thompson <33927854+rebecca-thompson@users.noreply.github.com>
Date: Fri, 13 Feb 2026 12:52:00 +0000
Subject: [PATCH 2/2] make database migration work locally

---
 collab/postgres/index.ts | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/collab/postgres/index.ts b/collab/postgres/index.ts
index dd96bf3..e676510 100644
--- a/collab/postgres/index.ts
+++ b/collab/postgres/index.ts
@@ -12,13 +12,15 @@ type PostgresError = {
   code: string;
 }
 
+const host = process.env['db.host'] ?? '';
+
 const sql = postgres({
-  host: process.env['db.host'] ?? '',
+  host,
   port: parseInt(process.env['db.port'] ?? ''),
   database: process.env['db.database'] ?? '',
   username: process.env['db.username'] ?? '',
   password: process.env['db.password'] ?? '',
-  ssl: 'require',
+  ssl: host === 'localhost' ? 'prefer' : 'require',
 });
 
 const migrate = async () => {