owned this note
owned this note
Published
Linked with GitHub
# How to build an entry relationship diagram
We recommend using draw.io or similar if you want to create your diagrams manually, or [mermaid](https://mermaid-js.github.io/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:
```rust
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](https://hackmd.io/RZn-QeU8TKuhBU-58IvRzg)).
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
```rust
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
```mermaid
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
