General

Syllabus NEU is an independent effort to provide 15,000+ Northeastern University (NEU) undergraduates access to a search catalog of 4,000+ previous NEU class syllabi to assist with course registration. Within a single course, the grading criteria and requirements set out by professors can vary widely, highlighting the need for students to know a class's syllabus before registering for a particular section of the course. Students can help Syllabus NEU by submitting a syllabus and its corresponding course information on Syllabus NEU's homepage for review by an administrator.

Development

Overview

This project contains the client-facing presentation code in /src/ and a back-end RESTful API concerned with exposing a HTTP interface to the front-end in a backend repository. The front-end is designed using React and TypeScript to promote an error-free, maintainable codebase with strongly-typed variables. For standardizing component styling and incorporating responsive design, Material UI was utilized with styled-components as the CSS-in-JS solution.

The back-end was designed using Express and TypeScript to handle all AWS cloud storage uploads and database queries. For storing syllabus PDFs, AWS S3 buckets are employed. The PDF's corresponding course information including fields such as course title, professor, and semester are stored in a DynamoDB table.

Workflows

As described in the introduction, students can submit a syllabus to add to Syllabus NEU's database. The process of syllabus submission is as follows:

1. The student fills out the fields in the syllabus submission form and attaches a PDF of their syllabus (skip to step 3).
2. Upon submission, the data is sent to a DynamoDB table storing pending submissions where an administrator can review and modify the submitted information and accept/decline (not yet implemented).
3. Once accepted (currently automatically accepted), the syllabus PDF is uploaded to S3 with a randomly generated key identifier. The PDF's corresponding course information is sent to a DynamoDB table with an additional key-value pair holding the randomly generated key identifier used for storing the PDF in S3.

The process that occurs when a visitor searches for a class's syllabus in the search engine is as follows:

1. React Router DOM navigates the visitor to an endpoint containing information about the semester they selected (defaults to all semesters) and the search term they inputted.
2. The search results page retrieves all data in Syllabus NEU's DynamoDB table. For each JSON object, a custom, boolean utility function is used to determine if the object matches the search term. If it does, then the S3 key identifier stored in the object is sent to the AWS S3 Request Presigner, which generates a temporary URL to provide visitors access to the syllabus PDF stored in S3. If not, then the object is filtered out.
3. The matching JSON objects with their temporary AWS S3 URLs are mapped onto the search results page.

Running The Project

This project requires NodeJS (latest version recommended). Before starting, make sure that the current working directory is the root of this project and not one directory above it (i.e. arbitrary/path/.../Syllabus-NEU). Run

npm install

to install necessary dependencies. To start the React front-end application, run

npm run dev

in a terminal from the root directory. Open up a second terminal and also run the backend repository with

npm run start

from the root directory to activate the Express back-end server.

Linting

This project uses eslint-config-airbnb-typescript and prettier for enforcing code style and formatting. For integration with git, husky is used for automating code formatting before every commit and works in tandem with commitlint to lint commit messages according to the conventional commit format. The complete list of configurable commit message rules can be found here. To get started, run the following in the root directory

npm install
npm run prepare

and download the eslint and prettier extensions for Visual Studio Code.

Miscellaneous

@startuml
package "Client Browser" {
  [React/TypeScript/MUI Front-End (/src)] as Frontend
} 

cloud AWS {
  [Node.js Express RESTful API (/backend/api/transpiled-api/main.js)] as Backend
  [DynamoDB NoSQL Database] as DB
  [AWS S3 Bucket Storage] as S3
  [S3 Request Presigner] as S3URL
} 

package "Express Server" {
  [Express/TypeScript RESTful API (/backend/main.ts)] as UncompiledBackend
}


Frontend <.d.> Backend : HTTPS (external)
Backend <.l.> DB : HTTPS (internal)
S3 <.u.> Backend : HTTPS (internal)
S3URL <.u.> Backend: HTTPS (internal)

UncompiledBackend .d.> Backend : transpiled into
@enduml