Public facing web UI requirements

Reference Documents

Reference Document Location
AQUASEC Aquasec
TESTING Software Testing
MONITORING Monitoring platform
PYT_LOG Python Logging
CI_CD CI/CD Policy
UPGRADES Managing Upgrades

Problem Description

Client facing User Interfaces in Ebury lack a subject matter requirements document. This document will outline what we expect from client facing web UIs, e.g. technical implementation, monitoring, code quality, and SDLC.

This document covers requirements for future web UIs but without specifying any specific technologies, e.g. we're not going to enforce that everything must be written in Vue.js or React. Any technology from the present or the future is alright if it matches requirements written down below.

This document covers only web UIs and not the mobile UIs.

Background

At the moment, Ebury has 4 public facing web UIs:

  • online.ebury.com: Online portal allowing our contacts to manage their trades, payments, beneficiaries, trade finance and profile
  • ebury.com: Ebury's main landing marketing website
  • apply.ebury.com: Onboarding forms for new clients
  • Ebury Solutions Community: An operations portal used by Ebury partners for account creation process

Solution

  1. UIs must use the Ebury brand Design System, Chameleon.
  2. UIs should use TypeScript.
  3. UIs should use server side rendering and may use single page application pattern.
  4. UIs must follow industry SEO best practices.
  5. UIs must only use API gateway.
  6. UIs should follow Web Content Accessibility Guidelines, version 2.0.
  7. UI's code must be accompanied by tests.
  8. UIs must conform to monitoring practices.
  9. UIs should have multi language support.
  10. UIs should be brandable.
  11. UIs must meet the security standards.
  12. UIs should be deployed to K8s.
  13. UIs should track user journeys.
  14. UIs must follow policies for CI/CD.
  15. UIs should comply with all laws and statutes applicable in the relevant jurisdictions.

Dictionary

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Chameleon Design System

The Chameleon is an atomic design system we use at Ebury, maintained together by our UX Team and the ONL team.

Every public facing UI must follow the Chameleon design system to ensure a consistent look across all UIs.

The implementation of the design must comply with accessibility standards (see accessibility section) and must be fully responsive using mobile-first approach.

Deviations from the design must be approved by the design and product team. It's important to keep the number of variants in the design as low as possible to reduce maintenance and development cost and keep the UIs consistent.

UI Frameworks

There's no limitation which UI framework or ecosystem can be used for developing the UI as long as the framework and its ecosystem is capable of matching all requirements in this RFC.

When choosing the framework, consider to re-use frameworks already in use at Ebury. There may exist components and/or tools that are ready to be reused which may speed up the prototyping and further development of a new UI. Choosing a new framework/ecosystem previously not used in the company requires creating an RFC, justifying why it is a better choice as well as how Ebury is going to maintain the UI in the long term.

Programming Languages

All web UIs should use TypeScript. Using JavaScript could be allowed for low budget projects. Using other languages that transpile to JavaScript (e.g. Dart, CoffeeScript, Reason) is not allowed.

SSR or SPA?

It is important to clarify whether public facing web UIs should use Server Side Rendering (SSR) or Single Page Application (SPA).

Clients should use SSR, and may follow a SPA pattern. The next chapter describes available options and recommended approaches to UI rendering and SEO.

Rendering web UIs

  • Client side rendering (only SPA): The server only renders static HTML and the bundled app is rendered on the client side. This used to be a preferred way of rendering apps in the last couple of years but due to performance and UX issues, the FE community started shifting away from this approach and towards the use of SSR. Performance issues are caused by huge JavaScript bundles that users are required to download before the app can be rendered. This reduces the UX with mobile device users impacted the most. Code splitting, prefetching bundles or modulepreloading solves the problem partially but due to differences in browsers implementation it's not always a reliable solution. On top of that, the SPA kills SEO because the initial render yields nothing that can be indexed and search engines penalise pages with huge assets served on mobile. Due to all these limitations, using only SPA for new UIs is prohibited.
  • Universal rendering (SSR + SPA): UI components can be rendered on the server side and on the client side using the same, universal, code. The server loads data and renders the UI so the user can see and can interact with the UI immediately after page load. Then the SPA is spawned, hydrates the state embedded by the server and continues from that point. This approach is recommended for complex UI applications (e.g. Eburyonline or Operations Dashboard) and can be achieved by any modern framework (e.g. next.js, nuxt, SvelteKit, Remix). For websites, it is recommended to drop SPA bits and rely only on SSR without client side routing and hydration. Modern UI patterns even allow to ship less code to the client, e.g. by reducing runtime code (Vue Vapor mode, SolidJS), or by using components without client side interactions (React Server Components), or by loading the client side on demand (e.g. Qwick).
  • Static Site Generation (SSG): Pages are rendered during the build and can be served as static assets using just nginx and CDN. Recommended for commercial, non-interactive websites.
  • Edge-side rendering/CDN rendering (ESR): An extension to SSG and Universal rendering allowing to render the website or application in the CDN as close to the user's device as possible, significantly reducing latency. This extension is recommended for global commercial websites but UI applications may not leverage their potential because of data loading from a database located on the other side of the world.

SEO

Every public web UI should be optimised for search engines. For commercial content it's a must have, web applications should provide SEO for their anonymous public pages.

SEO requirements to follow (if applicable to the web UI):

  • The UI must render the website without JavaScript as most crawlers don't support it.
  • The UI must be mobile friendly as crawlers take that into consideration when indexing.
  • Every page or resource must have their own URL, if a user refreshes the page, the UI must display the page as it was before reload.
  • If the app is multilingual then it must be indexed for all languages.
  • The UI must also follow industry SEO best practices.

Server runtime

The new UIs should use only node.js as a server runtime using only approved docker images (see RFC for UPGRADES). It's possible to use other solutions (e.g. Deno, Bun) if justified via RFC (same as UI Frameworks section).

Connecting web UI to API & Gateway

If a web UI needs API endpoints to fetch data, it must only connect to the Bosporus gateway (GraphQL). The API gateway must provide authentication and authorisation for each request. Bypassing the gateway and connecting to Ebury services directly is prohibited. Creating your own API gateway is prohibited too. If the desired Ebury service is not exposed yet via Bosporus, adding it must be considered when planning and developing a new UI.

For better UX and performance, the web UI must have the client side validations to prevent unnecessary requests to the API. The only exceptions are validations that can be performed only by the DB (data integrity, collisions, uniqueness) or 3rd party services (e.g. AML, Bank Account validations).

Auth

If the web UI requires authentication/authorisation, it must use Ebury IAM.

A11Y

All web UIs SHOULD follow Web Content Accessibility Guidelines (WCAG) 2.0, level AA. Accessibility testing SHOULD be part of the QA executed during CI.

Testing

There's already a general guide to testing at Ebury (see RFC for TESTING). The following requirements are web UI specific additions:

What tests to write?

  • Unit tests: dumb components, composables, services, utils, formatters, tooling, stores
  • Integration tests: smart components, components integration, APIs
  • Visual regression tests (optional): components
  • E2E tests: critical user journeys (happy paths only)
  • Smoke tests: critical user journeys (no logic)

We value the integration tests more than other tests because they cover complex logic and integrate the components together. Overall, our test pyramid more resembles the term called the testing trophy, explained in the video Write tests. Not too many. Mostly integration. by Kent C. Dodds.

Code coverage

We measure the code coverage in unit tests only. We always aim to have coverage as high as it gets but we don't require 100% coverage. However, the code must be clearly excluded from the coverage so it's discussed in the PRs.

Monitoring

All web UIs must conform to monitoring practices already defined in the Monitoring platform (see RFC for MONITORING). TL;DR:

If metrics are applicable:

  • Web UI must expose Prometheus metrics and must have alerts
  • Web UI must have Grafana dashboard
  • Web UI must have health checks

On top of that, there are monitoring requirements for web UIs such as:

  • The UI must monitor and log all client side errors using Sentry.
  • The UI must mask or remove Personal Identifiable Information (PII) from all logs and traces. (Same as mentioned in RFC for PYT_LOG)

I18n & L10n

If the web UI requires multi language support, both i18n and i10n must follow requirements from this RFC. It's possible to ship a web UI without i18n & i10n only after approval from product owners. As Ebury is a multinational company with global presence, this is very unlikely for public facing UIs.

Translations must be stored and processed in Crowdin.

If the UI is translated, it must also format all dates and numbers so they match the locale of the language that the user uses. The plural rules must be followed as some languages have multiple plural forms (Slavic, Arabic), some don't have plurals at all (in Asia). When sorting strings, the different alphabetical order of the locale must be respected too (e.g. French, Nordic, Slavic).

If support for RTL language (e.g. Arabic, Hebrew) is needed, the design and the UI must be adjusted for that.

All online communication with the user (e.g. via email or SMS) must be translated to the language the user uses in the web UI.

Branding / White Labelling

If the web UI is intended for use by clients of other Ebury partners, it must follow branding requirements we already use in other UIs such as Eburyonline:

  • The UI code should be brandable. This means the code should avoid hardcoding colour palettes, CSS, logos, images, and SVGs must be configurable.
  • Texts that mention "Ebury" should have a branded alternative.
  • HTML emails and PDFs generated by the backend must follow the same branding as the UI.

Performance

It's important to watch for the bundle size and doing regular reviews of performance budget of the web UI. Smaller bundles decrease time to first meaningful paint, improving UX especially on slow mobile devices.

The web UI must use gzip/brotli compression for all assets except binary content.

Binary content (e.g. images) must be optimised for web usage by striping metadata and reducing colour palette (e.g. using imagemin, TinyPNG, Squoosh). Images must use the most efficient format that fits the image content and produces the smallest size while not reducing content quality for the user (e.g. using png vs webp vs jpg vs avif).

The bundle must be minified, must perform code splitting so the biggest chunk is no larger than 70kB. Unused code (JavaScript and CSS) must be removed from the bundles using techniques such as tree shaking and CSS purging. Bundles must be loaded with priorities, first bundles for Largest Contentful Paint and then the rest of the application when the browser is idle to allow user interactions as soon as possible.

Every asset and API call must return information how the content is cached via Cache-Control HTTP header. Not having the header specified often leads to browsers guessing how the assets should be re-used. Browsers are often conservative and they rather not to cache so they won't break the website. Sometimes browsers cache dynamic content like API calls which leads to hard-to-reproducible bugs. Cache-Control must always make the assets cacheable in CDN and on the client to minimise the number of requests for returning users and cache misses in CDN.

If the web UI is available to Ebury's global audience, it must use CDN to distribute assets. Currently we only allow the use of AWS CloudFront for this purpose.

The only allowed versions of HTTP protocol for serving assets are version 2 and above. HTTP/1.1 is prohibited due to performance reasons. Thanks to connection improvements in HTTP/2 and above, it is no longer recommended to use domain sharding (e.g. having assets split to multiple domains like images.ebury.com, videos.ebury.com) for distributing assets to clients.

Browser support

We support browsers that are no older than 2 years and have at least 1% market share (Chrome, Firefox, Safari, Edge), see Eburyonline configuration as a reference. It's possible to adjust the list or add more if a target market has specific needs.

It is important to regularly update the list of supported browsers to reduce the number of polyfills needed for running the code in the browser and having as much of the latest technologies available as it gets.

Security

Every web UI must comply with security standards:

  • Must use only secured protocols HTTPS and wss. For HTTPS, it must specify Strict-Transport-Security header (HSTS) and must register HSTS preload if applicable.
  • TLS protocol must not use outdated or vulnerable ciphers (must score A grade or better in SSL labs).
  • Must have a non expired, non revoked certificate and a valid certificate chain (OCSP Staple).
  • Must have Content Security Policy header (CSP), must block everything by default, must not allow unsafe-inline, unsafe-eval directives and must report CSP errors to only approved 3rd party services (e.g. Sentry).
  • Must have score an A with https://securityheaders.com/.
  • Must not use vulnerable dependencies (see RFC for AQUASEC).
  • Must have a firewall protection against malicious bots and actors (e.g. AWS WAF).

Infra

If hosting on Ebury infrastructure, all new web UIs must be deployed in the K8s cluster. Adding more tasks to ECS is no longer a valid option.

User Tracking

Tracking user interactions is an essential part of every web UI but it's not enforced. The requirements should be always discussed with product owners and the design team about metrics they want to collect for UX improvements. Collecting metrics for generating reports or client data analysis is prohibited and the app should use data warehouse solutions already maintained by the Data Team.

If tracking users is required and 3rd party services (e.g. Segment, Google Analytics, Inspectlet, Sentry) are used for collection, it must use only approved parties and the purpose of collected data set must be approved by the Data Protection Team.

If the trackers use cookies, the user must give a consent first and must have options to opt-out from non-essential cookies.

The trackers should be treated as a progressive enhancement/graceful degradation philosophy. If the tracker fails to load or fails sending the event to the 3rd party, it must not break the journey that the user tries to achieve. The UI must be able to continue if the tracker has been removed by adblockers or browser extensions guarding users privacy.

In case the 3rd party service has an outage, there must be a way to turn the tracker off and the UI must be able to continue without the tracker.

User support

The web UI should have a help page (or any form of guidelines) for the users and provide communication channels to contact Ebury's help desk team. If a 3rd party solution is used (e.g. Intercom), it must be only from a list of approved 3rd parties.

CI/CD

Web UI must follow all policies defined in the Policy for CI/CD (see RFC for CI_CD).

On top of that, we define frontend related requirements for the CI/CD:

  • CI must lint TypeScript, JavaScript, CSS code and A11Y (using linter of their choice, e.g. eslint, stylelint, or axe).
  • CI must audit npm packages (e.g. via Aquasec, npm audit or using Snyk DB).
  • CI must execute all tests before merging to master.
  • CI must verify type safety and JSON schema defined by the backend (either using GraphQL schema or OpenAPI schema).

Compliance

Each web UI should comply with all laws and statutes applicable in the relevant jurisdictions. These must be discussed with product owners and the Compliance Team while planning the UI ahead.



Based on RFC Template Version 1.1