Skip to content

Latest commit

 

History

History
189 lines (145 loc) · 9.73 KB

readme.md

File metadata and controls

189 lines (145 loc) · 9.73 KB
Raw

Sources

Travis CI Codecov Dependencies Dev dependencies code style: prettier tested with jest license

A website the Daily Bruin uses to keep track of all of our sources. It's powered by an Express server with a PostgreSQL backend and a GraphQL endpoint, and uses React on the frontend.

The production version is only available to Daily Bruin members.

Technologies Used

Below is a non-exhaustive list of some of the more major technologies used by Sources and the reasoning why these technologies were chosen. This list is meant to give you a starting point for considering adding or changing the technologies used by Sources or other projects and should change over time as needs and technologies change.

General

  • TypeScript is a language developed by Microsoft. It's like JavaScript with types!
  • Jest is testing framework.
  • Prettier is an code formatter that makes sure all our code looks pretty!

Frontend

  • React is a popular JavaScript library for building user interfaces.
  • Parcel is an application bundler focused on simplicity and speed. It's very new and currently has a lot of bugs and limitations but shows a lot of promise and is much easier to use than alternatives such as Webpack.
  • Apollo Client is a popular GraphQL client that works very nicely with React.
  • react-table is a small and extensible component for displaying data (in our case, all of the Sources). It was selected because it's popular and had all the features we need. A potential alternative that was considered was react-data-grid, but we liked the lightweightness and styling of react-table better.
  • react-contextmenu is a simple popup context menu used to display options to edit and delete sources. We actually started by using react-contextify, but switched to react-contextmenu as it was more popular and appeared to be more actively developed.
  • react-modal is a simple modal component used to display the "Add" and "Edit" modals. A couple of modal components were considered, but react-modal seemed to be the least opinionated and did not come bundled as part of a larger library, such as react-bootstrap.

Backend

  • Node almost needs no introduction. A JavaScript runtime for servers.
  • Express is the most popular web framework for Node.
  • Google APIs Node.js Client are used to authenticated users via Google Oauth 2.
  • Apollo Server is a popular serverside package for creating a server that supports GraphQL queries.
  • Sequelize is an ORM (Object-Relation Mapping) library for SQL in JavaScript. Essentially, it allows us to represent our database in JavaScript. Pretty nifty!

Services Used

In addition to the technologies used about, Sources has a few services integrated with the repository to make maintenance and development easier. They are:

Structure

.
├── LICENSE
├── bin
│   └── www                     # The file the actually runs the node server.
├── coverage/                   # Folder generated by Jest for use with CodeCov.
├── dependencies.yml            # File used by dependencies.io.
├── designs/                    # Design documents and mockups
│   ├── flowcharts
│   ├── flowcharts.sketch
│   ├── mockups
│   ├── mockups.sketch
│   ├── site-flow.png
│   └── spec.md
├── dist/                       # Autogenerated folder where compiled TypeScript (i.e., JavaScript) code is.
├── package.json                # Project and Dependency metadata
├── readme.md                   # This readme!
├── scripts/                    #
│   └── create-data.ts
├── src
│   ├── app.ts                  # The main Express server.
│   ├── controllers             # Where controllers go
│   ├── errorHandling.ts        # Code for server error handling (e.g., 404, 500, etc.)
│   ├── models/                 # Where models are stored
│   ├── routes/                 # Routing logic goes here. Contains URL endpoints as well as GraphQL schemas.
│   └── views/                  # Where views are stored
├── tsconfig.json
├── tsconfig.server.json
├── tsconfig.test.json
├── tslint.json                 # TSLint configuration.
└── yarn.lock                   # Autogenerated file by Yarn.

Sources follows an MVC pattern.

The models are defined through Sequelize and stored in the models folder, along with some general database configuration. Currently there's only one model, Source.

Controllers are stored in the controllers folder. There are 2 controllers, authController and sourceController that take care of Google Oauth authentication and interfacing with the Source model respectively.

Frontend files are stored in the views folder. This includes both the login and main pages (login.html and index.html respectively) as well as React components (in the components/ directory).

Note that test files are put in the same directory as the respective file they test and have the extension .test.ts.

Contributing to Sources

Prerequisites

There are a couple of programs and files Sources depends on that you'll need to have installed to run it locally.

  1. Node – You can install this with a simple brew install node on macOS.
  2. Yarn – Yarn is a JavaScript package manager, and an alternative to npm. We prefer it to npm because it has a couple of nice features such as caching, lockfiles, and faster downloads.
  3. Visual Studio Code – VS Code is an open source text editor built by Microsoft and has amazing tooling support for TypeScript projects (as well as a lot of other awesome features!). You can use any text editor you want, but VS Code will give you a nice experience :).
  4. PostgreSQL – Postgres is the database we use. Installing it locally can be a little daunting, so check out our guide below if you're unfamiliar with it!
  5. A .env file – It's good practice to store things like API keys and database information with environment variables so that they can easily be changed for different environments without code changes. This is cool, but when you have a lot of configuration variables it can become hard to manage, so we use a package called dotenv that reads configuration data from a file called .env and puts them into process.env. Check out our guide below for an example .env.

Installing PostgreSQL

Mac

You want to install Postgres through Homebrew.

brew install postgres

Then start Postgres with the command:

brew services start postgresql

Awesome! For reference, you can stop postgres at any time with berw services stop postgresql. You don't want to do that right now, though! Instead, you'll want to create Sources' database. We call ours sources.

createdb sources

You'll also want to create a dummy database used for testing. It's called sources-test.

createdb sources

Note that by default, the Postgres user is your computer's username and there is no password. When creating your .env file, the values will look something like:

DATABASE_HOST=localhost
DATABASE_USER=nathan
DATABASE_PASSWORD=
...
(other values)
...

Dope. Now you'll want to just create some data with yarn create-data and you're ready to go!

For development, you may also find it useful to use a GUI client to visualize the database. There a lot of great options, but we recommend PSequel!

Windows

We're working on this! If you know how to install Postgres on Windows, please make a pull request!

Example .env File

If you're making your own, the values you'll want are:

DATABASE_HOST=
DATABASE_USER=
DATABASE_PASSWORD=
G_CLIENT_ID=
G_CLIENT_SECRET=