TEA Party Code Walkthrough

In this section, we'll walk through the TEA Party application's sample code.

The steps are:

• Clone the code to local.

• Install the build tools.

• Understand the folder structure.

• Understand the compile workflow.

• Run it.

Code location and structure

Start by cloneing the following GitHub repo to your local machine: https://github.com/tearust/tapp-sample-teaparty

There are 4 folders (click the following links for more details):

• party-fe: This is the front_end.

• party-actor: This is the back_end_actor.

• party-share: This is the common data structure or library that shared by both the back_end_actor and the state_machine_actor.

• party-state-actor: This is the state_machine_actor.

Workflow

Load the UI

Any user can launch a TApp by clicking on one of the hosting_cmls urls (there's no domain used when launching TApps). Picking any of the urls will work exactly the same so you can choose the one with least network latency. The URL is nothing but an IPFS CID.

Note: This is a brief diagram. The real communication is more complicated than this.

Query the state

Accounting information is stored in the state (e.g. when querying the balance of a user's TApp account.)

Querying the state can return the result without having to wait in conveyor queue. But the communication is still async, so additional queries for more results are still needed which is not shown in the diagram. You can see the details on additional queries at party-fe > Workflow.

Note: This is a brief diagram. The real communication is more complicated than this.

Send a command that changes the state

Commands are more complicated in that certain precautions must be taken before they're allowed to change the state. Like any other distributed state machine, we have to make sure the state in all the state_machine_replicas are consistent. We use the conveyor algorithm to sort the commands by their timestamp and are executed in identical order across all replicas.

The following diagram demonstrates the workflow of how a simple transfer txn command is handled. Note that this diagram is a simplifed verison. The full version can be found here: party-fe > Workflow.

Running SQL queries

Running SQL queries is almost the same as running a query against the state. The only difference is that we replace the state with the GlueSQL instance. Note: SQL queries are not allowed to change the state. Only Select statements are allowed in SQL queries.

Send SQL scripts to change SQL database

Rather than select, many SQL statements will change the database. They are all considered commands. The workflow is almost the same as the state command, with the state being replaced by the GlueSQL instance.

Load / save NoSQL data with OrbitDB

Because the state and GlueSQL are memory based distributed databases, they're very expensive when used to store large amounts of data. TApps needing to store large amounts of data should use either OrbitDB (structured data) or IPFS (blob data/ files).

OrbitDB and IPFS live inside the hosting_cml, so the state_machine_replicas are not involved in this workflow.

Combination of SQL and NoSQL

The diagram above shows a common use case that loads all messages. But in many cases, the ids (index) of the OrbitDB is stored in GlueSQL, so it's very common to first have to query GlueSQL to get the IDs. After successfully querying GlueSqL for the IDs, then we can query OrbitDB using the IDs to retrieve the actual data.

The above diagram shows the combination of SQL and NoSQL.

More details on each of the three parts

Click on any of the following links for more details:

• Code walkthrough for party-fe.
• Code walkthrough for party-actor.
• Code walkthrough for party-state-actor.

Run it

TODO: