documentation

README.md

@@ -0,0 +1,6 @@
+# Planner
+
+Currently in the early stages, `planner` will have:
+
+- A simple personal [synchronization service](doc/sync.md) for one small snippets of data (tasks, notes, calender items, etc.)
+- An ecosystem of apps for specific use on type of data and platform (cli, mobile, desktop, Homeassistant add-on)

doc/sync.md

@@ -0,0 +1,34 @@
+# Synchronisation
+
+Items:
+
+- Have an ID and a timestamp of last update
+- Have a "kind" (task, note, etc.) to allow for selective synchronisation
+- Have a "deleted" flag
+- Are kept long enough (months) on the server after deletion to let all clients know about its removal
+
+Server:
+
+- Has `update` handler to receive new (versions of) items
+- New (versions of) an item get timestamped by the server upon persisting
+- Has `updated` handler to return items that are updated after a certain timestamp
+
+Client:
+
+- Collects local updates in sync table
+- Sends local updates to server
+- Requests updates from server since previous sync action
+- The just sent updates also get retrieved again, but with server timestamp
+- Applies those updates to local state
+
+## Notes
+
+- The server timestamp is the version number
+- Local sync table serves as a queue when used offline
+- There is only one user
+- New items are generated by user and by bots/scripts
+- Only the user will modify items, in one client at the time
+- Race conditions are therefore very unlikely
+- If there is one, last client that sends its updates "wins"
+- No conflict resolution left out for simplicity
+- Full sync can be achieved by purging local database and sync with zero timestamp