Design Document

Structure of our codebase

• admin/ folder: It contains an admin control panel app designed for admin usage only.
• admin-scripts folder: Some automated scripts that will be eventually integrated in the admin control panel to be run periodically and automatically.
• course-info/ folder: It contains scripts to fetch all the exam and course information from Cornell websites.
• docs/ folder: It is the place where we document important design decisions.
• frontend/ folder: It contains all of our frontend code.

Architecture Overview

Unlike traditional web applications that have a clearly defined frontend or backend boundary, the Samwise team uses the serverless approach. Since Samwise's backend logic is very simple, we can rely on Firebase's Auth and Database to handle the backend logic. In case the app requires more complicated logic in the future, we can always use Firebase functions to address the deficiencies in Firebase's config.

In the current version of Samwise, we use Firebase Auth to authenticate users and Firestore to store user information. Security is enforced by Firestore Security Rules and the config is store here. We adopted Firebase to satisfy our need for an efficient and correct realtime data syncing system.

Our frontend subscribes from firestore to ensure we have the latest data. The workflow will be introduced in the next section.

We also use Firebase Functions to post-process many Firestore operations. Currently, we only use Firebase functions for analytics.

Frontend Overview

The frontend workflow can be summarized with the following ASCII art:

     <------------ <------------ <---------------
     |                                          |
     |   (Supported by Firebase Auth)           |
     |      |                                   |
     \/     \/                                  |
[LoginBarrier] ------> (user not logged in) ----
    |
    | (when user logged in)
    |
    \/
(Initialize Firebase Listeners to create the following cycle)

[Firestore Listeners] <------ (automatically notify) <----- Firestore
   |                                                           /\
   | (push changes to)                                         |
   |                          (add/update/delete documents in) |
   \/                                                          |
[Redux Store]                                      [Our Various Firestore Actions]
   |                                                           /\
   | (push changes to)                                 (calls) |
   |                                                           |
   -----------> [Our Various React Components] -------> ------->

Firestore & Redux Store Overview

You can see the type definition of Firestore here and type definition of redux store here.

We have our Firestore and Redux Store to have almost the same shape. In this way, we can speed up our development process by making as less data conversion as possible. We only have some slight shape different when we absolutely need them.

Firebase Functions Overview

We use Firebase functions to perform some non-urgent tasks, such as gathering some analytics stats when the users do something in our app. We subscribe to those Firestore events emitted inside Google Cloud.

Note that there may be a few seconds of delay before Firebase functions can handle the request. However, this is not a problem since no user actions will be blocked by this event handling.

Admin Overview

Currently, the admin control panel only fetches analytics data from the database, performs some computation, and displays to the admin. It can only be run locally with an admin credential.

The admin scripts contain some scripts that will eventually be integrated into the admin app to provide secure and easy access to sensitive data.