Anthem by Chorus One

Welcome to the Anthem codebase!

Anthem is a multi-network platform for managing Proof-of-Stake participation and data for blockchains like Oasis, Celo, Cosmos, Terra, Kava, and others. Anthem is open source and built and maintained by Chorus One.

Try out Anthem now at: https://anthem.chorus.one

👩‍🚀 Getting Started

You will need NodeJS and yarn installed to proceed.

# Clone the repo
$ git clone https://github.com/ChorusOne/anthem.git

# Use Node LTS
$ nvm install lts/* && nvm alias default lts/*

# Install Lerna
$ npm i -g lerna

# Install dependencies
$ lerna bootstrap

# Build the utils/ package
$ yarn utils:build

# Setup environment variables
$ yarn setup

# Start the server
$ yarn server:start

# Start the client
$ yarn client:start

# Start the app in development mode (no server required)
$ yarn dev

We recommend using VS Code and installing the recommended workspace extensions to make development easier.

For the application to work fully locally, you will need to obtain specific environment configuration variables. If you need to do this, please contact a Chorus One team member.

🗃️ Project Overview

The codebase is organized into a monorepo with the following packages:

client/: React client application.
cypress/: Cypress e2e test suite.
server/: GraphQL/Express API server.
utils/: Shared utils, tools, and types.

Each package contains a README document with more specific information about that package.

The utils/ package includes shared code which the other packages import. If any updates are made to this package, it will need to be rebuilt. If updates are being made frequently, the package can be built in watch made using yarn utils:watch. Note that sometimes your text editor may not immediately detect changes to the utils/ build output, when the build changes.

🚧 Testing

The entire project is written in TypeScript and all packages follow the same testing conventions. You can run tests at the top level or in any package with the following commands:

# Run Prettier
$ yarn prettier

# Run TSLint
$ yarn tslint

# Run the TypeScript compiler
$ yarn tsc

# Run all the above tests
$ yarn test

You can also run yarn prettier:fix or yarn tslint:fix to use the auto-fix options for these tools to fix any issues (or yarn format to run both in one command). Normally, any linting/styling issues should be fixed automatically on-save if you are using VS Code with the recommended extensions.

The above commands cover static and unit testing the codebase. Additionally, we maintain a suite of e2e tests written with Cypress which you can run with the following commands:

# Start the client application (it needs to be running for the tests)
$ yarn dev

# Run the Cypress tests
$ yarn cypress

This will run the Cypress tests. You can see the Cypress package README for more information.

🛰️ GraphQL

The project relies on GraphQL for the majority of the APIs. The GraphQL schema exists in the server package. To work with GraphQL, some tooling exists to generate TypeScript type definitions from the GraphQL schema. This generated code is in the utils/ package and can be imported and used by other packages. to generate the type definitions, run the following:

# Generate TypeScript type definitions for GraphQL schema
$ yarn types

🏗️ Development

Some additional tooling exists to record mock API response data to use for offline development and to run the app for the Cypress tests. The mock data is generated by running the server, querying all of the GraphQL endpoints and recording the responses. If any GraphQL APIs are updated or changed, this mock data needs to be updated. To update this data, run the following commands:

# If any GraphQL APIs have been added, changed, or removed:
$ yarn write:keys

# Start the server in recording mode
$ yarn recording

# Run the script to record the data
$ yarn record

# Rebuild the utils package
$ yarn utils:build

# Regenerate types
$ yarn types

# Note that if you update the client data you may have to update the client
# test snapshots, since some of the tests use this mock data.

The development can be run with the command:

# Run development mode
$ yarn dev

This runs the client app and uses the stored mock response data, which allows the client dashboard to be run without a server running. This also supports mocking the Ledger integration for testing.

📜 Internationalization

Anthem includes internationalized text versions, currently supporting Spanish, German, Korean, and Chinese (traditional and simplified). The language localization files exist in client/src/i18n/catalogs as JSON files which map the English source text to the localized translation of that text in the target language. The source definition for all of the localizations is the client/src/i18n/english.ts file, which exports a large union type of all the possible text values in the app. This allows the app to type check all text content and ensure that it has a matching source language key which maps to definition keys in the JSON translation files. This also supports interpolating dynamic values into a text string (with type-checking!), using this pattern:

// Applying this text in the app must include an address variable of type string:
["Address {{address}} copied to clipboard", { address: string }];

It's simply type safety for the internationalized translations.

However, in order to allow the app to continue to iterate features quickly, and to accommodate its largely English-speaking audience, and to deal with the slow bottleneck of manually translating text, the app allows for "untranslated" text to fallback to the English source definition. The internationalization logic exists in the i18n-utils.tsx file in the client package. The translation strategy is to accumulate text which requires a translation and then translate all such text in bulk at some point in time, rather than to block every feature change and edit which changes the text content of the app.

To update or change internationalized text in the app, the English source definition must be added or updated in the english.ts file. Then, the JSON translation files can all be automatically updated by running the command yarn i18n. This will update all of these JSON files to match the source file, and include TODO blocks for any unimplemented text, e.g.

{
  "LOGIN": "登陆",
  "Connect": "<<< TODO: Implement >>>",
  "Earn": "收益"
}

These TODO lines can then be collected for each JSON file and sent off for manual translation, and then used to update the JSON translation files when the translations are complete.

Note that for the Chinese translation we are translating the app into simplified chinese, and then using a library to convert this into traditional characters, since this conversion is usually 1:1. This may not be perfect, but it should be good enough.

📦 Docker Images

The docker image for the Anthem backend server can be found on Docker Hub. The latest release is kept up to date with the master branch of this repository.

A docker image for the frontend application will be available shortly.

📟 Kubernetes

A Kubernetes manifest file for the backend server is included in packages/server/anthem.yaml.dist.

🚚 CI/CD

Docker is used to build and test the project for CI/CD. You can find a Dockerfile and docker-compose file in the root directory, and other specific Dockerfiles as need in the individual project packages. The commands used to build these are:

# Install dependencies and build the application
$ yarn docker:build

# Run all tests (static, unit, and cypress tests)
$ yarn docker:cypress

The repo uses GitHub Actions to run CI/CD test and deployment pipelines. These pipelines are configured in the github/workflows directory. The client application is currently deployed using Netlify and the backend is deployed on Chorus infrastructure.

📝 Contributing Guidelines

We use the Gitflow Workflow for developing new features. This involves pulling the master branch, developing your fix or feature on a new branch, and then creating a pull request for your code changes. It is recommended to try to keep pull requests simple and confined to a concise set of changes to make it easy to review and merge code. Pull requests require review and all status checks (continuous integration checks, for instance) to pass before merging is allowed.

Any bug fixes, improvements, or new features are welcome. Pull requests must be reviewed and pass all project tests. If you are interested in contributing, feel free to explore the open issues or open an issue if you have an idea for an improvement or new feature.

kareemgrant / anthem