Visualise data schema as UML class diagram or similar

[aspiers]

Description

Our data model schema isn't trivial, so it would be useful to have a UML class diagram or similar to refer to when hacking on the code.

Comments, Questions and Considerations

Our schema is mainly defined by the files in src/ruby/meetings/app/resources/api/v1.

Acceptance Criteria

Given the schema defined in the Rails app,

When the schema is updated,

Then we can auto-generate a new UML class diagram or similar which visualises the schema in an easy-to-understand way.

Possible approaches

• We might be able to use https://github.com/SOM-Research/jsonDiscoverer, if we can persuade our API to auto-generate a JSON schema document of the right format.
• Ask for advice in the JSON API forums
• Draw a UML class diagram manually, via http://draw.io or similar.

[aspiers]

I tried out https://github.com/SOM-Research/jsonDiscoverer and unfortunately the JSON API response format is too complex and verbose for it to be able to understand usefully; you end up with diagrams like this:

As a next step, I've asked for advice on the JSON API forum.

[charlottebrf]

Could be a good diagram to add to our presentation deck, to show working process @aspiers ?

[aspiers]

Yes it could!

[aspiers]

Got responses from the forums, and they recommended Rails ERD – Entity-Relationship Diagrams for Rails and RailRoady :: Ruby Model & Controller Class Diagram Generator. Funnily enough, the latter is already in our Gemfile! So it turns out that all I needed to do was

bundle exec rake diagram:all

to get these:

However they are quite confusing to look at so maybe we can still do better.