Merge branches/quickjs to trunk. This is the way.

git-svn-id: https://www.unprompted.com/svn/projects/tildefriends/trunk@3621 ed5197a5-7fde-0310-b194-c3ffbd925b24

apps/cory/docs/structure.md

@@ -0,0 +1,67 @@
+# Tilde Friends Structure
+[Back to index](#index)
+
+Tilde Friends is a mostly-self-contained executable written in C.
+
+In combines the following key components:
+- A Secure Scuttlebutt (SSB) client/server.  This talks with other SSB
+  instances, storing messages and blobs for anyone visible to local
+  users as they are encountered and sharing anything published locally
+  as appropriate.
+- An sqlite database.  This is where the SSB instance stores its data.
+  The general schema involves a `messages` table, storing mostly JSON,
+  a `blobs` table storing arbitrary blob data, and a `properties` table,
+  storing arbitrary state gleaned from `messages` and `blobs`, generally
+  updated on demand and incrementally.
+- A QuickJS runtime.  The core process runs stock scripts and has access
+  and permission to use all resources.  All other processes, which
+  includes everything which runs untrusted code created by Tilde Friends
+  users, are strictly sandboxed in ways similar to how web browsers run
+  untrusted code.  All attempts to access potentially sensitive resources
+  are mediated through the core process.
+
+When run with no arguments, it starts a web server on
+[http://localhost:12345/](http://localhost:12345/) and an SSB server.
+
+## Web Interface
+The Tilde Friends web server provides access to Tilde Friends applications,
+which are arbitrary user-defined web applications.
+
+At the top left, in addition to some basic navigation links, is an `edit`
+link.  Anyone can view, modify, and run in-place the code to any Tilde
+Friends application by using the in-browser editor.
+
+At the top right, one can `login` (to save work in their own space)
+or `logout` (proceeding as a guest).
+
+The rest of the page is an iframe belonging to the application.
+
+## Special Paths
+
+- `/~user/app/` - Tilde Friends application paths take the form `/~user/app/`, where `user`
+is a username of a Tilde Friends account, and `app` is an arbitrary name
+of an application saved by the given user.
+- `/~user/app/file` - A raw file in an app.
+- `/&blobid.ed25519` - A raw blob.  Content-Type is inferred for at least
+	a few common image types.
+
+## Communication Channels
+Web Browser <-> Core <-> Sandbox
+
+Visiting an application path delivers stock HTML and JavaScript which
+establishes a WebSocket connection back to the server.
+
+At this point, a new sandbox process is started in Tilde Friends, much
+as a new sandboxed process might be started for a new tab in a web
+browser.  This process has a custom RPC connection to the core process
+which holds the WebSocket connection to the browser.
+
+The custom RPC communication between the sandbox process and the core
+process facilitates calling functions asynchronously.  Calling a remote
+function (ie. a function in another process) returns a `Promise`.  In
+addition, any functions passed in either direction are serialized in
+such a way that they can be called remotely.
+
+An application will typically call `app.setDocument()` at startup to
+populate the app's iframe in the web browser with its own client web
+application resources.