feat: sequence diagrams

[smol-ninja]

Closes #72.

Changelog

1. Uses sequence diagrams for actor based flow charts
2. Lockup Hooks preview
3. Airstream Campaign preview
4. Token Flows
5. Adds a new diagram in Flow

Previews

Lockup

Flow

[andreivladbrg]

Nice work, I really like these sequence diagrams.

---

What if we move the Flow Actors with Actions diagrams to Access Control (similar to lockup)?

Also, what if we divide the sequence into one diagram per function? (current version quite long)
adjustRatePerSecond is missing. Additionally, in some places, you pass the stream ID in the function as param, while in others, you don't. I suggest removing the instances where it is passed and simplifying it to foo().

---

Regarding your comment: #186 (comment)
I still think we can add that diagram, but in the concepts/flow/statuses file, at the end, after the Q&A. the section can be called function calls based on the status
But we can remove the state updates. Wdyt?

[andreivladbrg]

just saw now, instead of set ud = 0 i think it would be more precise to use the "set" word only for storage variables. so we should use st and sd.

[smol-ninja]

Thank you for the review @andreivladbrg.

What if we move the Flow Actors with Actions diagrams to Access Control (similar to lockup)?

Agree I also realized that I could use sequence diagrams in Lockup access control as well. So, made that changes.

What if we divide the sequence into one diagram per function?

Yes agree. I will make it similar to how it is in Lockup.

adjustRatePerSecond is missing

Good catch, will add it.

you pass the stream ID in the function as param, while in others, you don't

Will make it consistent by removing it.

I still think we can add that diagram, but in the concepts/flow/statuses file, at the end, after the Q&A. the section can be called function calls based on the status

I will add it and then we can decide if it fits or not.

instead of set ud = 0 i think it would be more precise to use the "set" word only for storage variables. so we should use st and sd.

IMO diagrams are to explain product. My rationale was that there is no need to mimic the internal of the contracts. For example, people might be more comfortable with terms like uncovered debt and covered debt than snapshot debt or snapshot time. That is why I used those terminologies in the diagrams, also given that it will be moved to access control section. Please lmk if that makes sense.

[andreivladbrg]

IMO diagrams are to explain product. My rationale was that there is no need to mimic the internal of the contracts. For example, people might be more comfortable with terms like uncovered debt and covered debt than snapshot debt or snapshot time. That is why I used those terminologies in the diagrams, also given that it will be moved to access control section. Please lmk if that makes sense.

IMO it depends on where the diagrams are placed. If they are under the "Concepts" section (which should target non-developers as well), then yes, I agree they don’t need to mimic the internal contracts. However, since they are not, I believe we should focus on the developers and use the storage vars

[smol-ninja]

@andreivladbrg I have included all your suggestions and made some changes as well. Let me know how it looks now.

[andreivladbrg]

i personally prefer the big diagram for the function status interactions instead of multiple smaller ones, but it’s fine this way as well.

so lgtm 👍

good job again! sequence diagrams are an improvement to the existing diagrams

[smol-ninja]

Thanks for approving the PR. The reason I split that diagram into smaller chunks is because in your review, you suggested to split the Flow Actors with Actions diagram into smaller ones because it felt too long. The function-status interaction was much longer in length than that one and one would have to scroll a lot to get the bottom of it.

I will merge the PR for now and we can refactor it later if we want so.