The TAMS Club Calendar is a fully contained event tracker, club/volunteering database, and general resource center. This is the unofficial club event calendar for the Texas Academy of Mathematics and Science (TAMS) student organizations!

Contribution

There is a page for instructions on how to contribute. You can look through the issues, comment on the ones you like, and make a pull request to resolve them :D We also welcome any bug reports or feature requests ➔ create a new issue!

We also have a publically viewable Trello board for our backlogged issues. To edit this board, you must be added as a contributor (please contact Michael Zhao).

Documentation

General documentation for the frontend can be found on our autogenerated documentation site. The docs site simply contains a large list of types and functions that are used throughout the client code.

Setup

To download the repository locally:

git clone https://github.com/MichaelZhao21/tams-club-cal.git
cd tams-club-cal && yarn install

It is assumed that you have node installed on your system. If not, follow the instructions on the Node.js website. You also need yarn installed locally as this is the main package manager (and imo better than npm) that we use. If you do not have this already installed, please follow the installation instructions on the Yarn website.

If you would like to help develop the backend, email or message MichaelZhao21 to get access to the database and other resources. If you are just developing frontend, you can simply use https://dev.tams.club as the backend server (skip to Execution and Deployment). You will not need to do the following steps if you are only developing frontend.

Create the environmental variable file at server/.env:

MONGO_USER="[Username for cluster]"
MONGO_PASS="[Password for cluster]"
MONGO_URL="[Connection URL to the mongodb cluster (eg. "tams-cal-db-staging.7d0nz.mongodb.net")]"

G_CLIENT_ID="[Google API OAuth 2.0 Client ID]"
G_CLIENT_SECRET="[Google API OAuth 2.0 Client Secret]"
SERVICE_EMAIL="[Google Cloud service account email]"
SERVICE_PRIVATE_KEY="[Google Cloud service account private key]"
CALENDAR_ID="[ID for Google Calendar for syncing]"

AWS_ACCESS_ID="[AWS IAM User Access Key ID]"
AWS_SECRET_KEY="[AWS IAM User Secret Key]"

ORIGIN="[(optional) Origin requests are sent from. This is needed for google login -- thus, login will not work for local development]"
NO_ORIGIN_CHECK="[(optional) If true, all requests not from ORIGIN will be *denied with a 403 error*]"
STAGING="[(optional) On dev.tams.club, this value needs to be true to upload files to the correct bucket due to docker running in production]"
PORT="[(optional) The port to start the server on - DEPLOYMENTS SHOULD BE PORT 80 due to docker port mapping]"

External Resources (Backend)

As mentioned above, please contact MichaelZhao21 for credentials if you would like to help develop the backend as it will probably be easier than setting everything up manually. That said, if you want a your own resources, go right ahead:

1. The first thing you will need is a Mongodb Atlas Cluster. A free tier instance should be good enough. If you decide to opt for a local instance, make sure to use that username/password and url instead
2. Next, you need an AWS account to set up an S3 bucket and connect that to a CloudFront CDN. Then, create an IAM user and allow access to S3 management. Put that user's access key ID and secret in the .env file
3. Additionally, you need to make a Google Cloud Developer Account, create a project, and make both OAuth 2.0 Client credentials and a service account credentials, enabling the Google Calendar API and Login with Google API. The Oauth2 credentials and the service account email/private key should be placed in the .env file
4. Finally, you will need to create a new Google Calendar, share it with the service account email, and add the id and url to the .env file

Execution and Deployment

To develop the frontend without a local backend, run yarn dev:staging, which will use the local frontend with http://dev.tams.club as the backend.

If you would like to host a local backend, run yarn dev and yarn backend in 2 different consoles. The first will start the frontend and the second will start the backend. To do this, you must have all the required environmental variables! Additionally, if you would like to utilize hot reloading for the backend, you may also use yarn backend:dev, which uses nodemon to watch for changes and reload.

To build the Docker image, simply run yarn docker. You must have all of the environemntal variables defined for the backend as well to run this command or the app will not work correctly. The port of the client app will be 80, but make sure to set the port of the server app to something other than 80 in the .env file or it will not work properly. The instructions on how to install and run docker containers is out of the scope of this document, but feel free to look it up on the Docker website. Unfortunately the build scripts will not work outside of the Docker environment, so running those will probably result in errors.

To perform typechecking, run yarn type for the client/ directory and yarn type:server for the server/ directory. This will simply run tsc --noEmit for each one of the client and server folders.

To generate documentation, run the yarn docs command. This run the typedoc compiler and create the HTML output in a new docs/ directory. Simply navigate to index.html in a web browser to see the autogenerated docs site. There is a workflow that will automatically run this whenever a push is made to the master branch, so you do not need to worry about updating it. All documentation is generated from typescript comments, so make sure to keep those updated!

Commands Summary

yarn dev - Runs frontend server (requires local backend)
yarn dev:staging - Runs frontend server (uses dev.tams.club = staging backend)
yarn backend - Runs backend server
yarn backend:dev - Runs backend server that watches for changes
yarn docker - Performs a docker build based on the Dockerfile
yarn type - Typechecks the client directory
yarn type:server - Typechecks the server directory
yarn docs - Generates the documentation in the docs directory using typedoc
yarn format - Formats all ts, tsx, and json code files and WRITES CHANGES TO THE FILES