1. Overview

Up to now, and maybe without realizing it, you have been developing the server side (backend) of a web application. In this checkpoint, you will give your project a frontend (AKA - a client side implementation)! A frontend allows for an end user to access your project through a user interface (UI). The previous two checkpoints (C1 and C2) built the backend of your application and although your tests can access your methods, it would be hard for a user (like a parent or friend) to use them. In C3, you will complete your application by building a frontend to allow easy access to your backend methods (addDataset, removeDataset, listDataset and performQuery).

In this checkpoint, there are two phases. Phase 1 involves designing and writing the user stories of your frontend, while Phase 2 involves actually implementing them. Your frontend should also use REST API calls to communicate with your backend, and so Phase 2 also includes the task of implementing a REST API server.

The details regarding Phase 2 will be released after the Checkpoint 2 deadline.

2. Requirements

Phase 1: Frontend Selection & User Stories

1. Choose the type of frontend you will build

2. Write and submit two user stories

Note: We will use the acceptance criteria (DoDs) of these users stories to grade your C3 frontend implementation.

To receive full marks for each user story, you must:

• Follow the format outlined in the below section: Role, Goal, Benefit and Given/When/Then. Look at the given example.

• Solve a use case for the user. For example, a user that loves sushi would like to see the best sushi restaurants in Vancouver.

• Be end-to-end. It must involve both your frontend and backend to provide feedback to the user. A user story must be evoked by a user interacting with your UI, which causes a request to the backend. The backend then responds and the UI updates with visual feedback. For example, when I click “search” in Google, I expect to see a list of search results compiled by some backend servers running at Google.

• Follow the INVEST principles! (Independent, Negotiable, Valuable, Estimable , Small, Testable)

• NOT be a recreation of the Campus Explorer UI (ie. JSON query input with a table output)

Phase 2: Implementation & Demo

During Phase 2, you are required to:

1. Implement the Web server. (graded by AutoTest, smoke tests provided)

2. Implement your two frontend user stories.

3. Create a video demonstrating your two frontend user stories in action and submit it (graded). Please follow the Submission section below on how to submit your video. To receive full marks, your video must:

   • Be uploaded online, and accessible via a link

   • A continuous screen recording of your user stories (no editing!). We are not expecting a polished work of art, you may need to restart your server during your demo and that is ok!

   • Include Audio explaining what you are doing. You can easily add a microphone to the default screen recording provided by both Windows and Mac.

   • For each user story, you will walk through each Definition of Done. For each:

     1. Demonstrate the Given. For example, if your story requires an added dataset, show the dataset in your data folder on your server.

     2. Demonstrate the When. For example, if the user must enter in values into a text box or press a button, show it!

     3. Show the Network Request upon the user doing the action. To do so, open the developer tools in your browser and navigating to the "Network" tab. When performing the action, a network request will go to your server.

     4. Demonstrate the Then. For example, the list of data in your table or the error after entering incorrect input.

   • Be under 15 minutes. We expect most demos to be between 5-10 minutes.

Below is a list of things you CAN do when implementing your frontend user stories:

• Use all/some of the methods provided by the IInsightFacade interface. For example, you can use performQuery() to list the results of a general or specific query.

• Create a new backend controller to add a new method that can be accessed from your frontend. However, you cannot alter the IInsightFacade interface in any way. You must create a new class/file if you'd like to add a new method that can be accessed from your frontend.

This is by no-means exhaustive however. If you have an idea but unsure of whether it is acceptable, check-in with your mentor TA for advice!

3. Important Dates

The schedule contains the due dates for Phase 1 (User Story) and for Phase 2 (Web server + Demo).

4. Evaluation

4.1 Grading

Test Score (80%)

Similar to the previous checkpoints, C3 has a portion graded by AutoTest and we will provide smoke tests. For C3, the Web server is tested by AutoTest and accounts for 80% of C3.

As before, AutoTest will automatically grade your project each time you merge to the main branch. Your grade will be the maximum grade you received from all submissions (commits in git terminology) made before the hard deadline.

To run the smoke tests, you can call AutoTest with @310-bot #c3 on the commit of interest on the main branch. As with before, @310-bot #c0 is updated to accommodate C3 server tests against the reference implementation.

User Stories & Demo (20%)

Phase 1: User Stories (4%)

• Frontend user story one (2%)

• Frontend user story two (2%)

You will receive a 0, 0.5 or 1 for each user story. 0 = no effort, 0.5 = missing key element, 1 = wahoo!

We will not be accepting LATE submissions. You will not get feedback from your TA or a grade if you submit late.

Phase 2: Demo (16%)

• Frontend user story one (8%)

• Frontend user story two (8%)

For the demo of each user story, you will receive a 0, 0.5, or 1. 0 = no effort, 0.5 = some DoDs not met, or major bug, 1 = wonderful! However if you miss one of the requirements for the Demo Video (like not including sound, not naming the file correctly, not being able to watch it on a Mac, your grade will be capped at 50%).

Important: We are not marking the aesthetics of your frontend (rounded corners, pretty colours). The marks will be based on satisfying your DoDs.

4.2 Submission

Phase 1: Frontend Selection & User Stories

There will be a pull request made with a github issue template file, which you are required to use. Before the user stories submission deadline, please create an issue using this template and then edit the issue to contain your stories + DoDs. After merging the PR, go to "Issues" tab and click "New Issue". You should see a template called "User Stories".

During your lab, in the week following the Phase 1 deadline, you and your TA will go through the user stories to receive feedback.

Phase 2: Implementation & Demo

For the AutoTest portion of your grade (web server implementation), AutoTest will grade your main branch.

For the Demo, you will submit a video which demonstrates both of your user stories. This video should be uploaded online. You are responsible for choosing a location that the TAs can access while grading. The simplest solution would be a private Youtube link, but the choice is yours. The video link should be specified in the /frontend/README.md file. There are details on what must be contained in the video in the Requirements section of this document.

Merge to the main branch anything you would like evaluated before the deadline.

5. PHASE 1: Frontend Selection & User Stories

5.1 Frontend Selection

You can choose any frontend for your project! Have some fun, go a little wild! The only requirement is that all frontend code resides in a /frontend directory in your project_teamXXX repository. We will be providing starter code for a basic Web frontend and a Discord frontend. Both frontends require installing new node packages and similarly, you can install additional packages as needed by your own frontend of choice! You can also choose any language for your frontend. If you do install new packages, make sure you have a package.json file inside the /frontend directory, and that you're not installing new packages at the project root level.

You should select your frontend before writing your frontend user stories, as it will provide context for how your end-user will interact with your application.

If you select the Web as your frontend and choose to use our bootstrap, you will build a website using HTML, CSS and plain JavaScript which will send REST API calls to your server. If you select Discord as your frontend, your end user will interact with your server via Discord! They can send messages, which will be listened for by your Discord bot and then forwarded to your backend.

If choosing a frontend that you are less familiar with it might be worth doing a proof of concept to make sure implementation will go smoothly.

Disclaimer! TAs are most likely only familiar with the Web frontend, as that has been used in previous semesters. The TAs will not be able to provide the same level of support for alternate frontends.

5.2 User Stories

During the first phase of C3, you will write two user stories that outline how your end-user can use your frontend application to achieve desired outcomes. In the second phase, you will then design and implement the code to realize your user stories. At the end of the semester, you will demo your user stories and we will use the exact DoDs you've submitted to judge whether you have completed them. We will provide feedback on your user stories and it is important that you take that feedback into consideration for your implementation in Phase 2.

You are required to provide a minimum of two user stories involving the frontend UI. Though you're free to write and implement more than two user stories, you will be graded based on just two of them.

What is a User Story?

A user story should describe the type of user, what the user wants to do with your application, and for what benefit.

Note: A user story should in general be agnostic of your frontend of choice. It should encode "what" the user can do with your application, not "how". The "how" belongs to the Definitions of Done (more about this in next section). Simply put, if you find yourself describing your UI in a user story, beware!

You should use the Role, Goal, Benefit framework:

As a [role], I want to [goal], so that [benefit].

[role]: Who is using this?

[goal]: What is the user trying to achieve?

[benefit]: Why does the user want to achieve this?

What is a Definition of Done?

Included in each user story are the definitions of done (DoD) that define the conditions your application must meet before it is accepted by the user of the story. In other words, DoDs are agreement between you and your user about when an application feature is considered “done”. For each user story, the DoDs should describe "how" your frontend application supports the user in achieving the said goal. Please think of both the successful and failure cases.

Your DoD should follow the Given/When/Then framework:

Scenario: The name for the behaviour that will be described

Given: Some initial application state (precondition)

When: The user do some series of action

Then: Some outcome state is expected (post-condition)

5.3 Example User Story

As an online bank user, I want to be able to log into my account, so that I can access my banking information online.

Scenario 1: Correct credential

Given: The user is on the login page

When: The user enters a valid card number and password pair and clicks “Log in”

Then: The application logs the user in and presents the dashboard page

Scenario 2: Incorrect credential

Given: The user is on the login page

When: The user enters an incorrect card number and password pair and clicks “Log in”

Then: The application remains on the login page and shows an error in red telling the user to try again

5.4 Getting Started

There is no best way to get started, but a few hints may help you:

• Create the big picture of your project in your mind. Use pencil and paper and draw some diagrams. Where is what component and how do they interact with each other? What's on the client and what's on the server?

• For selecting a frontend - what frontends are both yourself and your partner familiar with? If choosing a frontend other than web, it may be worth doing a small proof of concept to ensure you can successfully complete C3.

Good luck and we sincerely hope you'll also have some fun implementing this checkpoint!

6. PHASE 2: Implementation & Demo

In this phase, you will build both your Web Server and Frontend. Since the Web Server is evaluated by AutoTest, we are explicit with how it should behave. However, for your Frontend, you get to implement whatever you described in your user stories.

6.1 The Web Server

In order to respond to requests from your frontend UI, you will complement your backend with a Web server that surfaces your InsightFacade methods. This means adapting your existing InsightFacade to also be accessed by any potential frontend, using REST endpoints. Both InsightFacade and the REST endpoints must continue to work independently.

Your Web server will need to provide the following REST endpoints exactly as they are specified, because your C3 client (ie. AutoTest) will leverage on these endpoints to access your InsightFacade methods.

• PUT /dataset/:id/:kind allows one to submit a zip file that will be parsed and used for future queries. The zip file content will be sent 'raw' as a buffer in the PUT's body, and you will need to convert it to base64 server side.

  • • 1. • Response Codes:

           1. • 200: When InsightFacade.addDataset() resolves.

              • 400: When InsightFacade.addDataset() rejects.

         • Response Body:

           1. • {result: arr}: Where arr is the array returned by a resolved addDataset.

              • {error: err}: Where err is a string error message from a rejected addDataset. The specific string is not tested.

• DELETE /dataset/:id deletes the existing dataset stored. This will delete both disk and memory caches for the dataset for the id meaning that subsequent queries for that id should fail unless a new PUT happens first.

  • • 1. • Response Codes:

           1. • 200: When InsightFacade.removeDataset() resolves.

              • 400: When InsightFacade.removeDataset() rejects with InsightError.

              • 404: When InsightFacade.removeDataset() rejects with NotFoundError.

         • Response Body:

           1. • {result: str}: Where str is the string returned by a resolved removeDataset.

              • {error: err}: Where err is a string error message from a rejected removeDataset. The specific string is not tested.

• POST /query sends the query to the application. The query will be in JSON format in the POST's body.
  
  NOTE: the server may be shutdown between the PUT and the POST. This endpoint should always check for a persisted data structure on disk before returning a missing dataset error.

  • • 1. • Response Codes:

           1. • 200: When InsightFacade.performQuery() resolves.

              • 400: When InsightFacade.performQuery() rejects.

         • Response Body:

           1. • {result: arr}: Where arr is the array returned by a resolved performQuery.

              • {error: err}: Where err is a string error message from a rejected performQuery. The specific string is not tested.

• GET /datasets returns a list of datasets that were added.

  • • 1. • Response Codes:

           1. • 200: When InsightFacade.listDatasets() resolves.

         • Response Body:

           1. • {result: arr}: Where arr is the array returned by a resolved listDataset

The :id and :kind portions above represent variable names that are extracted from the endpoint URL. For the PUT example URL http://localhost:4321/dataset/mysections/sections, mysections would be the id and secions would be the kind.

In addition to the above endpoints, you’re free to add more as you need to implement your two frontend user stories.

Note: Those of you paying attention in lecture may notice that this is not a very RESTful API. As an exercise, consider how you could modify one of the endpoints to make a more RESTful API! (But please don't actually modify, as AutoTest depends on this exact specification)

6.1.1 Web Server Bootstrap Code (Required)

We will provide starter code for the Web Server as a pull request against your repository. Once you merge this pull request from 310-bot, you'll have three new files in your project associated with the implementation of a Web server:

• src/App.ts contains the source code for starting the application and initializing the server. This will be given to you for free.

• src/rest/Server.ts contains the logic for your server.

• test/rest/Server.spec.ts contains the tests for your server. You'll want to write your own Server tests here!
  

Both the Server.ts and Server.spec.ts files will contain some sample code to point you in the right direction. We will use express as our REST server library. Please refer to its documentation first whenever questions arise.

6.1.2 Starting and Accessing the App

A new yarn command yarn start will be available in your project through a change to package.json (included in Web Server bootstrap).

It will essentially run App.js as a node application. Once you have started the server, you'll be able to access the app in the browser at http://localhost:4321.

6.1.3 Testing the Web Server

The same libraries and frameworks as before (Mocha, Chai) will be used for testing. This time, however, your tests will have to send requests to your backend and check the received responses for validity. You should use the debugger to inspect the responses to determine the exact format of response and where to find the values you want to assert against.

6.2 The Frontend

You will implement the two user stories you have written and received feedback for in Phase 1. Please make sure to review and closely follow the corresponding DoDs for each story, as you will be expected to demo the workflows in the DoDs during your final demo video.

6.2.1 Frontend Bootstrap Code (Optional)

We will provide bootstrap code for a Web Frontend and for a Discord Frontend, both are optional to use.

Web Frontend Bootstrap (Optional)

There will be an optional pull request from 310-bot for the web frontend. We’ve provided a simple implementation that contains a button that when clicked that shows an alert.

You will also need to uncomment the following line in your Server.ts file:

this.express.use(express.static("./frontend/public"))

This line is what serves your frontend UI sources to the root of your application.

The subdirectory /public contains the static sources that will be hosted by your Web app:

• index.html contains the starter HTML code for the UI. This file is hosted by the GET/ endpoint of your REST server. This will already be implemented in the bootstrap as well.

• style.css contains the styles for the UI.

• frontend.js will contain the logic to listen to the button click event and show an alert.

There are two new aspects to the Web frontend that you haven't seen in early checkpoints:

1. Plain JavaScript. While it is theoretically possible to develop in TypeScript on the frontend as well, using plain JavaScript has the advantage that you won't have to build/compile your project when you work on the frontend.

2. Browser. You will dive into the world of browsers with your frontend implementation. Your frontend code will be run client-side in the browser and will communicate with your Web server via REST/Ajax calls. This means also that you will have the global window, document and XMLHttpRequest objects from the browser available anywhere in your code.

Discord Frontend Bootstrap (Optional)

Please checkout the starter code in this repository: https://github.com/braxtonhall/bot-starter. It may also be useful to view the discord.js package: https://www.npmjs.com/package/discord.js.

6.2.2 Adding Datasets for the Frontend

You may require already loaded datasets for your UI to work. There are a couple of ways of ensuring this. You could of course implement the ability for an end user to add a dataset from the frontend UI, but this is sometimes complex (and may not be one of your user stories). You could find a way to call addDataset by hitting one of your REST endpoints from a client, or keep a cached copy of your data around and just paste it into your ./data folder so the server can load it from disk.

WARNING: Keeping a cached copy of some dataset in ./data folder can interfere with AutoTest. We recommend only doing this only for the purpose of demo, and remove the cached dataset once you've finished recording the demo.

6.3 Getting Started

There is no best way to get started, but a few hints may help you:

• Postman is a great tool for sending requests to the server. It could be useful to use this tool to determine how your endpoints are behaving for different inputs.

• The two parts in this checkpoint (server, frontend) should be implemented and tested independent from each other. They are only hooked together with Ajax requests going from the frontend to the server but all parts are designed to be implemented and tested independently.

7. FAQ

Q. I'm still working to finish C1/C2, how would these checkpoints affect my C3?

C3 is can be almost entirely independent from C1 and C2, except for the required REST endpoint user story. Here, in order to test your endpoints, the client can use functionalities from C1/C2 to interact with your backend. However, your two custom user stories can be designed such that only pre-implemented parts of your C1/C2 will be used.