frontend Documentation

File: README.md Copy Chapter

Frontend

The backend of the Guardian website frontend.

For everybody who engages with our journalism, theguardian.com is an industry-best news website that is fast, accessible and easy to use. Unlike other ways of developing products, ours puts the audience first.

Frontend is a set of Play Framework 2 Scala applications. It is built in two parts, using make for the client side asset build and SBT for the Play Framework backend.

Frontend's responsibility is to build JSON to pass to the modern rendering service, Dotcom Rendering.

Core Development Principles (lines in the sand)

These principles apply to all requests on www.theguardian.com and api.nextgen.guardianapps.co.uk (our Ajax URL)

• Every request can be cached and has an appropriate Cache-Control header set.
• Each request may only perform one I/O operation on the backend. (you cannot make two calls to the content API or any other 3rd party)
• The average response time of any endpoint is less than 500ms.
• Requests that take longer than two seconds will be terminated.

Documentation

All documentation notes and useful items can be found in the docs folder.

New developers

Welcome! How to set up and run frontend.

To get set up, please follow the installation guide.

Fixes for common problems can be found here.

Please read the development tips document to learn about more about development process.

For our deployment process, see how to deploy.

File: docs/README.md Copy Chapter

Table Of Contents

(Do NOT edit manually. Generated automatically)

[Start here](01-start-here/) Copy Chapter

• Quick start guide
• How to deploy
• Troubleshooting
• Development tips
• Testing tips
• FAQs
• Incident handling

[Architecture](02-architecture/) Copy Chapter

• The different applications composing the Guardian website
• Fronts architecture
• Libraries we use
• Archiving
• Architecture principles for CSS
• Javascript

[Dev howtos](03-dev-howtos/) Copy Chapter

• Deployment
• Guardian embeds
• Inline SVGs
• Interactives
• Repressing fronts
• Sprite production
• Template Deduping
• Testing externally on your localhost
• Testing AMIs or provisioning in AWS
• Accessing HTTP access logs for your localhost
• Update configuration in Systems Manager Parameter Store
• Overriding default configuration
• Updating the test database
• Working with Google AMP
• Working with emails
• Apply the special report tone
• Tracking components in the Data Lake
• Updating Social Media Overlay Images
• Access Preview Locally
• Sport Tournaments
• Pointing to CODE CAPI

[Quality](04-quality/) Copy Chapter

• Browsers support
• Browser support principles
• Accessibility
• Security

[Commercial](05-commercial/) Copy Chapter

• ⚠️ Moved to https://github.com/guardian/commercial-core/blob/3a8c75e619c2e4ac2d731d251f5bf186f7af89dd/docs/GAM-Advertising.md ⚠️
• Integration of commercial components
• Standalone Commercial Bundle
• Non-refreshable line items

[Features and components](06-features-and-components/) Copy Chapter

• How are trail pictures picked in Frontend?
• Tag combiners

[Performance](07-performance/) Copy Chapter

• Performance reading list

[Archives](99-archives/) Copy Chapter

• Recipe for Breton crêpes
• theguardian.com/font-loader

META: How to create a new documentation file

Documentation conventions Copy Chapter

• Find the correct subdirectory your new documentation file belongs to.
• Every documentation file should be markdown (with .md extension).
• First line of every documentation file should contain its title (used to generated the table of content).
• Store all the images in an /images subfolder in the same directory the document referencing them will be.
• Table of content (TOC) is generated automatically with every commit, all changes will be staged accordingly.