Entities visualization with Mermaid.js

[dalssoft]

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

[italojs]

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

[italojs]

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]

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]

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

[maikvortx]

Hi guys! I will work on this issue!

[maikvortx]

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

[dalssoft]

@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]

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

[jhomarolo]

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

Like this:

[maikvortx]

Hi @jhomarolo!
I was implementing this feature.

[dalssoft]

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

[jhomarolo]

@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]

Related: #24

[maikvortx]

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

[maikvortx]

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:

[jhomarolo]

@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:

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]

@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]

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

[dalssoft]

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]

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]

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

[maikmb]

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]

@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]

Hey guys! What you think about this layout:

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

[dalssoft]

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