Skip to content

Architecture

Jump to bottom
Ray Millward edited this page Mar 25, 2019 · 14 revisions

Context

Containers

Components

Deployment

Architectural Background

Technologies

The technology stack selection has been based on the principles of:

  • Making use of Open Source Software
  • Selecting modern, well supported frameworks to ensure long term sustainability (within the bounds of the previous principle)
  • Fitting in with STFC processes where there are clearly defined technology choices for consistency

Tools

  • Create React App for the initial site template
  • Jest unit testing and coverage
  • Cypress end-to-end testing
  • React Storybook
  • React Storybook Info addon
  • ESLint with the Typescript rule set
  • Prettier code styling
  • Husky for pre-commit hooks
  • GitHub for Agile tracking
  • GitHub for version control and issue management
  • GitHub for the documentation wiki

Languages

  • JavaScript
  • Markdown

Frameworks

  • React
  • Redux
  • React-Router
  • Redux-thunk
  • Material UI
  • Single SPA (micro-frontend framework)

Quality

Coding Standards

Static code analysis is done by running ESLint against the code with the Typescript rule set. Code styling is done with Prettier to avoid debates on code styling. These are both enforced as pre-commit hooks with the --fix option turned on so as much as possible is automatically fixed. This ensures the static code analysis violations remain at zero unless explicitly ignored.

Unit testing is all done with Jest which provides code coverage information using the --coverage flag, this generates an LCOV report with all the coverage information.

All code including documentation should be peer-reviewed, as such all work must be done on a branch and a pull request created in order to review the code before merging into the master branch

Branches should use the naming convention feature/{descriptive name}-#{issue number}. By adding the issue number to the end it allows people to link requirements to code.

When creating a pull request you should also add the comment

connect to #{issue number}

to the description to link the pull request to the issue.

Reviewers should build the code and run the tests, they should also take note of the impact on code coverage. The aim is to maintain a high level of coverage (e.g. over 90% is good) but whilst being pragmatic, it is not an exercise in getting a high number but rather making sure the new code is sufficiently tested for maintainability.

Security

[TODO]

Testing

See the Project Test Plan for more details about testing the system.

Attitude towards bugs and technical debt

Bugs severely affect the maintainability of the system, as far as is practical we should seek to have a zero bug system - this means that when a bug is identified then it gets prioritised to the top of the backlog and dealt with as soon as possible.

This approach should ensure that the number of bugs doesn’t become un-manageable and then ignored because they seem unsolvable.

The same approach should be employed with technical debt, we should seek to minimise technical debt so the system is more maintainable. This should allow us to develop faster because we aren’t weaving new features into an existing fragile system. The one caveat with this is that a level of pragmatism needs to be taken depending on the timescales and progress needed for the project, but remembering that every un-addressed issue will slow the project down at some point in the future.

Clone this wiki locally