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.

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

Entities visualization with Mermaid.js #38

Closed
dalssoft opened this issue Apr 16, 2022 · 25 comments · Fixed by #41
Closed

Entities visualization with Mermaid.js #38

dalssoft opened this issue Apr 16, 2022 · 25 comments · Fixed by #41
Assignees
Labels
enhancement New feature or request

Comments

@dalssoft
Copy link
Member

It would be interesting to understand a entity and its relationships not only in code but also having a more "visual" approach and have this information as part of Shelf experience.

For that we could extract metadata from Herbs entity and export to MermaidJS:

classDiagram
    class User {
        Number ID
        String firstName
        String lastName
        Number age
        User_Account[] accounts
    }
    class User_Account{
        Number ID
        Date expirationDate
        isExpired()
    }
    class Project{
        Number ID
        String name
        User_Account user
        Task[] tasks
    }
    class Task{
        Number ID
        String name
        Date dueDate
    }
    User "1" --> "*" User_Account
    Project "1" --> "1" User_Account
    Project "1" --> "*" Task
classDiagram
    class User {
        Number ID
        String firstName
        String lastName
        Number age
        User_Account[] accounts
    }
    class User_Account{
        Number ID
        Date expirationDate
        isExpired()
    }
    class Project{
        Number ID
        String name
        User_Account user
        Task[] tasks
    }
    class Task{
        Number ID
        String name
        Date dueDate
    }
    User "1" --> "*" User_Account
    Project "1" --> "1" User_Account
    Project "1" --> "*" Task
Loading
@dalssoft dalssoft added the enhancement New feature or request label Apr 16, 2022
@italojs
Copy link
Member

italojs commented Apr 22, 2022

Just to give some example about what we can explore, I would like to share this link that Dalsoft shared with me

we have many diagrams opportunity to explore with this feature

@jhomarolo jhomarolo linked a pull request Apr 28, 2022 that will close this issue
4 tasks
@jhomarolo jhomarolo reopened this Apr 28, 2022
@italojs
Copy link
Member

italojs commented May 4, 2022

why did you reopen it?
If you reopen it becase we need to improve the current implementation, you could to open another issue, becase the #41 PR already fix this current issue

@dalssoft
Copy link
Member Author

dalssoft commented May 5, 2022

becase the #41 PR already fix this current issue

well, not really. the initial idea was to have this diagrams inside Shelf UI with diagrams auto generated by Herbs metadata. The PR above only allows to Mermaid diagrams to be part of the README file, created manually (which is completely fine).

@jhomarolo
Copy link
Contributor

@dalssoft is right. I reopened it because is not totally closed yet.

@maikvortx
Copy link
Contributor

Hi guys! I will work on this issue!

@maikvortx
Copy link
Contributor

Hey guys. Any suggestion? I'm working on this feature and just missing details to complete it.

image

@dalssoft
Copy link
Member Author

@maikmb ideally we could have a more in-depth discussion on how to document the entities, but thinking about it, I believe your suggestion would work well for a first version

@maikvortx
Copy link
Contributor

Thanks @dalssoft! We will implement the first version and improve it later.

@jhomarolo
Copy link
Contributor

Maik, I believe the diagram connection (1 ... N ) in the image is missing, right?

Like this:

image

@maikvortx
Copy link
Contributor

Hi @jhomarolo!
I was implementing this feature.

image

@dalssoft
Copy link
Member Author

Looks great. We should test it in a big project and see how it behaves.

@jhomarolo
Copy link
Contributor

@maikvortx I think is missing the pointer showing the relation 1 ... N

Inside the diagram should be TodoList "1" --> "*" Item

But, anyhow, looks amazing! This is a huge feature

@dalssoft
Copy link
Member Author

dalssoft commented Jul 1, 2022

Related: #24

@maikvortx
Copy link
Contributor

Hi everyone!
@jhomarolo The relationship is created automatically by herbsshelf.

image

@maikvortx
Copy link
Contributor

Hey guys, I have implemented the new version of the herbs shelf in internal project and I have an example of a complex entities class diagram:

image

image

@jhomarolo
Copy link
Contributor

jhomarolo commented Jul 5, 2022

@maikvortx, It's becoming excellent! I have only two considerations:

1 - About the ordering of the diagram. Is there any way to sort the diagram automatically? It seemed to me that the diagram gets a little confusing in a big system

Like this:
image

2 - I believe that mine needs to include use cases and entities. That is, create a folder called use cases and leave them there. From the way you sent the print, it implies that the entities link is also a use case

Does it make sense to you? I think we're almost there on this PR!

@dalssoft
Copy link
Member Author

dalssoft commented Jul 5, 2022

@maikmb amazing work! this is going to be a killer feature!

I agree with @jhomarolo on (1): i think we should find a way to implement a diagram reorder. ideally having a button where the user can choose which reorder they want. regarding (2) (to include use cases and entities), i think it is a improvement we can discuss, but for now I would leave without UCs.

@maikmb
Copy link
Contributor

maikmb commented Jul 5, 2022

Hey guys! I agree with you.

(1) What do think about implementing diagram reorder in another PR? I will study Mermaid to implement this feature. In a big project, the class diagram gets a little confusing.
(2) About usecases, I will implement this in another PR for this issue #37

@maikmb maikmb mentioned this issue Jul 5, 2022
@dalssoft
Copy link
Member Author

dalssoft commented Jul 5, 2022

I will study Mermaid to implement this feature. In a big project, the class diagram gets a little confusing.

"de bate pronto", is there a any indication of Mermaid having this feature? It doesn't seem like it mermaid-js/mermaid#806

@dalssoft
Copy link
Member Author

dalssoft commented Jul 5, 2022

I have an example of a complex entities class diagram #38 (comment)

We could use groups metadata to entities like we have in use cases. This way we could create sub-views to view entities so we don´t have to show the whole thing... yes, I know, it is another issue, but just to document it

@dalssoft
Copy link
Member Author

dalssoft commented Jul 5, 2022

@maikmb It seems we have many ideas of improvements here. But what is missing to accept this PR? #47

@maikmb
Copy link
Contributor

maikmb commented Jul 5, 2022

I have an example of a complex entities class diagram #38 (comment)

We could use groups metadata to entities as we have in use cases. This way we could create sub-views to view entities so we don´t have to show the whole thing... yes, I know, it is another issue, but just to document it

It's a good idea @dalssoft. I can implement it in another PR.

@maikmb
Copy link
Contributor

maikmb commented Jul 5, 2022

@maikmb It seems we have many ideas for improvements here. But what is missing to accept this PR? #47

@dalssoft I think this PR can be approved. The improvements discussed here will be implemented separated.

@maikmb
Copy link
Contributor

maikmb commented Jul 6, 2022

Hey guys! What you think about this layout:

Entities Group Diagram

screenshot-localhost_4000-2022 07 05-23_02_12

  • Group entities
  • Group Usecases
  • Include usecase workflow at the bottom of the details

@dalssoft
Copy link
Member Author

dalssoft commented Jul 6, 2022

Group entities

Great!!! But in order to have groups shown, it must be informed as metadata:

module.exports =
  herbarium.entities
    .add(List, 'List')
    .metadata({ group: 'Core Entities' })
    .entity

maikmb pushed a commit to maikmb/herbsshelf that referenced this issue Jul 12, 2022
implement entities doc with mermaid class diagran to herbsshelf

BREAKING CHANGE: include a new paramter to renderShefHtml method

re herbsjs#38
maikmb pushed a commit to maikmb/herbsshelf that referenced this issue Jul 13, 2022
github-actions bot pushed a commit that referenced this issue Jul 13, 2022
# [4.0.0](v3.2.0...v4.0.0) (2022-07-13)

### Features

* **mermaid-entities:** centralize class diagram and change entities doc description ([cb24e66](cb24e66)), closes [#38](#38)
* **mermaid-entities:** implement entities doc with mermaid ([0eb7d15](0eb7d15)), closes [#38](#38)

### BREAKING CHANGES

* **mermaid-entities:** include a new paramter to renderShefHtml method
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
Development

Successfully merging a pull request may close this issue.

5 participants