Skip to content
Permalink
Browse files

Update ReadMe to include Modules instead of Tech Stack

  • Loading branch information
kevinsuh committed Sep 21, 2016
1 parent b8f19e1 commit 632333bec52c497bb88450ad250603e33e8f8682
Showing with 48 additions and 64 deletions.
  1. +47 −63 README.md
  2. +1 −1 package.json
110 README.md
@@ -10,7 +10,7 @@ Toki is written in Javascript and uses the excellent [Botkit](https://github.com


- [Main Features](#main-features)
- [Technology Stack](#technology-stack)
- [Modules](#modules)
- [Directory Structure](#directory-structure)
- [Running on Development](#running-development)
- [Running on Production](#running-production)
@@ -20,127 +20,111 @@ Toki is written in Javascript and uses the excellent [Botkit](https://github.com

<a name="main-features"/>
# Main Features
#### Focus sessions
### Focus sessions
<img src="/build/public/images/focus_example.png" width="60%" alt="Focus sessions">
* `/focus [task] for [time]`
* Turns on your DND in Slack while in "focus" mode
* Shares what you are working on to your team
* Toki stores this information for daily / weekly reflection
* You can end your session at any point, which turns off your DND (via interactive button, or `/end`)

#### View your team's pulse
### View your team's pulse
<img src="/build/public/images/pulse_example.png" width="60%" alt="Team Pulse">
* Toki will dynamically update its channels whenever one of the channel members enters a focus session
* This allows you to create information channels (i.e. `#pulse-backend`) and get a snapshot of what teams are focused on
* You are able to send notifications through each teammate's `Collaborate Now` button, where Toki sends a ping through to the focusing user and starts a conversation
* See what an individual is up to with `/pulse @user`

#### Daily Reflection
### Daily Reflection
<img src="/build/public/images/reflection_example.png" width="60%" alt="Daily Reflection">
* Toki provides you with a daily cadence of how you spent your time
* This helps build a habit of intentionality with your time, and see pictures of what you got done each day and week

<a name="technology-stack"/>
# Technology Stack

#### Web Server
* Digital Ocean
* PostgreSQL
* Node.js
* ExpressJS
* HTML / SCSS / jQuery

#### Slack Bot
* Node.js
* Botkit
* Wit.ai

#### Libraries/Dependencies
* Babel (ES6)
* node-sass (SCSS)
* Sequelize
* Moment-Timezone
* EmbeddedJS
* Cron
```
Note: Toki has a web-app interface in its product roadmap and thus comes with the foundation for one using Express and EJS. There is no front-end framework (React or Angular) configured yet, but one would be instealled in the `/app` directory, which also holds an `/api` folder for RESTful calls.
```




<a name="modules"/>
# Modules

Toki, a node.js bot using the [Botkit](https://github.com/howdyai/botkit) framework, uses the following modules:
* [cron](https://github.com/ncb000gt/node-cron): Allows you to run a cronjob
* [botkit-middleware-witai](https://github.com/kevinsuh/botkit-middleware-witai): Forked version of Botkit's official middleware integration of Wit.ai
* [ejs](https://github.com/tj/ejs): Write embedded javascript templates for your views
* [lodash](https://github.com/lodash/lodash): A powerful javascript utility library for arrays, objects, numbers, and more
* [moment-timezone](https://github.com/moment/moment-timezone): For dealing with dates and timezones for your Slack users
* [sequelize](https://github.com/sequelize/sequelize): Promise-based Node ORM, which we use for Postgres
* [nlp_compromise](https://github.com/nlp-compromise/nlp_compromise): A javascript utility library for natural language
* [babel](https://github.com/babel/babel): Compiler that transforms ES6 into javascript that can run in any browser
* [node-sass](https://github.com/sass/node-sass): Compilers for .scss files to css
* [dotenv](https://github.com/motdotla/dotenv): Allows you to load environment variables from a `.env` file

<a name="directory-structure">
# Directory Structure
Since Toki uses a compiler for both ES6 ([Babel](https://babeljs.io/)) and SCSS ([node-sass](https://github.com/sass/node-sass)), we have one directory for our source code `/src`, and one directory for our deployment `/build`.

Code that does not need to be compiled is held outside of the `/build` and `/src` directories and and at the root-level of our project. Currently, outside of our various config files, that only includes our `/views`.

Since the `/build` directory is a compiled version of our `/src` directory, the structure within each _should be_ the exact same. The one exception to this is `/build/public`, which is where our assets are held. They are held here because we are using the `/build` directory for deployment
**Notes:**
* 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 assets are held in `/build/public` since we use the `/build` directory for deployment

**The following is the structure of the `/build` directory** _(excluding end files in nested directories)_:
**This is the overall structure of Toki**:
```
build/
├── app/ // Express web server
│ ├── api/
│ │ ├── v1/ // RESTful API endpoints
│ ├── api/ // RESTful API endpoints
│ ├── migrations/ // Sequelize DB migrations
│ ├── models/ // Sequelize Models
│ ├── router/ // Express routes
│ │ │ ├── routes/
│ ├── cron.js/ // Cron job functions
│ ├── scripts.js/ // One-off scripts
| ├── globalHelpers.js/ // App-wide helpers (i.e. prototype methods)
├── bot/ // Slackbot
│ ├── actions/ // Proactive actions
│ ├── controllers/ // Botkit controllers to handle Slack events and conversations
│ │ │ ├── buttons/
│ │ │ ├── dashboard/
│ │ │ ├── misc/
│ │ │ ├── notWit/
│ │ │ ├── pings/
│ │ │ ├── sessions/
│ │ │ ├── slash/
│ ├── lib/ // Slackbot helpers
│ ├── middleware/ // Botkit middleware functions
├── public/ // Assets
│ ├── css/
│ ├── gifs/
│ ├── images/
│ ├── js/
├── public/ // Static assets
├── server.js/ // Our starting point
```

**Notes:**
* There are two main sub-directores: `app` and `bot`. The `app` directory is for our Express web server. The `bot` directory is for Toki's existence in slack.
* `app` holds our Express web server, including routes, models that link up to our DB tables, and our API calls
* `bot` holds the functionality needed for our conversation in slack
* There are two main sub-directores: `app` and `bot`
* `app` is for our Express web application, 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 we proactively reach out, such as when user first signs in with our slack button
* `lib` holds various helper functions
* `actions` are when Toki proactively reaches out
* `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 ExpressJS app is created, and where our various bots are turned on to listen to [Slack RTM](https://api.slack.com/rtm)
* `server.js` is where our ExpressJS app is created, and where Toki's installed bots are turned on to listen to [Slack RTM](https://api.slack.com/rtm)


<a name="running-development"/>
## Running on Development
Toki makes use of compilers for ES6 ([Babel](https://babeljs.io/)) and SCSS ([node-sass](https://github.com/sass/node-sass)) to be translated into ES5 and CSS, respectively.

`npm run compile` is an NPM script that runs babel, node-sass, and sequelize db:migrate to convert changes. Toki also comes with the scripts `npm run watch-css` and `npm run watch-babel` to run in the background and compile a file everytime you save changes in `/src` to `/build`
Notes:
* `npm run compile` is an NPM script that runs babel, node-sass, and sequelize db:migrate to make changes
* Toki also comes with the scripts `npm run watch-css` and `npm run watch-babel` to run in the background and compile a file from `/src` to `build` everytime you save changes

<a name="running-production"/>
## Running on Production
To run our production server, Toki uses [pm2](https://github.com/Unitech/pm2), a production process manager for Node.js applications.

Toki use our NPM script `npm run prepare-production` to run a sequelize migrate and reset of our pm2 server. There may be occasions where you want to `npm update` on remote too, if one of our primary libraries goes through a massive update (this will happen to botkit, wit, botkit-kit-middleware, etc.). *Note: currently this repo uses Toki's forked version of botkit-middleware-witai for custom configuration*
For production, Toki uses Digital Ocean and [pm2](https://github.com/Unitech/pm2), a production process manager for Node.js applications.
*This project uses a forked version of botkit-middleware-witai for custom configuration*

Notes:
* both development and production use environment variables
* dev_toki is used for development purposes
* dotenv picks up whether there is `NODE_ENV`. If no `NODE_ENV`, will default to `development`
* Development environment triggers dev_toki and local postgres DB
* Production server holds some env variables through SHELL, and some through .env file. DB_HOST is absolutely necessary to be updated on shell
* Toki comes with a production bot and development bot by default
* dev_toki is used for development purposes
* Development environment triggers dev_toki and local postgres DB
* dotenv picks up whether there is `NODE_ENV` environment variable. If no `NODE_ENV`, will default to `development`. Please specify `NODE_ENV=production` on your prodution server
* Production server holds some env variables through SHELL, and some through .env file. DB_HOST is necessary to be updated on shell

<a name="product-roadmap"/>
## Product Roadmap
Our ideas for the product roadmap are held in our [public Trello board](https://trello.com/b/AYIEVUsN/product-development-roadmap). We'd love to hear suggestions, and work together towards a better future! You can add comments directly in Trello.

<a name="authors"/>
## Authors
[Kevin Suh](https://github.com/kevinsuh) ([@kevinsuh34](https://twitter.com/kevinsuh34)) is a co-founder and the primary developer for Toki. For inquiries, reach out at [kevinsuh34@gmail.com](https://mail.google.com/a/?view=cm&fs=1&to=kevinsuh34@gmail.com). For issues related specifically to Toki's codebase, please post on our [issues](https://github.com/kevinsuh/toki/issues) page.
[Kevin Suh](https://github.com/kevinsuh) ([@kevinsuh34](https://twitter.com/kevinsuh34)) is the primary developer for Toki. Additional help from [Chip Koziara](https://github.com/chipkoziara) ([@chipkoziara](https://twitter.com/chipkoziara). For inquiries, reach out at [kevinsuh34@gmail.com](https://mail.google.com/a/?view=cm&fs=1&to=kevinsuh34@gmail.com). For issues related specifically to Toki's codebase, please post on our [issues](https://github.com/kevinsuh/toki/issues) page.



@@ -28,7 +28,7 @@
"bluebird": "^3.4.5",
"body-parser": "^1.15.1",
"bootstrap": "^3.3.6",
"botkit": "https://github.com/kevinsuh/botkit.git",
"botkit": "^0.2.2",
"botkit-middleware-witai": "https://github.com/kevinsuh/botkit-middleware-witai.git",
"cron": "^1.1.0",
"dotenv": "^2.0.0",

0 comments on commit 632333b

Please sign in to comment.
You can’t perform that action at this time.