Discussion during seaside chat today https://github.com/NOAA-FIMS/seaside-chats/issues/9 drifted away from the paper to brainstorm ways to maintain the excellent diagram of our architecture which @kellijohnson-NOAA finds very helpful (originally created by @JaneSullivan-NOAA and @Andrea-Havron-NOAA):
I'm skeptical that any kind of automated diagram generation tool would produce something more useful or be less work than maintaining something by hand. I also didn't dig into the C4 model (see https://c4model.com/ and https://mermaid.js.org/syntax/c4.html).
However, I think that mermaid diagrams are easy to edit, easy to update, and well suited to git, GitHub, and bookdown (see https://noaa-fims.github.io/collaborative_workflow/contributor-guidelines.html#pull-request-review created by @Bai-Li-NOAA). I made a rudimentary attempt to convert the fig above to mermaid. I think the rendered diagram will not appear in email notifications but will appear on the github.com issue). It's not as good as the original and likely has errors, but might be useful to facilitate discussion of whether this is a path worth pursuing.
flowchart TB
subgraph R[R]
d5[add description here]:::description
end
R:::outerContainer
subgraph src[src/]
FIMS.cpp[FIMS.cpp]:::files
FIMS.dll["FIMS.dll or FIMS.so\n(created when FIMS is installed)"]:::files
end
src:::outerContainer
subgraph inst_include[inst/include/]
subgraph rcpp_objects[interface/rcpp/rcpp_objects/]
d3[Rcpp interface makes C++ classes callable from R]:::description
end
rcpp_objects:::innerContainer
subgraph common[common/]
subgraph information.hpp[information.hpp]
d1[Connects the model pieces]:::description
end
information.hpp:::files
subgraph model.hpp[model.hpp]
d2[Assembles the objective function]:::description
end
model.hpp:::files
%% link 1
model.hpp-->information.hpp
end
common:::innerContainer
subgraph population_dynamics[population_dynamics/]
d4["Modules in this folder (in .hpp) files contain functions and their parameter definitions."]:::description
modules.hpp["modules (in .hpp files)"]:::files
end
population_dynamics:::innerContainer
%% link 2
rcpp_objects<-->information.hpp
%% link 3
information.hpp-->population_dynamics
%% link 4
rcpp_objects-->population_dynamics
end
inst_include:::outerContainer
R-->|install FIMS|FIMS.cpp
R<-->|"optimization (R)"|FIMS.dll
FIMS.cpp-->|install FIMS|FIMS.dll
R<---->|Rcpp interface|rcpp_objects
FIMS.cpp-->model.hpp
%% Element type definitions
classDef outerContainer stroke:#000000, color:#ff00ff, fill:#dddddd, font-size:22px
classDef innerContainer color:#880088, fill:#bbbbbb, font-size:20px
classDef files fill:#999999
classDef description stroke-width:0px, color:#aa5500, fill:transparent, font-size:18px
Description
Discussion during seaside chat today https://github.com/NOAA-FIMS/seaside-chats/issues/9 drifted away from the paper to brainstorm ways to maintain the excellent diagram of our architecture which @kellijohnson-NOAA finds very helpful (originally created by @JaneSullivan-NOAA and @Andrea-Havron-NOAA):
I'm skeptical that any kind of automated diagram generation tool would produce something more useful or be less work than maintaining something by hand. I also didn't dig into the C4 model (see https://c4model.com/ and https://mermaid.js.org/syntax/c4.html).
However, I think that mermaid diagrams are easy to edit, easy to update, and well suited to git, GitHub, and bookdown (see https://noaa-fims.github.io/collaborative_workflow/contributor-guidelines.html#pull-request-review created by @Bai-Li-NOAA). I made a rudimentary attempt to convert the fig above to mermaid. I think the rendered diagram will not appear in email notifications but will appear on the github.com issue). It's not as good as the original and likely has errors, but might be useful to facilitate discussion of whether this is a path worth pursuing.