Merge branch 'main' into protocol-adr

CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [2.0.0-beta.1](https://github.com/athensresearch/athens/compare/v2.0.0-beta.1...v2.0.0-beta.1) (2021-11-25)
+
+
+### Bug Fixes
+
+* run health check on client as well ([9161df0](https://github.com/athensresearch/athens/commit/9161df0814b5373452d285addfea881cc72f79cd))
+
+
+### Documentation
+
+* updates for 2.0.0-beta launch ([#1868](https://github.com/athensresearch/athens/issues/1868)) ([87b1e82](https://github.com/athensresearch/athens/commit/87b1e82df539ccf1c756481b67b36f273d5ca243))
+
 ## [1.0.0-alpha.rtc.46](https://github.com/athensresearch/athens/compare/v1.0.0-alpha.rtc.45...v1.0.0-alpha.rtc.46) (2021-11-21)
 
 

README.md

@@ -7,11 +7,11 @@
 
 # Athens
 
-Athens is a knowledge graph for research and notetaking. Athens is open-source, private, extensible, and community-driven.
+Athens is an open-source knowledge graph that helps individuals and organizations solve complex problems by enabling them to capture, compose, and recombine ideas.
 
-# 🚀 [Download the free desktop app](https://github.com/athensresearch/athens/releases) 🚀
+**[Download the free desktop app](https://athensresearch.github.io/docs/user_guide/installation)**
 
-**[Sponsor us on Open Collective](https://opencollective.com/athens) until we migrate to Stripe! We are building out a software service for individuals and teams and a [self-hosted/on-premise solution for enterprises](https://github.com/athensresearch/athens-backend).**
+**Check out our beta [self-hosted solution](https://athensresearch.github.io/docs/developer_guide/self-hosted) for those looking to collaborate in real-time.**
 
 **[Demo Athens in your browser (no changes are saved)](https://athensresearch.github.io/athens)**
 
@@ -20,11 +20,11 @@ Athens is a knowledge graph for research and notetaking. Athens is open-source,
 
 ### Private
 
-You can use Athens as a local desktop app that saves data to your filesystem or with a [self-hosted server](https://github.com/athensresearch/athens-backend).
+You can use Athens as a local desktop app that saves data to your filesystem or with a [self-hosted server](https://athensresearch.github.io/docs/developer_guide/self-hosted) for multi-device or multi-user access.
 
-### Extensible
+### Collaborative
 
-You can modify Athens's source code. We are also building a plugin system for custom themes, keybindings, and integrations with other data sources.
+You can use the collaborative version of Athens for block-level and page-level presence, or if you want to easily use Athens from multiple computers.
 
 ### Community-Driven
 
@@ -38,26 +38,25 @@ Athens lets you take notes without praying to the search gods, without double-cl
 
 Athens does this with **[[bidirectional links]]** and **((block references))** that let you to take notes on anything from any page. Just [[link]] or ((reference)) another page or block - and voilà! - you can now go to this page and see all the places that linked back to it. The next time you press `[[` or `((`, you will be indexing through your previous notes, helping you connect the dots. You've started creating a graph of your knowledge!
 
-# [Contributing](https://athensresearch.gitbook.io/handbook/contributing)
+# Contributing
 
-If you want to contribute to Athens as a developer or designer, please begin by reading [Contributing](https://athensresearch.gitbook.io/handbook/contributing). This also contains instructions on how to build Athens on your own computer.
+If you want to contribute to Athens as a developer or designer, please begin by reading our [Developer Guide](https://athensresearch.github.io/docs/developer_guide/running).
 
 Some tips once you've gotten Athens:
 - [How to use Athens](https://www.loom.com/share/ee5120d1f69d4ce0aab923de71caedd0)
 - [How to file a bug report](https://www.loom.com/share/e69857c0f65f4232ab10dd78f47c4c44)
 - [How to file a feature request](https://www.loom.com/share/dea9e3b3e7424f97a84e2fb81daed9c9)
 - If you have trouble with a new version of Athens, download a previous build on our [releases page](https://github.com/athensresearch/athens/releases).
 
-# [Pricing](https://opencollective.com/athens)
+# Pricing
 
-Athens is free to use as a local-only desktop app. We are currently building out a hosted software service that will start at $6/month. [We have a self-hosted/on-premise option for enterprises](https://github.com/athensresearch/athens-backend), comparable to GitLab or Mattermost. If you want to use Athens commercially, please contact us at [email protected].
-
-Please see our [Open Collective](https://opencollective.com/athens) for more details. We will be migrating to Stripe from OpenColllective.
+Athens is free to use as a local-only desktop app or as a self-hosted server. Please email us at [email protected] if you are interested in a self-hosted license or a hosted plan.
 
 # Blog
 
 To learn more about this project, please read:
 
+- [Season 2 - A Collective Vision](https://athensresearch.ghost.io/season-2/)
 - [Athens' $1.9M Seed Round, led by Caffeinated Capital](https://athensresearch.ghost.io/athens-1-9m-seed-round-led-by-caffeinated-capital/)
 - [Athens Joins Y Combinator](https://athensresearch.ghost.io/athens-joins-y-combinator/)
 - [MVP Update, Funding, and Why I Started Athens](https://athensresearch.ghost.io/mvp-update-funding-and-why-i-started-athens/)

doc/adr/0013-source-of-truth.md

@@ -0,0 +1,85 @@
+# 13. Source of Truth
+
+Date: 2021-10-13
+
+
+## Status
+
+Accepted.
+
+
+## Context
+
+We've moved all of our UI transaction centric events to semantic events, where we express the intent of the change rather that the database transaction representation.
+
+The Athens server and client both resolve data representations from these events and apply it to their local database, discarding the semantic event after resolution. 
+This resolution loses information, because the semantic event contains more than just the applied data, and is specific to the particular database solution used at the time.
+But the concrete running local database state constitutes the usable running system.
+
+The core of this problem is what constitutes the source of truth for the knowledge graph.
+The two candidates we have for source of truth are the database state and the the total sequence of events.
+
+Choosing a source of truth does not mean we will exclusively use it, and remove any usage of the other mechanism.
+Instead, the choice of source of truth informs how we should reason about the system and how should the system achieve desirable properties (e.g. resilience, performance).
+
+Athens remains a multi-user experience where each user is able to collaborate in real time, and where data should be retained for a long time.
+The decision will need to provide solutions for communication of data, both in the whole and incrementally, and for handling large amounts of data.
+
+
+## Decision
+
+To better understand the shortcomings of each approach let's look at them in isolation.
+Were we to use the database state as only source of truth, with no notion of incremental changes, we'd have to transmit at least partial snapshots on every change to all clients.
+Conversely, without a notion of state, loading a new client would require replaying the total sequence of events.
+Each approach individually is insuficient.
+
+The real-time collaboration imposes a hard requirement efficient state updates on clients, which in turn requires accurate incremental changes.
+By accurate, we mean that applying the incremental changes upon a state should leave all clients in the same state.
+Without this property clients would see increasingly different states, and client actions would not be correct.
+
+This property applies all the way to the initial empty state, which means that the accurate incremental changes requirement in effect means that a total sequence of events must exist and deterministically reduce to the final state.
+This in turn also means that any database state can be derived from the sequence of events.
+The opposite is not true, as the sequence of events cannot be derived from the resulting database state due to the loss of information described in the context above.
+This leaves us with the sequence of events as the more natural source of truth.
+
+Instead of discarding events after resolution, we can store them permanently and achieve some of the benefits of [Event Driven Architectures](https://en.wikipedia.org/wiki/Event-driven_architecture), especially around CQRS and Event Sourcing.
+Achieving full CQRS or Event Sourcing is not a goal in and of itself.
+
+Major benefits in our case include:
+
+- ease of migration, between current databases and future ones
+- correctness checking, between two resolution implementations
+- debugging, via replaying history of changes to runtime
+- self-healing of databases, by replaying events with fixed resolutions
+- decoupling of event generation and consumption, allowing more sophisticated async and offline-first usecases
+- storage, for ephemeral databases
+
+We have decided to add an event log to the Athens server, to which we record every database-affecting operation.
+
+This event log will be implemented as an immutable append-only log in [Fluree](https://flur.ee/).
+
+Fluree was chosen because it offers a Datalog-adjacent query/transaction format, has a matching open-source licence we can use for the server (via Docker), good scalability, and a migration path to a cloud-native implementation. 
+
+Another relevant reason is that Fluree is a technology the team has been interested in experimenting with since it feels a good fit for the long-term Athens use case, so getting some experience with it on a very limited domain is valuable.
+
+It is impractical to always load the full log for large enough logs.
+Using state snapshots can help reduce this problem, given they function as a cache for replaying a set of logs.
+State snapshots can be used on the server, client, and as an export format to interact with other tools.
+
+
+## Consequences
+
+Besides enabling the scenarios described in [context](#context), there are also negative, or at least binding, consequences: 
+
+- total time to effect changes increases, because the server needs to store the events before processing it
+- the current event format becomes a frozen API that we need to support indefinitely, since all events must be replayable
+- extra storage needed to store the events, which grows at a similar pace or higher than the current data storage
+- the event storage format is another frozen API, since old events stored in the log need to be readable
+- increased memory usage for docker deployments due to the extra log service
+- limits on the event store (e.g. event size) are passed on to the system
+
+It is important to highlight that snapshots can and will differ according to the handling of events.
+While possible in principle to completely reproduce the original handlers for a snapshot, in practice this is hard and has diminishing returns.
+Prime is the case of benign bug fixes that change the output: the result was not the same, but the previous result was incorrect.
+For any given long running system using snapshots, it is likely that a fresh new system that replays all events will yield a slightly different snapshot.
+

package.json

@@ -1,7 +1,7 @@
 {
   "name": "Athens",
   "author": "athensresearch",
-  "version": "1.0.0-alpha.rtc.46",
+  "version": "2.0.0-beta.1",
   "description": "An open-source knowledege graph for research and notetaking",
   "repository": {
     "type": "git",