design/software-architecture/cross-cutting-concepts: Text/figure suggestions

[signekb]

This issue became quite long, but the post also has many sections :-)

Introduction/first section

• This page doesn't include an introduction on what it covers. I think that would be helpful, since it covers a lot!
• Not sure how the title "cross-cutting concepts" relate to the content? An introduction might help to clarify this

Security

• The figure's "layers" are not the same as the layers described in text, see post. Maybe the text (and/)or the figure need to be updated? Or are they describing two different things? It seems that the text outlines (some, but not all of) the sections to come while the figure doesn't?
  • Maybe align the headers throughout the post with this list?

Authentication/permission

• Mention of "relevant institutions": could we be more explicit about who these relevant institutions are?

  • https://github.com/seedcase-project/seedcase-project/blob/d6086fe2ca077597dc7cf00db9d863055f04139e/design/software-architecture/cross-cutting-concepts.qmd#L67-L69

• L65-L101:

  • Two-factor authentication is mentioned in-text but not described in the list below
  • Basic Authentication and User Tokens are described in the list but not mentioned right above (where 2fa and OAuth are mentioned)f
  • Will Seedcase use both Basic Authentication, User Tokens, and OAuth? Maybe a sentence describing what the list covers will clarify that?
  • Basic Authentication: Not sure I understand the last sentence: "When make API request need to include the correct username and password."?
  • User Tokens:
    • First mention of a "seedcase box". What is that? Maybe relevant to naming and seedcase-project/design#21
    • Not sure I understand the last sentence. Maybe rewrite?
      • https://github.com/seedcase-project/seedcase-project/blob/d6086fe2ca077597dc7cf00db9d863055f04139e/design/software-architecture/cross-cutting-concepts.qmd#L87-L88
  • OAuth:
    • Mentions "Seedcase" seedcase-project/design#21

Data-in-transit

• Add section after this named "Server-based security" explicitly stating what it is and how it is outside the scope of Seedcase so all points in the list in the Security section has a corresponding header?

Privacy

• The "Seedcase Project itself" is mentioned for the first time on this page, along with "Seedcase". seedcase-project/design#21
• First mention of an Administrator light user:
  • https://github.com/seedcase-project/seedcase-project/blob/d6086fe2ca077597dc7cf00db9d863055f04139e/design/software-architecture/cross-cutting-concepts.qmd#L158-L160
  • Should that be mentioned when users are defined/described on the System context and scope page?
  • "other database objects." - include examples of other database objects?
• "First and only mention of activated users --> what is an activated user?
  • https://github.com/seedcase-project/seedcase-project/blob/d6086fe2ca077597dc7cf00db9d863055f04139e/design/software-architecture/cross-cutting-concepts.qmd#L171

Legal

• Header: Legal what? concerns? security? other?
• Storing the data: "(see section on C4 design)" - I'm not sure which section that refers to, but it would be helpful to include a link to this section
• Limiting access to data: This section feels a bit repetitive of the first section under Privacy. Can/should they be merged?

Logging and monitoring

• Administrators and admin users are used interchangeably. Should it be aligned?

Multiple domain-specific standards

• "Open standards will be prioritized first": Include examples of these?

User permissions

• Table:
  • "THIRD PARTY" --> Should that be "external user" as it is named on the System context and scope page?
  • Are there/should there be any particular order of the rows in this table?

Computational and storage locations

• "Table 1" is not actually the first table on this page. More generally: seedcase-project/seedcase-project#167

Dissemination

• I feel like this section, with specific docker commands, is a bit misplaced here? Should it be on its own page called something like "Installation" or "Getting started"?

The sections Archiving and Documentation seem to be in a rather drafty state still :-)

[martonvago]

I agree with this in general, especially the points about the security diagram, authentication and the Dissemination section. I also thought the user roles were a bit confusing at first, so maybe it'd be worth noting explicitly that these are database-level roles and do not have to correspond 1-to-1 to the users/actors in the use cases?