A suite of functionally independent building blocks affording most functionality commonly used in supply chain systems, project management software, logistics management and enterprise resource planning; as well as post-capitalist economic paradigms such as gift and contributory economies.
These and other components can be used to create distributed social, economic & resource coordination applications of any kind; by plugging together Holochain "zomes" (units of functionality) and "DNA modules" (fully decentralised, agent-centric, networked application microservices).
These are fully distributed, agent-centric applications. There are no transaction bottlenecks and individual networks can grow to planetary scale if needed.
- About
- Documentation
- hREA beyond Holochain
- Repository structure
- Other names
- License
What do we mean by "most functionality"?-
- group management: manage groups of collaborators and permission access between groups, sub-projects and across organisations
- event ledger: use the observation module to track the observed movements of resources, currencies and skills in any coordination space
- coordination functions: use planning modules to decide on future plans, manage agreements or coordinate actions with other participants
- needs matching: use proposal modules to group matched outcomes in order to describe bilateral and multilateral trade requests
- knowledge sharing: use the recipe module to share structured production knowledge and easily repeat well-understood processes
For a more detailed list of modules and features planned for development, see modules in the hREA framework.
A key aspect to note about these modules is that they require no technical knowledge to remix or re-architect into different social organising patterns. Different arrangements of network components can be used to address different use-cases in novel ways.
Most people making use of hREA will never have to delve into the software beyond this level. All modules in the suite have established APIs for interoperability and can be arranged into complex organisational patterns at runtime, like lego blocks. To see some concrete examples of this, see the scenarios orchestrated in test/social-architectures.
Beyond this outer layer the system has been designed with flexibility, modularity and composability as core architectural concerns. The depth to which you will delve into the architecture depends on a project's needs; i.e. how much customisation is required. See Repository Structure for a breakdown of how hREA fits together, how to customise it, and how to browse this repository.
High-level documentation for integrators, potential collaborators and entrepreneurs can be found in the project's ecosystem wiki. This includes information on hREA's organisational goals, strategic mission, design philosophy, cultural background and ideological positioning.
Developer documentation can be found in the docs/ directory. We keep it within the codebase instead of in the wiki so that all contributors retain the information necessary to understand, configure and run the system.
There is a quick start guide for those who want to spin up hREA locally for development or experimentation.
hREA is built to implement the ValueFlows protocol— a set of common vocabularies based on REA Accounting theory to describe flows of economic resources of all kinds within distributed economic ecosystems.
By building to align with the ValueFlows GraphQL spec, UI applications built for hREA are automatically compatible with other ValueFlows-compatible system backends like our partner project Bonfire.
The goal is to enable radical code reuse and cross-project interoperability between next-gen distributed backend systems and traditional web infrastructure, and to allow user interfaces to span multiple disparate apps.
This section details the layers of the system and where to find each set of components within this repository.
apps/contains end-user applications built on the HoloREA framework.apps/holorea-graphql-explorer/is a GraphiQL interface to the system with some added additions to assist with comprehension. Wired up to the development DNAs by default— super handy for testing and getting to know the ValueFlows data structure.
test/contains integration tests for the application suite as a whole. Connections to the GraphQL Interface and Holochain application cells are managed ininit.js.
The ValueFlows GraphQL spec is an effort towards composable application architectures for distributed socioeconomic coordination applications.
Though it exists outside of this repository and is co-governed by many stakeholders, it is worth mentioning here that ValueFlows GraphQL and the core ValueFlows RDF vocabulary are open protocols which accept proposals for improvement. Contributions to the domain model from non-technical authors are welcomed and encouraged.
If you are implementing systems which you'd like to be compatible with our interfaces and client applications, the ValueFlows GraphQL NodeJS module can be leveraged to build and validate implementations, and to export raw schema formats for injection into other software.
modules/graphql-client contains a NodeJS module exporting a configurable GraphQLClient generator function that provides provide a simplified and coherent entrypoint to the system. It contains some features which introspect the connected Holochain conductor to automatically determine the appropriate running DNA 'cells' to connect to under normal operations.
You should develop against this interface if:
- You are a UI app developer creating an application to run on top of standard hREA module functionality.
- You are a UI app developer extending hREA's functionality with custom business or domain-specific integrations (including web platforms, blockchain tech and other Holochain modules).
- You are a creator of distributed socioeconomic coordination applications and you would like your apps to run on hREA, Bonfire or other protocol-compatible storage backends.
- You are a UI app developer implementing a multi-agent UI (Holochain or otherwise), where the arrangements of hREA modules within a collaboration space do not diverge from standard configurations.
Note that there is a mock GraphQL client available for building ValueFlows apps against which does not require Holochain to be configured.
modules/vf-graphql-holochain is one layer deeper, at the level of GraphQL schemas and resolvers. It contains helper methods which wraps the underlying Holochain 'cell' connections exposed by the conductor API with the ValueFlows GraphQL schema and allows for combining and remixing collaboration spaces.
You should develop against this interface if:
- You are a UI app developer implementing a multi-agent UI (Holochain or otherwise) for a multi-stakeholder environment where hREA modules are complexly arranged across collaboration spaces. For example, two organisations with separate internal event logs (observation DNAs) collaborating in a shared planning DNA where some people might be members of both organisations.
For more information on usage and options, see the GraphQL Client and GraphQL Schema module directories.
There are a few sets of *.yaml configuration files used by Holochain in its build processes.
bundles/ contains configuration files which group Holochain 'DNA' modules into 'hApp bundles'. A hApp bundle contains all backend components accessible by a single UI application.
These bundles are used by the project scripts to run the application locally from this repository. There are also bundles_templates/ which are used by the Github releases process to build pre-packaged binaries for end-user installation into the Holochain Launcher; in combination with the webhapp/ configuration which also packages & associates a user interface. If you aren't developing hREA yourself this is a much easier way to setup the app— simply download the *.webhapp file from the releases page and open it with the Holochain Launcher.
happs/ configuration files group assemblages of "zomes" into Holochain DNAs.
DNAs are the highest-level units of functionality available in the system. One is available for each of the modules in the hREA framework.
The architecture of hREA is designed to be as flexible as possible between components. We aim to separate the overall hREA app 'suite' into sensible logical services which allow for composition and pluggability. For example, you might swap an external project management tool for the planning DNA; or bring in your own agreement handling functionality.
The configurations in this directory are for "standard" module deployments where the combination of functionality and separation of concerns follows established patterns in ValueFlows networks. You can use them as guides for creating configurations of your own.
You should customise at this layer if:
- You wish to bundle hREA modules differently- for example, including them adjacent to other third-party zomes which extend their behaviour; or keeping observation and planning records within the same shared DHT space.
- You wish to include components of hREA as embedded logic within bespoke context-specific DNAs.
Note that as Holochain matures it is likely that this kind of configuration will be wrapped up into various administration interfaces, or even hREA-specific orchestration wizards.
zomes/ is where the majority of the application logic resides. Each zome implements a modular set of functionality needed to support a single feature, and comes with consistency guarantees about its internal operations. In technical terms they are DHT storage + app logic + shared data validations + node-to-node messaging. These are implemented as Rust crates.
There are some simple registration zomes which only exist to link to remote Cargo dependencies.
rea_* zomes implement the core ValueFlows model. Each directory is typically broken down into at least five modules. From the outside inward, they are:
rea_*/rpc/ defines the structs needed to de/serialize data at the WASM API boundary for this zome.
You should develop against this interface if:
- You are developing higher-order or companion zomes designed to work with hREA.
- You are building Rust client applications on top of hREA.
rea_*/zome/ defines the WASM externs and source chain data structures for building each module in its default configuration.
Third-party code using the interface struct crates is calling through the APIs exposed by #[hdk_extern] methods in these modules in the same way that hREA modules communicate with each other.
You should create your own customised zome definitions if:
- You wish to combine multiple separate hREA zomes in the same DNA and isolate the storage into different
entry_deftypes. - You wish to define private variants of ValueFlows record types or customise sharding and validation rules.
- You wish to add handling of bespoke organisational logic and related records that needs to be validated tightly against REA data or coordinated as a coherent unit of information.
example/contains contrived implementations for particular use-cases and domain-specific applications which may be helpful in getting started with some of the more common advanced ValueFlows extensions.
rea_*/lib/ contains the bulk of the logic driving each ValueFlows record type. This layer is considered a "black box" to any outside systems, and forms the outermost guarantees of consistency provided by hREA.
Building against these APIs is the method by which one may create custom zome crates (as above). Methods for managing records most often follow the pattern pub fn handle_{create|get|update|delete}_rec(...), where rec is the type of record.
You should consider the public API of these crates as the boundary of the REA system. Customisation of internal storage and link handling logic could lead to inconsistent database states and erroneous interpretations of ValueFlows records.
rea_*/storage crates define the data structures and logic used with the low-level HDK (Holochain Development Kit) functions. This includes DNA properties, struct definitions and data validation logic.
Each module exports an EntryData for the record information of relevance, and an EntryStorage which wraps this struct with standardised identifiers used to manage links between record updates.
In cases where records have standard CRUD features, EntryData is convertible From<CreateRequest> in its associated interface struct crate; and implements Updateable<UpdateRequest> from the hdk_records library. These traits are used by library crates to handle the underlying storage logic.
It is unlikely that there should be a need to create customised versions of these files. For maintenance reasons it is much better to compose additional fields and functionality onto the REA record types as new entry_defs in zome crates if adding additional fields is a requirement for your use-case.
rea_*/storage_consts/ are simple includes which provide the string constants used to identify and link records using the ValueFlows vocabulary. They are provided as separate crates for consistency, since multiple zomes often manage links to corresponding entries at either side of a network boundary.
The Rust crates in lib/ provide some abstract functionality and type definitions used across the hREA suite. Of particular note:
Manages CRUD and indexing operations for entries, including DNA-local and remote-DNA indexing capabilities. Leverages DNA Auth Resolver to grant capabilities for cross-DNA API calls.
Exports an addressable_identifier!() macro which wraps a primitive type implementing Into<AnyDhtHash> in a struct scoping it to a DnaHash; as well as dna_scoped_string!() which does the same for String.
These types are used as identifiers throughout all hREA record fields, allowing records to complexly reference each other in many:many relationships in different networks.
See the vf_attributes_hdk crate to see these macros in action.
A helper type for record fields which acts similarly to Option<T> except that an explicit null is differentiated from omission of a field.
This provides an external API which is consistent with common developer expectations in the JavaScript community, where null is used to remove fields in update operations whilst omission indicates leaving a value unchanged.
Previously, this work was referred to as "Holo-REA" or sometimes "HoloREA". All these labels refer to the same project.
Licensed under an Apache 2.0 license.