How to build an entry relationship diagram

We recommend using draw.io or similar if you want to create your diagrams manually, or mermaid to declare the diagrams in markdown files.

Documentation sections

It is recommended to document every zome in your happ separately, to improve readability and reusability.

Entry structure

For every type of entry in your zome, specify the rust struct with its fields and types and the links from and to your entry:

Entry "<entry_type_name>" {
    struct <StructName> {
        <struct_fields>: <struct_field_types>
    }
    Links: {
        <base_entry_type_name>-><target_entry_type_name>
    }
}

Identifiers (entry_type_name, base_entry_type_name…) should match the names in your zome. These are important for holochain to know which entries is your code linking.

Entry relationship diagram

1. For each entry type in the zome, create a subdiagram space in it with the entry's name as label.
2. Create example entries for each entry type. Try to represent all the entries and relationships involved in your hApp.
3. Add the links between your example entries that would exist in the application. Use solid lines for explicit links, and dashed lines for implicit links (reference: Implicit vs Explicit links).
4. Use different agents (at least two, depending on the hApp), by the names of Alice, Bob, Carol, Dave, Eve…

Try to create just enough example entries to represent all the relationships. If there are too little of them, you may be missing some types of relationships. If there are too many, the diagram can get difficult to grasp at first glance.

Note: if your diagram is starting to get out of hand, it could be a sign that your zome has too much complexity, as zomes should be small and easy to reason about. It may be time to consider splitting its functionality.

Validation rules

1. For each entry or link, if they have validation rules other than Ok(()), specify the conditions in which each entry is valid. Try to be as precise as possible.
2. Specify the valid CRUD operations (Create, Delete, Update).

Example: Clutter (twitter clone)

Entry structure

Entry "anchor" {
    struct Anchor {
        anchor_type: String,
        anchor_text: String
    }
    Links: {
        hashtag->tweet
    }
}

Entry "tweet" {
    struct Tweet {
        author_address: Address,
        timestamp: u64,
        content: String
    }
    Links: {
        agent_id->tweet
    }
}

Entry relationship diagram

graph TD
  subgraph Clutter zome
    subgraph tweets
      Tweet1
      Tweet2
    end
    subgraph handles
      Tweet1 -.creator_address.-> alice_handle
      Tweet2 -.creator_address.-> bob_handle
      bob_handle --> Tweet2
      alice_handle --> Tweet1
    end
    subgraph anchors
      hashtag1 --> Tweet1
      all_tweets
            all_tweets --> Tweet1
      all_tweets --> Tweet2
    end
  end

Validation

Entries

• Tweets:
  • Create is valid if:
    • The tweet is signed by its author
    • The tweet's content is less than 280 characters
  • Update and delete are not valid

Links

• handle->tweet:
  • AddLink: valid if the handle author is the tweet's creator address
  • RemoveLink not valid