This is still very long - as the post is :-)
However, this issue is mostly about aligning what we call different containers/components/blocks and asking for more context, when I think something is a bit unclear to the reader.
Generally
I'm still not 100 p certain on the white / black box distinction as it is described and used. They might have been reversed some places in the texts? If that is not the case, adding more text describing the figures and tables explicitly might help with my confusion :-)
E.g., In the introductory text, L19-20, it says that the second section goes deeper, "but only describes the contents as black boxes", then under Building block, Level 2, the figure is called "Web Portal (white box)" and the table right underneath it says "Black boxes within the Web Portal part"?
The header is "Building block view", but each block is called parts throughout the text. Would it be more clear if they were callled blocks instead?
Introduction:
As a reader, it is unclear to me what "Level 1" and "Level 2" entails. Maybe include that explicitly?
"Back end environment" is the only container which subparts are shown in this overview figure. Maybe remove them here so all containers are on the same "descriptive level"?
If keep sub-containers here, "Database" container within BEE is called "Relational Database" in the BEE figure. Add "relational" here as well?
If keep sub-containers for "Back End Environment" in figure:
"This enclosed environment contains the inputted data, admin details, changelog, and raw data." -> Where specifically in the three containers shown in the figure? Database, File Storage, or Large File Storage, respectively?
Mentions of "Admin users" - align across posts to call them either "admin users" or "administrators"?
Mentions of "Web Portal" - is that the same as the "Web Interface" defined above or something else? If something else, maybe clarify what it is (it's neither in the figure nor defined in the table or text). Is the same, maybe align the wording to avoid confusion?
Under "User and Data Management Layer:" there is a mention of "advanced users" - who are these users? Add a description of those under System Scope and Context?
Building block Level 2
Add an introductory sentence on the content of this section before going into the subheader "Web Portal (whitebox)?
Not sure what the "Front End" box adds to the figure? :-) "Front end" is only mentioned here on this page and the box only contains "User Interface". If keep, it would be helpful to clarify explicitly what is meant by this in the text
The page "Project information pages" in the figure was missing in the table. I have added it in the design-text-mods branch, but a description is still missing
"User Login Pages": "[...] before they can access protected areas" - clarify which are the protected areas? Considered whether the figures could visualise which areas are protected, but I think it might clutter them/make them too complex?
"Data Detail Pages": Called "Data information pages" in the figure. Align? Which one to use? :-)
"Upload Data Pages": add file types that will be accepted, i.e., json and csv (as far as I understand)? Also images?
"Download Data Pages": Which "authorised users" are allowed to download data? Add this to the description of users under System Context and Scope?
After the table, two level 4 sub headers appear ("Data catalog", "Data projects"). As a reader, I'm not sure how these fit with the pages described in the figure and table? Maybe add context before "Data catalog" to clarify what these are and how they fit with the information above? Do they correspond to pages described in the table? If yes, why were these described further and not the remaining pages?
Is "Data catalog" = "Data List Pages" or "Data Detail Pages", maybe?
Since this container is called "User Authentication" in the header and in the initial figure, should the header in the figure be that as well, instead of "User ID Management"?
Table "Blackboxes within the User Authentication part.": Not sure what the containers (i.e., "Local Authentication" and "Connect Remove ID Server") are/do. Maybe add some more context here?
Header "User and Data Management Framework" --> Should that be "Layer" instead?
It seems that the "Admin Portal" part of the figure is described in the table "Black boxes related to Admin Management within the User and Data Management Layer part". Write "Admin Management" in the figure as well?
It seems that the "API Layer" sub parts are described in the table "Data entry" further down. Move this table up to just after the figure and align naming here as well?
The API endpoint section from L142 and down, with specific response status codes, does not have a header and seems to be a but out of place here? Should this be moved to a separate post?
Maybe define what is meant by an "endpoint" and what the commands (e.g., POST /data/raw/) are, i.e., that they are HTTP request methods (right?) and that they are a part of RESTful APIs?
When describing e.g. "(string)" make sure that it's followed by either "optional" or "required" - this is not always the case, currently
Mention of "authorised" users again. Who are these users? Define under System Context and Scope?
"If the action is “update”, the user must also provide the new value of the permission field.". As a reader, I'm not sure what's meant with action is here? Maybe an example would help?
Generally: It might be helpful to have written out examples of the codes - e.g. showing the full JSON object with a user id, etc. after explaining the sctructuer under "Assign permissions to users"
What is meant by"dataset" and "data file", respectively? Could this be clarified with examples in the table?
"List Projects Metadata": "[...], it could use parameters to display related project metadata." Does this mean that parameters are optional? If yes, write that explicitly instead of "it could use"?
Back End Environment (whitebox)
This section starts off with a list of the components, L301-315, which seems to correspond to some parts of, but not a complete overlap with, the figure and table below? Could all elements from this list be included in the figure/table instead?
Figure (don't want to implement changes for this figure since it's currently being revised in the pr seedcase-project/seedcase-project#176 as well)
Remove "ID" from "User ID Authentication" to align with rest of the text
How does the "API layer" relate to earlier figures? Is it = "User and Data Management layer" or is actually the sub-container within "User and Data Management layer"? Maybe change it to "User and Data Management Layer", to only include the "level 1" container, like "User ID Authentication"?
Table "Blackboxes within the Back End Environment part": Includes a container and components not on the same "level", i.e. the two components in "File storage" ("Raw File Storage" and "Large File Storage") and "Relational Database" (which contains four components)
Would it make more sense if that was "Relational Database" and "File storage" overall and then tables describing subparts of those?
Align the Building blocks with their names in the figure: Which one to use? :-)
Table "User information" vs figure "Information on users"
Table "Resource data" vs figure "Data in Tables"
Table "Data project information" vs figure "Data projects in Tables"
Table "Changelog" vs figure "Changelog in Tables"
Is "File Storage" in the C4 container diagram = "File Storage" in the BEE C4 component diagram? If yes, the "Large file storage"seems to be a subpart of "File storage" and should be removed from the overview diagram? If no, the BEE figure needs to be adjusted to be aligned with the overview figure :-)
This is still very long - as the post is :-) However, this issue is mostly about aligning what we call different containers/components/blocks and asking for more context, when I think something is a bit unclear to the reader.
Generally
Introduction:
Whitebox overall system, Level 1
C4 container diagram:
Table "Core internal parts of Seedcase (as black boxes)":
The list "This list describes the individual blackbox parts in more detail:"
Building block Level 2
Add an introductory sentence on the content of this section before going into the subheader "Web Portal (whitebox)?
Web Portal (whitebox)
Table Blackboxes within the Web Portal part:
After the table, two level 4 sub headers appear ("Data catalog", "Data projects"). As a reader, I'm not sure how these fit with the pages described in the figure and table? Maybe add context before "Data catalog" to clarify what these are and how they fit with the information above? Do they correspond to pages described in the table? If yes, why were these described further and not the remaining pages?
User Authentication (whitebox)
User and Data Management Layer (whitebox)
The API endpoint section from L142 and down, with specific response status codes, does not have a header and seems to be a but out of place here? Should this be moved to a separate post?
Maybe define what is meant by an "endpoint" and what the commands (e.g., POST /data/raw/) are, i.e., that they are HTTP request methods (right?) and that they are a part of RESTful APIs?
"Authorisation (string):" - Is this string unique to the user or general?
"Assign permissions to users":
Generally: It might be helpful to have written out examples of the codes - e.g. showing the full JSON object with a user id, etc. after explaining the sctructuer under "Assign permissions to users"
"Data entry" table:
Back End Environment (whitebox)
This section starts off with a list of the components, L301-315, which seems to correspond to some parts of, but not a complete overlap with, the figure and table below? Could all elements from this list be included in the figure/table instead?
Figure (don't want to implement changes for this figure since it's currently being revised in the pr seedcase-project/seedcase-project#176 as well)
Table "Blackboxes within the Back End Environment part": Includes a container and components not on the same "level", i.e. the two components in "File storage" ("Raw File Storage" and "Large File Storage") and "Relational Database" (which contains four components)
Is "File Storage" in the C4 container diagram = "File Storage" in the BEE C4 component diagram? If yes, the "Large file storage"seems to be a subpart of "File storage" and should be removed from the overview diagram? If no, the BEE figure needs to be adjusted to be aligned with the overview figure :-)