# HG changeset patch
# User drewp@bigasterisk.com
# Date 1710621909 25200
# Node ID b72f4ba1345dedf9f3f1915cadaa37cf46bbbc38
# Parent  25538e3ee531800c26c4c277b8fab71705dd13d8
design notes

diff -r 25538e3ee531 -r b72f4ba1345d README.md
--- a/README.md	Sat Mar 16 12:51:39 2024 -0700
+++ b/README.md	Sat Mar 16 13:45:09 2024 -0700
@@ -1,2 +1,57 @@
 # rdferry
 
+A library for python and typescript.
+
+(Rewrites/replaces my rdfdb and patchablegraph projects)
+
+Goals:
+
+- ferry graphs of RDF statements between disk/server/browser
+- keep them in sync
+- use starlette, uvicorn, rdflib in python
+- use N3.js in typescript
+
+Throughout this doc, 'graph' means PatchableGraph, a class that holds an rdflib.ConjuntiveGraph and edits it only through patches. A patch is a set of
+statements to delete and a set to add (in one operation).
+
+## API plans to turn into tested examples
+
+Each of these items should be a one-liner to set up.
+
+- server boilerplate with metrics and auto index page:
+  - `svr = StarletteServer()`
+  - `svr.serve() # if caller hasn't routed '/', serve auto index`
+
+### py
+
+- SSE -> graph
+  - `graph = GraphSseClient(url1)`
+  - `await graph.finishFirstRead()`
+- graph -> simple served text (StaticGraph)
+  - (part of addGraphRoutes)
+- graph -> SSE (GraphEvents)
+  - `svr.addGraphRoutes('name1', graph1)`
+- graph -> sparql -> table
+- k8s json -> graph
+  - `graph = K8sRead(type='Deploy', ns='default', name='deploy1', watch=True)`
+    - but break this into json-fetch and jsonld-convert
+- mqtt json/etc -> graph
+- csv -> graph
+  - `graph = FromCsv(r: csvReader)`
+- file -> graph -> file
+  - `graph = WatchFile(file: Path)`
+    - `await graph.finishFirstRead()`
+  - `graph = WatchTree(top: Path)`
+    - `await graph.finishFirstRead()`
+- multiple graphs -> readonlygraphaggregate (collector)
+  - `graph = PatchableAggregate([graph])`
+- http request -> statement(s) (rdf_over_http.py)
+  - `def handler1(stmt, requests): ...`
+  - `svr.addRdfStatementRoute('/path1', handler1)`
+  - `def handler2(graph, requests): ...`
+  - `svr.addGraphInputRoute('/path2', handler2)`
+
+### js
+
+- SSE -> graph
+  - new GraphSseClient(url1) (graphSseClient.graph: N3.Store)