Skip to main content

Software Guide Rails

warning

THIS SECTION IS MARKED FOR DELETION

The guide rails below are used by CRUK's Software Engineering teams to ensure alignment and aid decision making.

Summary​

Guide RailDescription
LanguageTypeScript
Version ControlGitHub - Product Monorepos
Cloud PlatformAWS
AWS ServicesServerless
Lambda >> Fargate >> EC2
DynamoDB >> Aurora Serverless >> RDS
EnvironmentsPR - ephemeral for testing
Integration (int) - static for clients
Production (prod)
AWS Accountsint - PR & Integration Environments
prod - Production Environment
Frontend Testing Librariesjest | vitest | React Testing Library | Cypress | Playwright

Introduction​

The Software Engineering team’s purpose is the design, development, operation of custom-developed software for the charity. This includes:

  • External-facing websites such as the main Cancer Research UK website
  • Web applications such as the Payments Web Service, Online Fundraising and Event Management
  • Applications aimed at researchers, clinicians and internal users like the ECMC Trial Finder
  • Data integration solutions like Person Hub or the U4BW interfaces

This document defines high-level principles that all software engineers at Cancer Research UK should adhere to. This promotes strategic alignment and consistency between teams whilst empowering engineers to make lower-level decisions as part of their day-to-day work. The main benefits of adhering to these principles are that:

  • engineers are able to move between teams more easily thanks to familiar frameworks and patterns and
  • technical decision making is quicker as higher-level decisions have already been made

Assurance approach​

The assurance approach to ensure these guide rails are followed is to:

  • Involve the software engineering team in early stages of initiatives where buy vs build decisions are made
  • Ensure all code changes go through a code review, either by a peer or by a more senior Engineer; Lead Software Engineers are accountable for the guide rails being followed within their teams

Exception process​

If an engineer needs to deviate from these guide rails, they are expected to produce a decision document supporting this, to be approved by the Senior Manager of Software Engineering or the Head of Engineering. This decision document should be kept with the rest of the product documentation (typically in the code repository) for future reference.

Engineering approach​

When & how to engage with the Software Engineering team​

The Software Engineering team’s purpose is to design, develop and operate custom-built applications for the charity where suitable off-the-shelf commercial alternatives do not exist on the market or where there is a strategic advantage to developing a custom solution.

Rationale​

The Software Engineering team’s purpose is to design, develop and operate custom-built applications for the charity such as:

  • Content Management System (CMS) websites such as the main Cancer Research UK website
  • External-facing fundraising web applications such as the Payments Web Service, Online Fundraising and Event Management
  • Web applications aimed at researchers, clinicians and internal users like the ECMC Trial Finder
  • Data integration solutions like Person Hub or the U4BW interfaces that allow custom-built or off-the-shelf applications to communicate with each other

The Engineering strategy is not to develop custom applications where suitable off-the-shelf commercial alternatives exist on the market. Good examples are U4BW (Finance system), Workday (HR system), FirstClass (legacy management system).

Separate Engineering teams are in place for CRM/Marketing engineering and Business Intelligence.

The Software Engineering team should be engaged during the discovery phase of new products/services/initiatives to assess and estimate options, design custom solutions and mobilise the delivery team using either internal or external software engineers.

Further reading​

Preferred cloud platform​

The preferred cloud platform for software engineering is AWS. Specialist service providers/vendors will only be considered if they have a significantly superior offering to the equivalent AWS service. The preferred approach is to adopt its native services and libraries (as opposed to cloud-agnostic tools or abstraction frameworks).

Rationale​

Focussing our skills on one cloud provider makes the most of the software engineers we have available. Using native services and libraries (e.g. AWS Lambda, AWS SDK, AWS CDK) rather than abstraction frameworks (e.g. Serverless Framework, Terraform) reduces complexity and allows us to recruit more easily.

Further reading​

Preferred AWS services​

We prefer using serverless services (e.g. prefer Lambda over Fargate, Fargate over EC2, Aurora Serverless over RDS).

Rationale​

Serverless services require less coding and less maintenance to meet the same non-functional requirements

Further reading​

AWS accounts and test environments​

Each product should have the following AWS accounts with the minimum following environments:

AWS Account: Integration (int)

  • PR environments
  • Integration environment (optional)

AWS Account: Production (prod)

Rationale​

Fewer static environments (Reduces environment rot, lowers cost, removes bottlenecks) Quicker releases: having fewer environments from the PR to Production results in quicker releases as every change approved is merged and pushed to the Production environment. Aligned AWS accounts and environments across product teams. Clarifies what environments to connect across products.

Further reading​

Preferred Frontend Testing Libraries​

Jest, Vitest, Cypress, React Testing Library, Playwright

Rationale​

Jest is the most common test runner for modern JS development. It is used for rudimentary unit tests. Vitest is a modern contender that is Jest-compatible that should be a drop-in replacement for Jest. It includes a lot sane defaults and interesting concurrency modes for test execution.

Cypress is our preferred testing tool it is well known by our QA team. It can be used in interactive or headless mode where a real browser is used to test real browser behaviour. It has a rock solid and comprehensive API and multiple add-on modules written by its large community. The only caveat is if your tests need to jump multiple domains; in this scenario we would recommend using Playwright.

React Testing Library does a good job of being a fast framework that doesn’t require a browser. It uses real DOM elements to test with instead of shallow rendering like enzyme, so it is much more closely aligned with real user experience.

Further reading​