BFF

The BFF (backend for frontend) is the backend API that powers the GDS UI at vaspdirectory.net. The GDS UI is intended to give users a single access portal to both the MainNet and TestNet as well as to support non-GDS features like collaborators and TRISA Service Providers. Because of this it sits in the middle of multiple services, including both the MainNet and TestNet GDS services and multiple data sources. Its environment variables are all prefixed with the GDS_BFF_ tag. The primary configuration is as follows:

User Cache Config

The BFF interacts with Auth0 to fetch data about users. To reduce the number of Auth0 network lookups an expiring LRU cache is used to store user information for a fixed amount of time while bounding the amount of space used by the cache. The configuration for the user cache is as follows:

Auth0 Config

The BFF uses Auth0 for authentication and authorization and must connect to the Auth0 Management API in order to manage users. The Auth0 client is configured as follows:

Network Configuration

The network configuration enables the BFF to connect to the GDS Database, Directory API, and Members API for both the MainNet and TestNet networks. The required configuration and configuration values is the same for both networks but the environment variables are prefixed with GDS_BFF_TESTNET_ and GDS_BFF_MAINNET_ respectively.

The configuration without the prefixes is specified below, at the end of each section, we will provide an exhaustive list of environment variables that are required to fully configure the BFF for connecting to both the TestNet and MainNet GDS services.

GDS Database Connection

The GDS Database connection is a store connection that is similar to the BFF Database connection described in the following section. Configuration for the TestNet and MainNet database connections is as follows:

Note that only a trtl:// database url should be used for network database connections and that DATABASE_REINDEX_ON_BOOT should always be false for the BFF.

List of environment variables:

• GDS_BFF_TESTNET_DATABASE_URL
• GDS_BFF_TESTNET_DATABASE_INSECURE
• GDS_BFF_TESTNET_DATABASE_CERT_PATH
• GDS_BFF_TESTNET_DATABASE_POOL_PATH
• GDS_BFF_MAINNET_DATABASE_URL
• GDS_BFF_MAINNET_DATABASE_INSECURE
• GDS_BFF_MAINNET_DATABASE_CERT_PATH
• GDS_BFF_MAINNET_DATABASE_POOL_PATH

GDS Directory API Configuration

The BFF connects to the GDS TRISA Directory API to perform operations like registration submission, contact verification, and verification status lookups. The configuration for the directory API clients is as follows:

List of environment variables:

• GDS_BFF_TESTNET_DIRECTORY_INSECURE
• GDS_BFF_TESTNET_DIRECTORY_ENDPOINT
• GDS_BFF_TESTNET_DIRECTORY_TIMEOUT
• GDS_BFF_MAINNET_DIRECTORY_INSECURE
• GDS_BFF_MAINNET_DIRECTORY_ENDPOINT
• GDS_BFF_MAINNET_DIRECTORY_TIMEOUT

GDS Members API Configuration

The BFF connects to the secure GDS Members API to give logged in users access to the complete directory including listing verified members and updating their member record. The configuration for the members API client is as follows:

List of environment variables:

• GDS_BFF_TESTNET_MEMBERS_ENDPOINT
• GDS_BFF_TESTNET_MEMBERS_TIMEOUT
• GDS_BFF_TESTNET_MEMBERS_MTLS_INSECURE
• GDS_BFF_TESTNET_MEMBERS_MTLS_CERT_PATH
• GDS_BFF_TESTNET_MEMBERS_MTLS_POOL_PATH
• GDS_BFF_MAINNET_MEMBERS_ENDPOINT
• GDS_BFF_MAINNET_MEMBERS_TIMEOUT
• GDS_BFF_MAINNET_MEMBERS_MTLS_INSECURE
• GDS_BFF_MAINNET_MEMBERS_MTLS_CERT_PATH
• GDS_BFF_MAINNET_MEMBERS_MTLS_POOL_PATH

Database

The BFF makes use of a globally replicated key-value store for persistence of BFF-specific data structures such as organizations and announcements. By default it uses the TrtlDB for this, but for testing or smaller deployments it can use a local LevelDB database instead.

Generally speaking, the BFF uses the same TrtlDB as the GDS MainNet instance, and we’ve ensured there are no namespace conflicts to prevent this. The BFF primary store can also be independent of the GDS stores if necessary.

The primary database store is configured as follows:

The GDS_BFF_DATABASE_URL is a standard DSN with a scheme, host, path, and query parameters. In the case of the BFF the scheme can be either trtl:// or leveldb://.

When connecting to a TrtlDB, the host and port need to be specified with a trailing slash, e.g. trtl://localhost:4436/. Connecting via mTLS is only relevant when connecting to a TrtlDB. If GDS_BFF_DATABASE_INSECURE is false, then the GDS_BFF_DATABASE_CERT_PATH and GDS_BFF_DATABASE_POOL_PATH are required.

When connecting to a LevelDB, the path to the directory on disk where the leveldb should be stored must be passed to the DSN. To specify a relative path, use three slashes: leveldb:///relpath/to/db, to specify an absolute path use four: leveldb:////abspath/to/db.

Email and SendGrid

The BFF uses SendGrid to send email notifications and to enable communication workflows with users and admins. Configure BFF to use SendGrid as follows:

SendGrid is considered enabled if the SendGrid API Key is set. The service and admin email addresses are required if SendGrid is enabled.

Sentry

The BFF uses Sentry to assist with error monitoring and performance tracing. Configure BFF to use Sentry as follows:

Sentry is considered enabled if a DSN is configured. Performance tracing is only enabled if Sentry is enabled and track performance is set to true. If Sentry is enabled, an environment is required, otherwise the configuration will be invalid.

Note that the sentry.Config object has a field Repanic that should not be set by the user. This field is used to manage panics in chained interceptors.