# REA Playspace User Guide

## Installing the software

1. First you must install the holochain Launcher, if it is not already installed. Most often, you will only need to do this once. You can get it [here](https://github.com/holochain/launcher/releases). You can generally take the most recent version, top in the list, unless someone tells you that you need a specific version. Scroll down for earlier versions if you need one. Then you will need to select the right version for your computer's operating system, and follow the directions on the page.

2. Then you install the Playspace app into the Launcher.
* Open the Launcher from your file system. You will see a list of your already installed holochain apps.
* If the playspace app you want is listed, and you intend to install a newer version, uninstall it by clicking on the setting (gear) icon, and selecting UNINSTALL.
* Select INSTALL NEW APP in the lower right.
* Select INSTALL APP on the REA Playspace rectangle. (You can verify the version if you need to, it will be labeled with a number.)
* A smaller popup will appear.
* Select the holochain version you want, you can pick the last one unless you were told otherwise.
* Click the down arrow on the left by Advanced, and fill in the Network Seed. Enter a new one if you are creating a new playspace, or enter the correct code for an existing playspace you want to join.
* You also might want to change the App Id at the top (this is what will appear on the list in your Launcher).
* You can leave "Generate new Public Key", which will generate a new identity for you in this app. Or you can select an existing public key.
* Click INSTALL APP, and wait for it to install.

## Getting started

On the Launcher, click OPEN to start the playspace.


When the canvas comes up for the first time, you will be asked to give a nickname that you want to be your holochain profile name for this app. You can also select an avatar picture if you like, by clicking the add circle. Then select CREATE PROFILE.

The playspace app will appear in your browser. If you are the first to create this network, it will have no data. If you are joining an existing network that has data, you will see that data.

## Configuration

Configuration is done on the left side panel. Selecting + in any section will bring up a small window for you to enter information for a new item. Double clicking on an item in any section will allow updating. To delete, hold ctrl-alt (option-alt), left click.

### Resource Specifications

Resource specifications can be kinds of material items, electronic resources, types of work or skills, whatever kinds of things will be going into or out of processes, or transferred between agents. These can be general or very specific, depending on the need, more info [here](https://www.valueflo.ws/concepts/resources/#definition).

* Name: a unique textual name (req)
* Image: a URL to a picture of the resource (opt)
* Resource Classified As: textual tags or categories that could be used to search (opt)
* Default Unit of Resource: choose a unit from the list that most often will be used for resources that could be inventoried. (opt)
* Default Unit of Effort: choose a unit from the list that most often will be used for resources that will be used or are types of work/skills. (opt)
* Note: text description (opt)

### Process Specifications

Process specifications are kinds of processes that will be used in your network. Processes generally transform resources into new resources, fix or modify resources, or transport resources to a different location.
They can be more generally or more specifically defined, depending on your needs, more info [here](https://www.valueflo.ws/concepts/processes/).

* Name: unique name (req)
* Note: text description (opt)


### Agents

Agents are people or organizations (formal or informal) or ecological agents (non-human individuals or living ecosystems), more info [here](https://www.valueflo.ws/concepts/agents/). You will need agents that are inside your network, and also agents you collaborate or exchange with outside your network. You will need to create an agent for yourself if you will be part of the network.

Click on the "hamburger" (3 lines) on the upper left of the page, select Agents.


Click the + for a new agent, double click an agent on the list to make changes. When complete, click on the menu again and select Flows to get back to the main page.

* Name: unique name (req)
* Image: URL for an avatar or logo (opt)
* Note: text description (opt)
* Primary Location: For now, if you want to map the agents, enter a latitude and longitude with a comma in between. Eventually, locations will be a full feature.


## Resource flow diagrams

### Two patterns

There are 2 patterns involved:
* Input-Process-Output is used for producing or modifying or transporting resources of any kind. This pattern "creates value".
* Transfer is used to change rights or custody of resources from one agent to another. This pattern also will include moving and copying resources. This pattern does not "create value".

Both patterns fit together into resource flows, both planned and actual.

### Using the visual canvas

The visual canvas is the large central space to draw the plan for the resource flows, and/or log what actually happened.

To create a resource flow, drag and drop Resource Specifications and Process Specifications from the left side bar. These create the "nodes". If you need something you don't have, just create it as above.

Then connect the nodes with "flows". Draw from the right side of one node to the left side of another node, which will bring up a popup so you can define either a Commitment (a planned flow) or an Event (an actual flow). Possible connections:
* From a Resource Specification to a Process: creates an input resource flow to the process.
* From a Process to a Resource Specification: creates an output resource flow from the process.
* From a Resource Specification to another Resource Specification (of the same kind): creates a flow of that resource from one agent to another one, or (coming soon) a flow from one location to another.

Move nodes around by dragging them individually. (Coming soon: They can also be moved as a group by selecting (shift and drag to select multiple nodes), and dragging the group.)

Move around in the canvas by dragging on a blank space.

Zoom in or out by moving your mouse wheel or other scroll tool. Or use the + and - on the lower left. To get the whole diagram to fit on the page, select the "fit view" tool on the lower left.

### Plans

Coming soon, you will be able to create separate visualizations for each plan (one or a set of related flows). Right now, it is one big plan for the network.

### Process nodes

When a Process Specification is dropped, a form will appear so you can create a Process from the Process Specification. A Process is something you want to actually do.

* Name: A unique name for the planned/actual process (req)
* Accountable: The agent by and for which the process is done, usually an organization (opt)
* Note: Description of the process, useful as guidance to the people doing the work (opt)
* Finish: Pressing this says that there will be nothing else done on this process (opt)

### Resource nodes

When a Resource Specification is dropped on the canvas, it does not yet create a resource, because that happens later when applicable, for now it remains a kind of resource, like a placeholder. You may have more than one of the same Resource Specification on your canvas.

### Flow information

Drawing a flow line will bring up a form where you can create a commitment (a planned resource flow), or log an unplanned economic event (one which was not planned so does not have a commitment).

### Commitments

In this case (an input flow), we will select Create Commitment.

* Action: the verb which has specific effects on resources (see [this documentation](https://www.valueflo.ws/concepts/actions/) for detailed information) (req)
* Provider: the provider agent (for inputs, the person doing the work or the agent primarily accountable for the resource; for outputs, usually the accountable on the process) (req)
* Receiver: the receiver agent (for inputs, usually the accountable on the process, for outputs,the accountable agent or another agent who receives the resource) (req)
* Resource quantity and Resource unit: The quantity affected by the event, for resources that can be inventoried (the appropriate quantity option will display, based on the action)
* Effort quantity and Effort unit: The quantity worked or used (the appropriate quantity option will display, based on the action)
* Due: date due (opt)
* At Location: planned location (opt)
* Note: description of what should be done for this commitment (opt)
* Finish: this commitment fill have no further fulfillment from events, usually done after the last event is entered (opt)

When filled in, press Create (you may have to scroll down). The Commitment is displayed in the flow window.

Press Done to go back to the visual canvas.

If you drag a line between 2 Resource Specifications (they must be the same type), you are creating a transfer commitment, more info [here](https://www.valueflo.ws/concepts/transfers/).

Now the plan for how Alice will get the flour is in place. And we have added some other process commitments to complete the process inputs and outpts.

### Economic events

Usually after the planning has been done, the plan is executed and actual events are entered. Alternatively, if no planning is done, the events can be entered without a commitment.

Here is the economic event that consumes the flour. All elements are listed below in case the event is not fulfilling a commitment. If there is a commitment, some of these cannot be changed.

* Action: the verb which has specific effects on resources (see [this documentation](https://www.valueflo.ws/concepts/actions/) for detailed information) (req)
* Provider: the provider agent (for inputs, the person doing the work or the agent primarily accountable for the resource; for outputs, usually the accountable on the process) (req)
* Receiver: the receiver agent (for inputs, usually the accountable on the process, for outputs,the accountable agent or another agent who receives the resource) (req)
* Resource quantity and Resource unit: The quantity affected by the event, for resources that can be inventoried (the appropriate quantity option will display, based on the action)
* Effort quantity and Effort unit: The quantity worked or used (the appropriate quantity option will display, based on the action)
* Datetime: date due (opt)
* At Location: the location the event occurred
* To Location: new location for the resource (opt)
* Note: description of what was done for this event, can be used for coordination (opt)


Sometimes more than one event is created for one commitment. This is often the case for work, but can be for any kind of flow. For example Alice logged 2 separate work times, maybe she did something else in the middle.

Here ore those flows on the canvas after the economic events that fulfill those commitments are entered.

### Updating

To update either a node or a flow line, double click on it, and the form will appear. Make changes and press Update.

### Deleting

To delete an individual node or flow line, click on it once to select it. Then hold Alt and press Backspace.

To delete multiple nodes and/or flow lines, hold Shift and drag a boundary around what you want to delete. Then hold Alt and press Backspace.

Temporary note: There is nothing to stop you from deleting anything, or warn you, so be careful with data you want to keep until we get that logic in.