From cef3ba0df16bb32d8c62f36c0d39e110c31f4abb Mon Sep 17 00:00:00 2001
From: vilmibm <nathanielksmith@gmail.com>
Date: Wed, 20 May 2020 04:19:49 +0000
Subject: [PATCH] readme

---
 README.md | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 97 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..058ca87
--- /dev/null
+++ b/README.md
@@ -0,0 +1,97 @@
+# bustle
+
+being an ambient activity feed for tilde.town
+
+## development plan
+
+- [ ] skeletal server
+- [ ] skeletal client
+- [ ] manually created proof of concept spool files for a few users
+- [ ] basic `bustle update <something>` (decide on protocol)
+  - [ ] receiving client update
+  - [ ] writing audit log
+  - [ ] writing to bustle.log
+- [ ] basic `bustle` command
+- [ ] proof of concept inotify implementation
+- [ ] bbj integration
+- [ ] user management task
+- [ ] event aggregation, sampling, and throttling
+- [ ] ...honestly if you can even get to hear you can worry about what is next then.
+
+## motivation
+
+it's quiet. you've shelled into tilde.town but until you take one of the following actions you will have no idea what else is happening on the server:
+
+- run chat
+- run bbj
+- run feels
+
+all of these have different problems.
+
+chat:
+
+- it requires energy and social grace
+- it might be empty; worse, it might /seem/ empty when you join
+- it can get addictive
+- it can get heated
+- you don't see people that don't like chat. some of those people might be your new best friends.
+
+bbj:
+
+- the pace is slow
+- it's hard to tell what conversations are already going
+- admin can't figure out how to unsticky stuff
+
+feels:
+
+- the pace is slow
+- it's read-only in that you can't respond to people
+
+instead, what about a new command `bustle`:
+
+```
+$ bustle
+
+you hear faint noise in the chat room
+
+       ~endorphant is moving around in their home directory
+
+  ~vilmibm just added to their public\_html
+
+                     some things are knocking around on bbj
+
+    ~selfsame just created a new file
+
+  there is a rattling sound in ttbp
+
+someone shouts, 'HI WORLD'
+
+                   ~archangelic shouts, 'HELLO BACK'
+
+```
+
+## architecture brainpuke
+
+I am not sure how to do this without a daemon process. Something needs to be listening to inotify
+events, listening for shouts, and ready to receive API hooks.
+
+### How should the daemon work?
+
+- for shouts and bot integration, every user gets a file in /town/bustle/spool/. bustled does a select over every file. a scheduled task adds and removes spool files based on who exists on the system.
+- for file activity, some kind of inotify watcher.
+
+### How should user clients work?
+
+when you run `bustle`, it enters a loop. at some interval, messages print. should a connection be
+maintained with bustled waiting with recv? I don't think so, since the log is not personalized. what
+if `bustle` is just a fancy `tail -f` on a file, `/town/bustle/bustle.log`? i think that's fine. i
+want running bustle to be exciting and cute, animating the messages in various ways. someone who
+just wants the log is free to read `/town/bustle/bustle.log`.
+
+
+### How should API clients work?
+
+I'd like to be able to report on irc, bbj, and feels events. feels can be a special case of just
+users editing in their home dir, but bbj and irc are more special. i think to start those services
+will just get a spool file like a normal user and then write to it programmatically. this will
+require modification of bbj and hooking into an irc bot run as some user.