Homework 1: Building a CRUD app in Express

This assignment is due before class starts on Monday, October 9.

This assignment has three purposes:

  1. Practice good software engineering in teams. As such, You must be part of a team of 2 or 3 students. If for some reason all other students are in groups of 2 or 3, you may join a group of 4. Finding a team is your responsibility.
  2. Familiarize you with server side programming and building a basic app.
  3. Build a codebase for iterating on and improving on as the course progresses.

CRUD: Create, Retrieve, Update, Delete

An immense number of modern applications revolve around manipulating data using little more than create, retrieve, update, and delete operations. In this assignment, you must create your own CRUD app. You have two high level options for creating your CRUD app. You can implement an app that meets these six criteria:

  • Allows visitors to register a new account with some basic user information which is visible on a user profile page.
  • Allows users to edit their own profile
  • Allows users to create new “posts” which each have their own unique URL.
  • Allows users to restrict their post visibility beyond “all visitors to the web app”
  • Allows users to view posts by other users according to visibility rules
  • Allows users to delete their own posts

OR you can propose any other application idea that has six meaningful CRUD-style features. Honestly, I would recommend against proposing something else: almost any more complex application will have these features as a baseline. If you really want to do something very different, the additional requirements are:

  • Propose an overall app description along with a set of six meaningful features to me, via email, with the subject “Proposed 491 Application” by NOON, Friday, September 29.
  • Provide enough explanation of how each of the six features work in your README.md that a non-expert could run and test the functionality of your application (and be able to visually judge whether the application is doing what it says it’s doing).
  • Receive an OK from me by NOON, Saturday, September 30. If you don’t get a yes, you have to do the standard CRUD app, sorry.

Optional, but would be a good idea

Using the express application generator is totally allowed and a fine idea for getting started with good application structure and “skeleton code.”

You do not need to split your data model out from your application code. It is fine to keep the entire user “database” in an in-memory object (like a map).

You do not need to make the application pretty. In fact, I would recommend not wasting time adding any page layout beyond the bare minimum until after completing the graded requirements. For the sake of your sanity, I would recommend using a view engine - the application generator lets you choose which one you’d like, and if you’d like a quick overview this page does a decent job of introducing the popular ones.

Plan for security. While it’s not an explicit requirement worth any points on this assignment, it is wise. Document your threat model and potential attacks that an attacker might attempt, and how your code will prevent them.

Plan for maintainability. Explicit tests are a great way to check for correct execution and maintain your code. They aren’t required for this assignment, but there’s a one to one mapping between the required tasks and potential tests, it’s almost like they were chosen that way on purpose…

Technicalities

All commits must be made with your UIC email address - we’ll be verifying contribution based on commit history. You can update the email address that git uses for your commits with the command git config --global user.email "yournetid@uic.edu. Each group member should contribute 1/3 of all graded features implemented for groups of 3, and 1/2 for groups of 2. Academic integrity rules still apply here: you must write the code you commit. You can discuss how to do so with your group, but you must write your own code.

You are free to use whatever published node modules you’d like as part of your application. You must list which ones you used and why in your design document. You do not need to document code that is provided by the Express application generator if you choose to use it.

For any given package, you can only use “starter”/”example” code from the package’s official documentation. Whenever you use this code (outside of the require statement and any use wiring), either a modified or unmodified version, you must provide a comment with a URL pointing to the documentation, and a plain English description of what the code does. For instance, if I wanted to use the csurf package to defend against cross site request forgery, I would need to have comments that looks like:

/** From https://github.com/expressjs/csurf
 * Here we expose the CSRF middleware to the '/form' route and the token to the
 * template renderer so that it can be added to the HTML form for this user.
 */
app.get('/form', csrfProtection, function (req, res) {
  res.render('send', { csrfToken: req.csrfToken() })
});

/** From https://github.com/expressjs/csurf
 * Here we expose the CSRF middleware to the '/process' route so that it can
 * verify the CSRF token and abort the request if necessary.
 */
app.post('/process', parseForm, csrfProtection, function (req, res) {
  ...
});

As you can see, I expect a very deep understanding of reproduced code if you’re going to use it as part of your submission. It would be much better to read the documentation, get an idea of what is needed, close that browser tab, and then write your own code without the documentation open in front of you (and without touching your copy/paste buttons).

Deliverables

  • Design document (README.md) which describes, in plain English:
    • What your app does (if it has a theme beyond “meet the minimum requirements of the assignment”)
    • What modules you use, and how you use them
    • Any “how to run the app” explanation if it isn’t the default (see below).
    • A mapping between implementing student and feature implemented for each of the six features.
  • The actual code. If you need any node modules, they should be listed in package.json in the root of the repository. Furthermore, you must set the “start” property of the “scripts” object in package.json such that npm start will start your app. This is done automatically by the Express application generator. You may use multiple source code files, views, etc if you wish.

Grading

Grading will be done via manual inspection. The grader will:

  • Run npm install && npm start in a fresh HTML5 cloud9 instance. If you require the tester to do anything beyond that, explain clearly what they need to do within a fresh HTML5 cloud9 instance to run your app. You should listen on port 8080 to make running inside of cloud9 easy.
  • The tester will, in whatever order they choose, manually exercise each of the six features in your application. They may choose to do them in any order, they may do some tasks repeatedly.
  • In this assignment, the tester will not be attempting to attack your app. However, they will be attempting to do illogical or otherwise shouldn’t-be-possible tasks, like register an account that is already registered, edit a post that is not theirs, view a post that should not be visible to them, etc.
  • The grader will not be judging the style of the application, but an able-bodied English speaker who is acting in good faith should be able to find and activate the controls for all six tasks without difficulty. It is okay if they need to manually navigate to the main page of the app to find them, but every functionality should be reachable (if not necessarily directly) from the main page of the app.

Grading oracle

This assignment is due before class start time on Monday, October 9. Due to the manual and potentially subjective nature of grading, if you have any questions regarding whether you have sufficiently implemented a given feature, we will provide a grading oracle service. This will be similar to code reviews, but for grading. Each group is allowed, once every 24 hours (with the exception of the last 24 hours before the deadline - none will be accepted then), to send a review request. The process will work like this:

  • Write your contribution to the assignment in a repository fork. You can learn about the GitHub flavored forking model of software development here.
  • Add me and the TA as collaborators on your team repository.
  • Create a pull request on your team repository. Be as concise and descriptive as you can with what you’ve done, how to run it, and what feature you’d like tested.
  • Request a pull request review from us (at most once per 24 hours).
  • Wait at most 24 hours for us to respond. I make no guarantees of any response in any amount of time less than that.
  • If for any reason we can’t successfully test your code (we follow your instructions and node doesn’t start correctly, a file that’s needed for correct operation doesn’t exist in the repository…), we’ll let you know what error we got. We’ll be descriptive, but we won’t debug the process with you (outside of your next PR request). This expends your grading oracle request for that 24 hour period.
  • You’ll get a full credit/failed bit of information feedback at minimum. Any other feedback will be at our discretion.
  • You may only request one feature be tested at a time. If it takes me more than 2 minutes from clone to test complete, we reserve the right to tell you that the test timed out.
  • You are only guaranteed a response if you request review from both of us, and it’s up to us to decide who reviews it. If you get a review from one of us, the other won’t also test it.
  • We’re keeping track of the 24 hour limit manually for now. You’ll get one warning if your group sends more than one review request within a 24 hour window. A second “too soon” review request will lock your team out of oracle requests for the rest of the class.

Note that getting positive feedback here does not guarantee that you will get credit for that feature. Regressions are real. If you somehow introduce a regression later on, you could still lose those points.

Once the deadline has passed, the grading decision of the grader is final unless the decision is deemed completely unacceptable by us. The sooner you get started, the more you can take advantage of the oracle.