diff options
Diffstat (limited to 'doc/source/architecture.rst')
| -rw-r--r-- | doc/source/architecture.rst | 87 |
1 files changed, 87 insertions, 0 deletions
diff --git a/doc/source/architecture.rst b/doc/source/architecture.rst new file mode 100644 index 0000000..4cca49a --- /dev/null +++ b/doc/source/architecture.rst @@ -0,0 +1,87 @@ + +Architecture +============ + +The BSFS stack can be coarsely divided into four parts (see the image below). + +* Envelope: Essentials and utils used throughout the whole codebase. +* Front: End-user applications and APIs. +* Center: The core interfaces and functionality. +* Back: The triple store backends. + +Details of these components are given in the sections below. + + +.. image:: _static/arch_light.png + :class: only-light + +.. image:: _static/arch_dark.png + :class: only-dark + + +Envelope +-------- + +Most notably, the envelope covers the :class:`Schema <bsfs.schema.schema.Schema>` and the :mod:`Query syntax trees (AST) <bsfs.query.ast>`. +Both of them essential for all parts of the BSFS stack. +For example, the schema is specified by the user via the :func:`Migrate <bsfs.apps.migrate.main>` command, checked and extended by the :class:`Graph <bsfs.graph.graph.Graph>`, and ultimately stored by a :class:`Triple Store backend <bsfs.triple_store.base.TripleStoreBase>`. +Similarly, the Query AST may be provided by a caller and is translated to a database query by a backend. +In addition, the envelope also contains some classes to handle URIs: +:class:`URI <bsfs.utils.uri.URI>` defines the URI base class, +:class:`Namespace <bsfs.namespace.Namespace>` provides shortcuts to generate URIs, and +:mod:`UUID <bsfs.utils.uuid>` is used to generate unique URIs. + + +Front +----- + +The front consists of exposed interfaces such as end-user applications or APIs, +and all utils needed to offer this functionality. +See :mod:`bsfs.apps` and :mod:`bsfs.front`. + + +Center +------ + +The heart of BSFS is grouped around the :mod:`bsfs.graph` module. +These classes provide the interface to navigate and manipulate the file graph +in a safe and programmer friendly manner. +Some of them are indirectly exposed through the higher-level APIs. + +The two core design principles of BSFS are the focus on nodes and batch processing. +They are realized in the the Graph and Nodes classes. +The :class:`Graph class <bsfs.graph.graph.Graph>` manages the graph as a whole, +and offers methods to get a specific set of Nodes. +In turn, the :class:`Nodes class <bsfs.graph.nodes.Nodes>` represents such a set of nodes, +and performs operations on the whole node set at once. +Besides, the :mod:`bsfs.graph` module also comes with some syntactic sugar. + +Example:: + + # Open a file graph. + from bsfs import Open, ns + graph = Open(...) + # Get all nodes of type File. + nodes = graph.all(ns.bsfs.File) + # Set the author of all nodes at once. + nodes.set(ns.bse.author, 'Myself') + # Retrieve the author of all nodes at once. + set(nodes.get(ns.bse.author, node=False)) + # Same as above, but shorter. + set(nodes.comment(node=False)) + + +Back +---- + +There are various graph databases (e.g., `RDFLib`_, `Blazegraph`_, `Titan`_, etc.) +and it would be foolish to replicate the work that others have done. +Instead, we use third-party stores that take care of how to store and manage the data. +The :class:`Backend base class <bsfs.triple_store.base.TripleStoreBase>` defines the +interface to integrate any such third-party store to BSFS. +Besides storing the data, a triple store backend also need to track the current schema. + + +.. _RDFLib: https://rdflib.readthedocs.io/en/stable/index.html +.. _Blazegraph: https://blazegraph.com/ +.. _Titan: http://titan.thinkaurelius.com/ |