Awesome

Toki: deep work for collaborative teams

Toki is a Slack bot that helps individuals focus at work, track their productivity and stay in sync with their team. Its goal is to empower deep work for teams, through the benefits of Slack (collaboration, transparency and fun).

Toki enables you to /focus on [task] for [time]. This command turns on your Do Not Disturb (DND) mode in Slack and shares what you're working on to your team. You can see what teammates are focused on by checking /pulse @user. Toki will also store these focused sessions to provide daily reflections of how you spend your time. Think of /focus as an upgrade to /dnd that makes deep work more collaborative, transparent and informative.

Toki is written in Javascript and uses the excellent Botkit and Wit libraries. The Botkit + Express integration is inspired from this tutorial. If you are looking for a foundation to build your own Slack bot app with Botkit and Express, check out that tutorial.

• Main Features
• Directory Structure
• Getting Started
• Modules
• Development
• Running on Production
• Product Roadmap
• Authors

View your team's pulse

Send appropriate notifications

Daily Reflection

Note: Toki has a web app interface in its roadmap. We plan this to be a React + Redux frontend hosted on a separate server that speaks to the API end points on this server in /app/api.

Notes:

• There are two main sub-directores: app and bot
  • app is for our Express web server, including routes, models that link up to our DB tables, and our API calls
  • bot holds the functionality for Toki's existence in slack
    • controllers are used to respond to user events, and engage them in conversation
    • actions are when Toki proactively reaches out
• Since Toki uses a compiler for both ES6 (Babel) and SCSS (node-sass), we have one directory for our source code /src, and one directory for our deployment /build.
  • This means actual development is done in /src directory, which Babel uses to compile into the /build directory for deployment
  • Code that does need to be compiled is held at the root-level of our project. Currently, this only includes config files and our /views directory
    • Our static assets are held in /build/public
• cron.js is used for our focus sessions and daily reflections. It holds various functions that get run every 5 seconds (configured in server.js)
• server.js is where our Express server is created, and where Toki's installed bots are turned on to listen via Slack RTM

By default, Toki comes with configuration for a development bot and a production bot so that you can continue developing your bot and test new functionalities while it is live and on others' teams. This means you will have to create two separate Slack apps and do basic configuration for each. Here are the steps:

1. Create your two slack apps (one for development and one for production)
2. Set up your environment variables. You can modify and rename the provided .env-example file:

SLACK_ID=your.productionSlackId
SLACK_SECRET=yourProductionSlackSecret
SLACK_REDIRECT=https://yourproduction.site

DEV_SLACK_ID=your.developmentSlackId
DEV_SLACK_SECRET=yourDevelopmentSlackSecret
DEV_SLACK_REDIRECT=http://localhost:8080/

VERIFICATION_TOKEN=yourVerificationToken

WIT_TOKEN=yourWitToken
HTTP_PORT=8080

Make sure to put NODE_ENV=production as an environment variable on your production server. This allows Toki to know whether to start up the production bot or the development bot 3. Get your apps' verification tokens for Slash commands 4. Create a Wit.api app and set your wit token

• Wit token is located in settings of your Wit app under Server Access Token

5. Decide deployment strategy

• We used Digital Ocean for deployment
  • Configure environment variables while SSH'd into the server. This is done by creating this same .env file on the server, but you must also configure DB_HOST in shell to connect to your prodution postgres DB
• For Heroku, you can use the Heroku dashboard to add these environment variables

6. We use Postgres for storage with the Sequelize ORM

• Familiarize yourself with Sequelize and configure accordingly in config.json
• You will notice that for "production", we just look at DB_HOST. This is the connection uri to your production DB. An example format is postgresql://user:password@example.com:5432/dbname

Toki is built on top of the Botkit framework and uses the following modules:

• cron: Allows you to run a cronjob
• botkit-middleware-witai: Forked version of Botkit's official middleware integration of Wit.ai
• ejs: Write embedded javascript templates for your views
• lodash: A powerful javascript utility library for arrays, objects, numbers, and more
• moment-timezone: For dealing with dates and timezones for your Slack users
• sequelize: Promise-based Node ORM, which we use for Postgres
• nlp_compromise: A javascript utility library for natural language
• babel: Compiler that transforms ES6 into javascript that can run in any browser
• node-sass: Compilers for .scss files to css
• dotenv: Allows you to load environment variables from a .env file

Actual development is done inside the /src directory, and its changes are compiled into the /build directory via babel and node-sass for deployment. This allows us to use ES6 and SCSS while developing.

Toki comes with the scripts npm run watch-css and npm run watch-babel to run in the background and compile a file from /src into its mirror location in /build each time you save a change.

Notes:

• Toki comes with a production bot and development bot by default
  • Development environment triggers dev_toki and local postgres DB
  • Production environment is identified via environment variable NODE_ENV=production. Otherwise, it's assumed you are in development. Specify NODE_ENV=production on your prodution server
• This project uses a forked version of botkit-middleware-witai for custom configuration
• Production server holds some env variables through shell, and some through .env file. DB_HOST is necessary to be updated on shell