Project 3: Books for Days

Deadlines

Design Check Signup: Sat Dec 1 11:59PM
Design Checks: Tues Dec 4 - Wed Dec 5
Design Check handin: due 15 minutes before your design check

Final handin deadline: Tues Dec 11 9:00 PM
Final handin late deadline: Tues Dec 12 5:00 PM

Handin

Design Check:

Final Handin:

Summary

You and a friend want to make a website for people to be able to view and purchase books. You think you have devised a clever algorithm for determining books to recommend to the user that will make your site unique.

Your friend knows a little bit about web development, so they have handled all of the “frontend” work of the website. That includes writing everything required to display the website and make it so that when the user clicks on things, the right functions are run.

However, your friend has no idea how to handle the backend of the site. The backend includes the logic for users searching, adding and removing from their cart, purchasing books, and viewing book recommendations. You will fill in the necessary functions to make the website run!

To prototype your idea, rather than build a massive site supporting many people buying books you will instead create an example site that supports only one user. This will be enough to let you work out some key data structures and functions (so you can get buy in from other people, including potential funders!).

You will work with a dataset including the best sellers from amazon.com (we have already downloaded this as a CSV for you). The dataset gives information about the title, author, genre, number of reviews, and book rating (out of 5 stars). Not all books have review and rating information, but many do.

For the design phase, you will come up with a plan for the data structures required to handle the website logic (which we describe below), and write short dummy data examples that will make the website display a few books.

For the implementation phase, you will be filling in the functions to make the website actually run.

Overview: The website (provided)

The website (1) shows the user available books, (2) lets the user view information about individual books, (3) shows books specifically recommended for the user, (4) lets the user add or remove books from their shopping cart, (5) lets the user purchase the contents of their cart, and (6) allows the user to search for books. These actions occur through the following website pages:

You are not being asked to build these pages. That code will be provided. You just need to compute the data that gets displayed on the pages.

The home page

The home page shows a collection of books, organized by genre. There is no particular order to these books, they should be chosen randomly from the dataset every time the page is loaded.

Recommendations page

The recommendations page shows a list of books, sorted by how highly the system ranks those books for the user (for example, a book with 7 points comes before a book with 3 points; the point system is detailed below).

Search page

The search page shows a list of books matching the user’s search query, sorted by the rating of the books (for example, 4.8 stars comes before 3.5 stars).

Book viewing page

The book viewing page gives you more information about a book, and allows you to add the book to your cart.

Cart page

The cart displays all the books in the user’s cart, allowing them to remove individual books and purchase all the books in the cart.

Each page has a header with links to useful pages and a search bar to look for books, and a footer that displays the book covers of the user’s previously purchased books.


Overview: Your portion

When your friend implemented all of these pages, they made assumptions on how your code would communicate with theirs. In particular, your friend has already defined the Book dataclass and the names (and input/output types) of several functions that the visual part of the website depends on.

Everything your friend defined already is in a file named books.py in the directory we are giving to you. You have to complete that file to make the website work. In summary, you’ll need to provide code for the following operations (headers for which are already in the books.py starter file):

In order to write these functions, you’ll have to make some decisions about how to organize some of the required data. In particular, you’ll need to figure out how to represent the collection of all books from the dataset, the user’s shopping cart, the user’s prior purchases, recommendations for the user, and any additional internal datatypes that may be required.

Remember that even though lists (or hashtables) are the required output of many of these functions, your internal datatypes do not necessarily have to be lists (or hashtables).

Running the web application

The zip file we provide you contains all the files required for this assignment. Your code will go into books.py and bookstest.py.

To run the web app, you need to run app.py (also in that folder). app.py contains the code to create what is called a “Flask application.” Flask is a python package (similar to how datetime and dataclasses are python packages) which allows you to make web servers.

In PyCharm, run app.py. You should see something like this:

While this is running, you will be able to go onto your web browser and go to the url http://127.0.0.1:5000 and see the web app! This will only work on the computer that is running the application.

You can only have one version of the web app running; if you try to run app.py twice, you will see an error message. You should be able to have app.py running constantly; if you then make changes to books.py, the app will automatically reload itself and you can refresh the website.

If you are having a hard time running the web app, let the TAs know!

Design Check

For questions that ask you to figure out data structures, you should provide a combination of prose and code that indicates the main data structure with the types of all required components of the data (i.e., contents for lists, keys and values for hashtables, fields for dataclasses, etc.).

For example, if we asked you to set up data structures for a zoo, your answer might say “the zoo is a list of animals, where animals are a dataclass”, with the actual dataclass for an Animal written out in code.

Requirements

  1. Find a partner. You should work with someone other than your partners for the first two projects. Ideally, you and your partner probably should have similar goals for this project (for example, those heading for CS18 may want to think about the project in more depth, those aiming for less functionality should pair with others intending the same, etc.).

    Sign up for a design check appointment here. Make sure to invite your project partner to the event! (we need this information for grading purposes).

  2. Setup: Download our starter zip file from this link. Instructions for the rest of the setup in a video at the bottom!

  3. Setup: Manually create a simple hashtable that maps two genres (for example, Fantasy and History) each to two books. Make sure you can use this simple example to actual start up the website (your TA will check that this runs properly at the beginning of the design check). You should see a home page that displays your simple example. None of the other features need to work for this stage.

  4. Data/Coding: (1) Figure out which data structures you need to store the collection of books (that you will load from the provided csv file). This data structure must support efficiently finding the details of individual books.
    (2) With this representation in mind, write the get_book function (in books.py).

  5. Data/Coding: Figure out which data structures you need for the information about the user: their shopping cart, purchases, and recommendations. Remember that your data structures only need to support one user (rather than multiple users as a full bookstore site would have).

  6. Data/Coding: Figure out any data structures you may need to allow searching for books by author, genre, and title.

The Implementation Phase

For this phase, you will fill in the rest of the functionality that’s missing from the books.py starter file. We have included some Python hints as a support code link on the course website; they may or may not be useful to you.

As with project 2, this project will go more smoothly if you implement it in stages, rather than all at once. The three levels of functionality in the grading section suggest how to break this down into more manageable chunks.

The next three sections provide additional details on specific features or functions:

Details: Setup Function

In books.py, you will need to set up several global variables for any data that will be modified as the web app runs. For example, if the cart is a list of books, that list of books will be appended to and removed from when appropriate.

The setup() function should populate all of your global variables.

Note: You will need to define the global variable outside of any function, otherwise it will not exist inside of that function.

lst = []
def setup():
    lst.append(3)
    lst.append(4)

setup()
print(lst) # prints [3, 4]

Details: Homepage

When the homepage is opened, the get_book_dict function is run. This should return a hashtable that maps genres to lists of up to 20 Books. Again to optimize the website’s loading speed, you should not return a hashtable with one key for every genre in the dataset; rather, there should be one key for each of the genres in display_genres, which is a list of genres loaded on line 12 of books.py.

The books in the list for each genre should be chosen randomly so each time the homepage loads, the user sees 20 different, say, Fantasy books. You can use the random module to accomplish this (Google it!).

When the user searches in the search bar, your code needs to produce a list of all books from the dataset that match the search query. A search query matches if the query is part of the book’s title, author, or genre. This should be case insensitive in both directions.
Examples:

The returned list should be sorted by the books rating (with highest rating first), and should contain no more than 50 books (so as to not overwhelm the website).

Details: Recommendations

Initially, there should be no books recommended for the user. When the user buys a book, the recommendation information should update as follows:

You will need some way of internally tracking points so that when the user goes to the recommendation page (and the get_recommendations() function is called), a list of Books can be returned. The returned list should be sorted from most points to least points, should contain no more than 50 books (again so as to not overwhelm the website), and should not contain any books that have zero points.

Grading

Functionality

Minimum functionality (required for check-minus)

Mid-tier functionality (required for check)

Full functionality (required for check plus)

Testing

For this project, we are most interested in how you test functions that update data structures. Which function we will focus on for grading depends on how far you got:

You do not need to write tests for functions that use the random module. If you want to, you’ll have to think of non-explicit ways to test those functions (for example, looking at the length of a list rather than its contents).

Design and Clarity

We will grade design and clarity in the same manner as previous assignments. You should write helper functions where necessary to abstract your code, and you should use any previously written functions where you can rather than rewriting their functionality.

Reflection

This project was designed to give you practice with organizing data for both updating and fast access. Answer the following questions about these topics in a text file called reflection.txt.

  1. Describe one key insight that each partner gained about programming or data organization from working on this project.

  2. Describe one or two misconceptions or mistakes that you had to work through while doing the project.

  3. State one or two followup questions that you have about programming or data organization after working on this project.

  4. In lecture, we discussed (or soon will) the idea that different approaches to features like recommendations can yield very different results. As a result, the underlying models of what to recommend change over time. If we asked you to replace the current method for determining recommendations with a new one, what are all the places in your code that would need to change? What places would NOT need to change? Do you feel any of your code should have been isolated differently so that less code needs to be changed (this last part will depend entirely on your data structures and code – there is no single right/wrong answer).

    Q5 added Dec 1

  5. We gave you a dataclass for Books that did not include recommendation score. Why is that? There are a few reasons for this; try to think of at least one.

Project Setup Instructions


Text instructions at this link: https://cs.brown.edu/courses/csci0111/projects/project-3-installation.html