Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Flow documentation #164

Open
wants to merge 7 commits into
base: develop
Choose a base branch
from
Open

Flow documentation #164

wants to merge 7 commits into from

Conversation

shokri-navid
Copy link

No description provided.

michielbdejong
michielbdejong requested changes Jan 10, 2025
View reviewed changes
invitation-flow.drawio Outdated
<mxPoint x="570" y="210" as="targetPoint" />
</mxGeometry>
</mxCell>
<mxCell id="NDPqdjoCEg37fMv0_q80-18" value="&lt;p style=&quot;margin:0px;margin-top:4px;text-align:center;text-decoration:underline;&quot;&gt;&lt;b&gt;Invitation:Type&lt;/b&gt;&lt;/p&gt;&lt;hr size=&quot;1&quot; style=&quot;border-style:solid;&quot;&gt;&lt;p style=&quot;margin:0px;margin-left:8px;&quot;&gt;Tokrn :&amp;nbsp;&lt;b&gt;string&lt;/b&gt;&amp;nbsp;&lt;br&gt;email :&amp;nbsp;&lt;b style=&quot;background-color: initial;&quot;&gt;string&lt;/b&gt;&lt;span style=&quot;background-color: initial;&quot;&gt;&amp;nbsp;&lt;/span&gt;&lt;/p&gt;&lt;p style=&quot;margin:0px;margin-left:8px;&quot;&gt;&lt;span style=&quot;background-color: initial;&quot;&gt;accepted :&amp;nbsp;&lt;/span&gt;&lt;b style=&quot;background-color: initial;&quot;&gt;bool&lt;/b&gt;&lt;span style=&quot;background-color: initial;&quot;&gt;&amp;nbsp;&lt;/span&gt;&lt;br&gt;&lt;/p&gt;&lt;p style=&quot;margin: 0px 0px 0px 8px;&quot;&gt;createdAt :&amp;nbsp;&lt;b style=&quot;background-color: initial;&quot;&gt;datetime&lt;/b&gt;&lt;span style=&quot;background-color: initial;&quot;&gt;&amp;nbsp;&lt;/span&gt;&lt;/p&gt;&lt;p style=&quot;margin: 0px 0px 0px 8px;&quot;&gt;expiresAt :&amp;nbsp;&lt;b style=&quot;background-color: initial;&quot;&gt;?datetime&lt;/b&gt;&lt;span style=&quot;background-color: initial;&quot;&gt;&amp;nbsp;&lt;/span&gt;&lt;/p&gt;&lt;p style=&quot;margin: 0px 0px 0px 8px;&quot;&gt;acceptedAt :&amp;nbsp;&lt;b style=&quot;background-color: initial;&quot;&gt;?datetime&lt;/b&gt;&lt;span style=&quot;background-color: initial;&quot;&gt;&amp;nbsp;&lt;/span&gt;&lt;/p&gt;&lt;div&gt;&lt;br&gt;&lt;/div&gt;" style="verticalAlign=top;align=left;overflow=fill;html=1;whiteSpace=wrap;fillColor=#d5e8d4;strokeColor=#82b366;" vertex="1" parent="1">
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Tokrn" -> "Token"

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The email should be optional in the database table, because we want our schema to support situations where invites are generated and then sent for instance via Matrix instead of via email

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Throught the I-D we use the term 'Invite' so maybe call the db table 'Invites'?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

'Reciever' -> 'Receiver'

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

'submiting' -> 'submitting'

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For AcceptInvitationRequestDto, please use the field names as they actually appear in the API call (section 3.5.2. Invite Acceptance Request Details), so:

  • recipientProvider
  • token
  • userID
  • email
  • name

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Samce for Invite Acceptance Response, and maybe rename them to:

  • InviteAcceptanceRequestDto
  • InviteAcceptanceResponseDto

glpatcern
glpatcern reviewed Jan 10, 2025
View reviewed changes
Copy link
Member

@glpatcern glpatcern left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. Could you also move the files in a Diagrams folder? Afterwards we shall also move the other example committed by Michiel in there.

README.md
@@ -14,6 +14,11 @@ Previous versions:

[SemVer](https://semver.org) versioning applies to OCM, and all versions are supported unless stated otherwise by an implementation.

## Invitation flow at a glance
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest to not include this in the README, there are quite a few flows and the Invite is not even the core one, therefore it does not make much sense to show it here.

@MahdiBaghbani
Copy link
Collaborator

I have a suggestion, would you be able to use mermaid instead of draw io?

I have created something very similar to yours, it is human-readable text and auto renders as markdown:

sequenceDiagram
    participant Inviter
    participant InviteSenderServer as Invite Sender Server
    participant InviteReceiverServer as Invite Receiver Server
    participant Invitee

    Inviter->>InviteSenderServer: Calls Invite API
    InviteSenderServer->>InviteSenderServer: Creates an invite record in the database
    Note right of InviteSenderServer: Dispatch notification (Email) to invitee\n- Token\n- invite sender server FQDN

    InviteSenderServer->>Invitee: Send Email with Token and Server FQDN
    Invitee->>InviteReceiverServer: Submit invite acceptance form\n(Token, invite sender server FQDN)
    
    InviteReceiverServer->>InviteSenderServer: Discover the OCM API of the inviter server
    InviteReceiverServer->>InviteReceiverServer: Adds FQDN of invite sender server as trusted server

    InviteReceiverServer->>InviteSenderServer: Accept invite API Call\n(InviteAcceptanceRequestDto)
    Note left of InviteReceiverServer: InviteAcceptanceRequestDto\n+ recipientProvider: string\n+ token: string\n+ userID: string\n+ email: string\n+ name: string

    InviteSenderServer->>InviteSenderServer: Add invite receiver FQDN as trusted server
    InviteSenderServer->>InviteSenderServer: Mark the invitation record as accepted
    InviteSenderServer->>InviteSenderServer: Add invite receiver in the contacts table
    InviteSenderServer->>InviteReceiverServer: Return InviteAcceptanceResponseDto
    
    Note right of InviteReceiverServer: InviteAcceptanceResponseDto\n+ UserId: string\n+ Email: string\n+ Name: string
    InviteReceiverServer->>Invitee: Adds Invite sender as contact
Loading

@glpatcern
Copy link
Member

I actually support @MahdiBaghbani comment, the mermaid-based diagrams are also more git friendly!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@glpatcern glpatcern glpatcern left review comments

@michielbdejong michielbdejong michielbdejong requested changes

Requested changes must be addressed to merge this pull request.

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@shokri-navid @MahdiBaghbani @glpatcern @michielbdejong