Skip to content

Latest commit

 

History

History
136 lines (94 loc) · 6.06 KB

TECHNICAL.md

File metadata and controls

136 lines (94 loc) · 6.06 KB

Repository Technical Specs

These specifications describe technical aspects about this app. In particular, they discuss how the repository is organized, technical standards, etc.

Technical overview

This app is built using a MERN stack: Express.js on Node.js, MongoDB (via Mongoose), and React.

We are running our apps on Google Cloud Platform, using Google App Engine. Builds and pull requests are tested and deployed via Travis.

Some technical comments

  • This project is open to people from a variety of technical levels! So don't be afraid to try to contribute and, if you have questions, ask for help. (Also, React is not as complicated as it might seem at first!)

Notes for non-experts

  • .jsx are just javascript files which also allow React components (things that look like -- but are not quite -- standard html). If you know javascript, you should be able to understand them!

  • Javascript is fairly straightforward syntactically. However, one of the trickiest parts is that it is run typically asynchronously, which can be confusing. Understanding that makes a big difference in being able to read and write javascript effectively.

  • To learn React, if you know javascript, I suggest you go to the Facebook documents. Start with (the tutorial)[https://facebook.github.io/react/tutorial/tutorial.html] and then do (the Quickstart)[https://facebook.github.io/react/docs/installation.html]. These give a good overview of the framework.

Repository organization

Sources

The repository organization is as follows:

├──server/                      the Express backend for serving static 
│  │                            files andservicing the API
│  ├──routes/                   API routes
│  │  ├── index.js              main routes
│  │  ├── ...
│  ├──models/                   data models for API
│  │  ├── db.js                 connect to the mongo DB
│  │  ├── ...
│  ├──controllers/              backend API 
│  │  ├── ...
│  ├──_common/                  support files used in multiple sections
│  │  ├── ...
│  ├──server.js                 starting point for backend
│  ├──config-server.json        server config file; see below
├──src/                         client files for React
│  ├──App.jsx                   client starting point
│  ├──credentials-client.jsx    hold client credentials
│  ├── ...
├──static/                      static files
│  ├──index.html                shell for the client for React
│  ├── ...
├──scripts/                     scripts run separately from server process
│  ├── ...

Production server

On the production server (or if npm run compile, npm run compile-server are run), the following additional files are generated by compiling the source:

├── dist/                 transpiled version of server/ from running babel
│   ├── ...
├── static/
│   ├── app.bundle.js     compiled client code from src
│   ├── vendor.bundle.js  compiled client code from node_modules

Conventions

REST API structure

  • For rest API endpoints, use spinal case, i.e. "this-style", not "thisStyle" or "this_style".

Javascript

  • Use ES2015 syntax on both the server and client-side (including modules). Babel will be used to transpile code for wider compatibility with older browsers.

React

  • React component class should be their own files

JSON

We will (tentatively) follow the Google JSON Style Guide.

Linting

The code is linted via ESLint to follow the Airbnb javascript guide. For contributors: running eslint (after you have run npm install in the main directory to install dependencies) is as easy as running npm run lint in the main directory.

Development

To develop the code base, do the following:

  • Install mongodb.

  • Follow these Github instructions to fork this repo to your account

  • In the repo directory, install the dependencies by running $ npm install

  • Set up configuration variables

  • Copy server/credentials-template.js to server/credentials.js and edit it. For example, try changing 'mongodb://' to 'mongodb://localhost/atibroadcastapp'.

  • Start the app via:

    $ npm run dev-all

The app should automatically detect changes to your code and recompile. The app will listen on port 8000.

Configuration variables

The following configuration variables are recognized:

variable name (R)equired or default description
port 8080 port on which server will be run
fb_appsecretid R Facebook App secret
fb_broadcastuserid R Facebook broadcast user ID
mongo_connectionstring R connection string for mongo
cookiesecret R salt for cookies (currently unused)

Note that all variables are lowercase.

Because it is easiest to store configuration variables in different places in different environments, configuration variables are checked for in several places in the following order:

  1. As argument (e.g. node dist/server.js --port 40 --fb_appsecretid fjlj34)
  2. As an environmental variable
  3. From the file server/credentials-secret.json
  4. From Google App Engine project metadata (if being run on Google App Engine)

Explanation of database collections

Admin (settings)

This collection hold settings for the Admin user. Each document must have a name, holding the setting's name, and then the other fields differ per setting and indicate the setting's values.

accessToken The Facebook access token for the broadcast user.

field name type description
token string The access token
expiryDate date the token's expiration date