Skip to content
This repository was archived by the owner on Sep 6, 2023. It is now read-only.

Architecture Documentation - #211

Merged
Weltraumschaf merged 10 commits into
secureCodeBox:mainfrom
Stijn-FE:architecture_documentation
Mar 16, 2022
Merged

Weltraumschaf merged 10 commits into
secureCodeBox:mainfrom
Stijn-FE:architecture_documentation

Conversation

@Stijn-FE

@Stijn-FE Stijn-FE commented Jan 20, 2022 •

Copy link
Copy Markdown
Contributor

Hi all, I'm Stijn van Es from Secura and as mentioned in issue #208, I wanted to work on the architectural documentation for secureCodeBox (SCB). So far, I have worked mainly on a functional description of SCB and I will continue with the following:

  • A building block overview
  • A deployment overview
  • A runtime overview
  • A description of relevant cross-cutting concepts

To complete the documentation, some questions regarding ownership and sponsoring have been posed by my colleague @EndPositive in issue secureCodeBox/secureCodeBox#731 on the main repo. Could you please provide some information regarding these questions?

Since I am new to this project I lack some background in the architectural choices and technical debt on this project. Therefore, I won't be able to fill in the chapters on technical debt and quality requirements. Could you please check these chapters on accuracy and maybe fill in the required information.

  • Risks and technical debts
  • Quality Requirements

closes: #208

Signed-off-by: Stijn van Es <stijn.vanes@secura.com>
@netlify

netlify Bot commented Jan 20, 2022 •

Copy link
Copy Markdown

❌ Deploy Preview for docs-securecodebox-test failed.

🔨 Explore the source changes: a0a94c4

🔍 Inspect the deploy log: https://app.netlify.com/sites/docs-securecodebox-test/deploys/6231b9cf29bbdb0008f867ea

@Stijn-FE
Stijn-FE marked this pull request as draft January 20, 2022 11:44
@Stijn-FE Stijn-FE changed the title initial commit Architecture Documentation Jan 20, 2022
@J12934
J12934 self-requested a review January 27, 2022 16:07
@J12934 J12934 added the documentation Improvements or additions to documentation label Jan 27, 2022

@J12934 J12934 left a comment •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi awesome work.
Really like the structure of the templates, this should really expand the doc to include aspects previously grossly uncovered by it.

I've tried to answered @EndPositive questions in the issue as much as possible, hope this helps.

I've added a suggestion to update the iteratec team members and their roles.

What tool did you use to generate the diagrams? Would it be possible to include their source files in the repo so that they stay editable? Otherwise we'd have to completely redraw them whenever we want to change them.

If you need help on the other sections please reach out, I'd be happy to help :)

Comment thread docs/architecture/introduction.md Resolved
Comment thread docs/architecture/introduction.md Resolved
@Stijn-FE

Copy link
Copy Markdown
Contributor Author

Hi, happy to hear the structure is to your liking.

Thanks for the info and the additional changes.

For the diagrams, I've used draw.io. The source code is incorporated in the .png files. You should be able to load the .png files directly into the draw.io editor. I'll add an explanation on how to edit in the docs.

@Weltraumschaf Weltraumschaf added the planned Issues we will do in the next sprint. label Mar 2, 2022
@Weltraumschaf
Weltraumschaf self-requested a review March 11, 2022 10:37
@Weltraumschaf

Copy link
Copy Markdown
Member

Hi @Stijn-FE ,

we have decided to start documenting the architecture. The idea is as follows:

  1. I review what you've done yet.
  2. We merge your PR.
  3. I refactor your work to match the Arc42 template. (This is a widely adopted template for architecture documentation.)
  4. Then we evolve the documentation step-by-step.

So, please convert your PR from draft to ready :-)

If you're not familiar with Arc42 and want to know more about it, we may schedule a short (~30 min) appointment to tell you the basic idea of it.

@Stijn-FE
Stijn-FE marked this pull request as ready for review March 11, 2022 12:56
@Stijn-FE

Copy link
Copy Markdown
Contributor Author

Hi Sven,

Good idea to use Arc42. I looked into this a while ago and actually meant to use this template in this PR. If you have any questions regarding the changes in this PR, please let me know.

@Weltraumschaf

Copy link
Copy Markdown
Member

Ah, I wondered if you did the structure by accident like Arc42 :-)

@Weltraumschaf Weltraumschaf left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice work! This is a really good starting point and my hope is that we now evolve to a good architecture doc with this foundation :-)

If you do my suggestions (mostly the copyright header) I'll merge this.

Comment thread docs/architecture/introduction.md Resolved
Comment thread docs/architecture/introduction.md Resolved
@Weltraumschaf

Copy link
Copy Markdown
Member

Hi @Stijn-FE,

would you please look into our suggested changes? Our current sprint ends tomorrow and we would like to merge this PR to plan the next steps for the next sprint.

@EndPositive

Copy link
Copy Markdown
Contributor

Leaving a comment here that Stijn is currently unavailable, but verbally agreed to the last few comments.

@Weltraumschaf

Copy link
Copy Markdown
Member

Hi @Stijn-FE,

@EndPositive told me that you're away at the moment, so I committed all the suggestions and will merge it.

@Weltraumschaf
Weltraumschaf merged commit 7ee7014 into secureCodeBox:main Mar 16, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

documentation Improvements or additions to documentation planned Issues we will do in the next sprint.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add architecture documentation

4 participants