зеркало из https://github.com/mozilla/fxa.git
3.4 KiB
3.4 KiB
Use Structurizr for Software Diagrams
- Status: accepted
- Deciders: Ben Bangert, Wil Clouser, Dan Schomburg
- Date: 2023-01-26
Context and Problem Statement
Existing architecture documentation has not been self-explanatory nor follows the more thorough architecture diagramming techniques set down in the c4 model. MermaidJS has been used for some diagrams but runs into issues with larger more complex diagrams as it can't be manually re-arranged, while LucidChart doesn't lend itself to being serialized for our version control.
Decision Drivers
- Ability to edit and define relationships and text in a text file.
- DRY, can re-use models between diagrams for consistency in naming and terminology.
- Serializable output that we can save diagrams in our ecosystem repository.
- Can automate diagram generation for our ecosystem docs.
- Cost effective and/or free solution to encourage wider diagram editing audience.
Considered Options
- A. Structurizr
- B. MermaidJS
- C. LucidChart
Decision Outcome
Chosen option: A: Structurizr was specifically built for software architecture diagrams, has multiple runtime options available, github actions, and allows the unique ability to define the models and relationships once and re-use them in additional diagrams to add further explanations.
Pros and Cons of the Options
A. Structurizr
- Good, because models and relationships can be defined once and re-used.
- Good, because application can be run as docker container for free.
- Good, because there's github actions allowing for integration during doc building.
- Good, because diagrams can be automatically laid out, and manually fine-tuned as needed.
- Good, because all manual changes made in the app can be serialized to JSON and used again.
- Good, because free self-hosted or very cheap cloud hosted solutions are available.
- Bad, because it's a new DSL for diagramming that hasn't been used at Mozilla.
- Bad, because an application will need to be run locally or the cloud to render the diagrams.
B. MermaidJS
- Good, because diagrams can be rendered inline on our ecosystem docs page via JS.
- Good, because diagrams can be defined purely in simple markup.
- Good, because all markup for the diagrams can be included inline with the documentation.
- Good, because the diagrams can be automatically laid out.
- Good, because it's free to use and distribute.
- Good, because we already use it and are familiar with its markup language.
- Bad, because diagrams can't be manually rearranged if the automatic layout is unhelpful.
- Bad, because models and relationships in the diagrams have to be defined for every diagram rather than re-used between them.
C. LucidChart
- Good, because diagrams can have their elements manually positioned when complex.
- Good, because Mozilla already uses it and has licenses for its use.
- Bad, because it's expensive and only our licensed users can change the diagram.
- Bad, because diagrams can't be automatically laid out.
- Bad, because models and relationships in the diagram have to be manually created and can't be re-used between them.
- Bad, because diagrams can't be reduced to any representation that can be saved in our repository other than the image.
- Bad, because we will lose our ability to make changes to our diagrams if we stop paying for LucidChart.