Charlie developer documentation

Charlie is built using Slack's Bolt SDK for Node.js. The app starts by configuring a Bolt "App," attaching a brain to it for ease-of-use, starting its web listener, and then starting up all of the individual bots defined in the src/scripts directory.

Nomenclature

• This wiki uses the term "bot" to refer to the modules that provide user-facing functionality to Charlie. So, for example, "QEX Expander" is a bot.
• This wiki uses the term "script" to refer to modules in the src/scripts directory that engage with the Bolt API but do not necessarily provide user-facing functionality, such as home, which handles rendering information provided by bots, but does not create any information itself.
• This wiki uses the term "utility" to refer to modules in the src/utils directory that provide functionality meant to be consumed by scripts or bots.

Development environment

Charlie is a Slack App, and for structural and policy reasons described below, it can't be fully qualified and exercised in a local development environment.

Because Slack apps work by responding to web hooks rather than setting up a persistent websocket connection, the machine where Charlie runs cannot respond to Slack events unless it is accessible on the public internet over HTTPS. GSA policy forbids our computers from doing this. As a result, it is necessary to run the app in cloud.gov to test it.

To facilitate this requirement, there is a GSA TTS Testing Slack instance available to test changes to Charlie before deploying to production. GSA TTS Testing Slack is configured to send events to a static URL running in cloud.gov space. Code can be developed locally and then pushed to cloud.gov (which in turn automatically redeploys the app). Within a few minutes, the changes will spin up and can be tested on GSA TTS Testing Slack. There is no need for any direct manipulation of Slack configuration.

Using Docker for Local Linting and Unit Testing

Make sure Docker is installed locally and the daemon is running.

Start up the container:

docker-compose up

This will get all of Charlie's dependencies installed, set up a PostgreSQL container, hook up Charlie and postgres, and start Charlie. In this configuration, Charlie is run using nodemon, so it will automatically restart if you make any code changes.

Run linter and tests:

docker-compose exec charlie npm run lint
docker-compose exec charlie npm test

tip: the above will test all unit tests across Charlie. To shorten iteration cycles, you can temporarily change a regex from the top-level file package.json (don't commit this change) to only test your code.

change this:

"test": "jest 'src/.+/?.+\\.test\\.js'",

to something like this:

"test": "jest 'src/scripts/awesomobot\\.test\\.js'",

Creating Bots

Charlie is mostly a collection of bots. Creating a bot is not particularly difficult, though making it interesting might be. For more information about how Charlie initializes and loads bots, see the Creating bots documentation.

Internal APIs

Charlie has a bunch of utilities to help make bots and scripts easier to author. See the Internal APIs documentation for more information.

Security

For documentation about the secure software development practices used for Charlie, please see the NIST 800-218 documentation.