Skip to main content

Software Guide Rails

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

Summary​

Guide RailDescription
LanguageTypeScript
FrameworksNextJs | Chakra
Version ControlGitHub
Cloud PlatformsAWS | Vercel
Frontend Testing LibrariesJest | Vitest | Playwright
Design SystemHelix | Component Library

Introduction​

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
  • 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 in 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.

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).

To enable our headless content strategy we have partnered with Vercel for hosting our NextJS websites for our core sites. Where possible we want to follow this reusable pattern for future sites.

Rationale​

Focusing 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.

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

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.

Preferred Frontend Testing Libraries​

Jest, Vitest, 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 sensible defaults and interesting concurrency modes for test execution.

Playwright is our preferred testing tool it is well known by our QA team.

Further reading​