From 57adfc6b65959aafa402c65e8bbd8c2f7a07bf98 Mon Sep 17 00:00:00 2001 From: Patrick Pan Date: Mon, 11 Dec 2017 09:32:16 -0500 Subject: [PATCH 1/5] readme --- README.md | 98 ++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 94 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 571e84a..115fb28 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,99 @@ -# textroulette -CS96 Dev Team first project -- a text-based communication tool, driven by Node.js +# Eye to Eye +Eye to Eye is a nonpartisan web application that enables you to have face-to-face conversations with strangers who have different views from your own. -*This repo autodeploys to https://cs96.tk* +# Table of Contents + +1. [Getting Started](#getting-started) +2. [Technical Documentation](#technical-documentation) + * [Technical Overview](#technical-overview) + * [Configuration](#configuration) + * [Database](#database) + * [Routes](#routes) + * [Views](#views) + * [Controllers](#controllers) + * [Matcher](#matcher) + * [Socket Logic](#socket-logic) + * [Static Assets](#static-assets) +3. [About](#about) + +# Getting Started Before running, please ensure that you have a `.env` file in the root directory in the format `KEY=VALUE`, one per line. `.env` should contain the following keys: * DB_URI: an complete MongoDB connection URI -* FB_ID: `1820618154618978` (only usable for localhost:3000) or your own FB app ID +* FB_ID: a valid Facebook Developer App ID +* FB_SECRET: a valid Facebook Developer App Secret +* FB_CALLBACK: by default, `http://localhost:3000/auth/facebook/callback`; you should change the host and port of `FB_CALLBACK` according to the deployment configuration. + +Then, run `npm install`. Finally, run `npm start`. + +To run on a port other than `3000`, chaneg the `PORT` and `FB_CALLBACK`environment variables as well as the configuration in Facebook Developer. + +# Technical Documentation + +## Technical Overview + +Eye to Eye is powered by a *node.js + express* backend. Pages are rendered server-side using the *Handlebars* templating engine. *Socket.io*, a wrapper around the *WebSocket* protocol, is used for bidirectional communication between server and client. The client side uses *Bootstrap* and *jQuery* for styling and interactivity and, following a handshake using *Socket.io*, clients initiate video chat using *WebRTC*, facilitated by *SimpleWebRTC* and *Xirsys* STUN servers. *tracking.js* is additionally used during video chat for facial masking. Data is stored using *MongoDB*. + +Eye to Eye's main exectuable is `/server.js`, which: +* loads configurations from `/config` and `/.env` +* connects to MongoDB with *mongoose* and models in `/db` +* configures an *express* app using routing logic in `/routes` powered by logic in `/controllers` and rendering views in `/views` +* instantiates the matcher engine in `/matcher.js` +* initializes WebSocket communication from `/sockets.js` +* serves static resources from `/static` + +Finally, in auto-deployment, shell scripts in `/scripts` are used to start/restart/stop the server using *nginx* and *pm2*. + +## Configuration + +Node packages *dotenv* and *getconfig* are used for configuration. *getconfig* uses JSON to store configuration and *dotenv* uses key-value pairs. Data stored in `/config/default.json` +is inevitably passed to the client side and is thus not secret, meaning that it can be safely committed. Data stored in `/.env` is not committed because it contains sensitive API keys. + +## Database + +The server connects to MongoDB by requiring `/db/connect.js`, which initializes a connection to the instance the `DB_URI` from `/.env`. `/db/connect.js` also exports models from `/db/models/`. + +## Routes + +Most routes are contained in `/routes/main.js`. Routes often use the `isLoggedIn` function to ensure that users are authenticated and redirecting them to `/` otherwise. Authentication is powered by *passport.js* and relevant data is stored in `req.user` after successful authentication. + +Routes that render *Handlebars* views in `/views` pass the data returned by the `getAuthInfo` function to the frontend, which allows the frontend to access user account data. API routes are powered by controllers in `/controllers`. + +## Views + +Views are contained in `/views` and are powered by Handlebars. Similar to PHP, Handlebars is a superset of HTML syntax that allows accessing JSON-formatted variables with `{{{variable}}}`. All views begin with the `/views/layouts/main.handlebars` layout and may utilize the partial views in `/views/partials`. HTML elements in views generally are styled using *Bootstrap* classes, while *jQuery* is used for interactivity. The view */views/video.handlebars* extensively utilizes *Socket.io* and *SimpleWebRTC* to communicate with the server for pairing and disconnection. + +During video chat, *SimpleWebRTC* uses an existing *