|
| 1 | +# Tappdin: A Beer Tracking App |
| 2 | +*By [Johnny Bui](https://github.com/JBui923) (front-end lead) [Giancarlo Sanchez](https://github.com/giancarlo-sanchez) (backend lead), and [Ben Perlmutter](https://github.com/bpmutter) (project manager)* |
| 3 | +* [Live version](http://tappdin.herokuapp.com/) |
| 4 | +* [Backend Github repo](https://github.com/bpmutter/tappdin-backend) |
| 5 | +* [Project Overview Presentation](https://docs.google.com/presentation/d/10oj08Ui1VeKpdLh826dOvSCKTy7ddCq2_fsc34zgWfU/edit?usp=sharing) |
| 6 | + |
| 7 | +**Table of Contents**: |
| 8 | +* [Tappdin at a Glance](https://github.com/bpmutter/tappdin/blob/master/README.md#tappdin-at-a-glance) |
| 9 | +* [Application Architecture and Technologies Used](https://github.com/bpmutter/tappdin/blob/master/README.md#application-architecture-and-technologies-used) |
| 10 | +* [Frontend Overview](https://github.com/bpmutter/tappdin/blob/master/README.md#frontend-overview) |
| 11 | +* [Backend Overview](https://github.com/bpmutter/tappdin/blob/master/README.md#backend-overview) |
| 12 | +* [Conclusion & Next Steps](https://github.com/bpmutter/tappdin/blob/master/README.md#conclusion) |
| 13 | +## Tappdin At a Glance |
| 14 | +Tappdin is a beer tracking app modeled on [Untappd](https://untappd.com/). It allows users to create accounts, post and delete checkins of beers, view the checkins of other users, and discover new beers. |
| 15 | + |
| 16 | +Tappdin currently possesses a database of 500 beers from almost 20 breweries that users can explore and review, which we call **checkins** to maintain consistency with the original Untappd app. |
| 17 | + |
| 18 | +## Application Architecture and Technologies Used |
| 19 | +Tappdin was built using separate front and back end servers that communicate via RESTful APIs. |
| 20 | + |
| 21 | +Both front and backend servers are built using the Express NodeJS framework. We used a PostgreSQL (postgres) database to store all application data. |
| 22 | + |
| 23 | +The front end uses the [Pug](https://pugjs.org/api/getting-started.html) templating engine to render views from the frontend server. We used vanilla Javascript for interactivity and standard CSS for styling. |
| 24 | + |
| 25 | +The backend uses a suite of libraries for application security and building its API routes (discussed further in the backend section below). To connect our backend to the postgres database we implemented the [Sequelize ORM](https://sequelize.org/). We also seeded the database using beer and brewery information from [BreweryDB API](https://brewerydb.com/developers/). |
| 26 | + |
| 27 | + |
| 28 | + |
| 29 | +## Frontend Overview |
| 30 | +As Tappdin, is a quite straightforward CRUD app with simple interactivity, we were able to build out the front end without any AJAX and minimal client-side Javascript. There are actually only 6 lines of frontend Javascript, which were used for the 'Demo User' login button! |
| 31 | + |
| 32 | +We made extensive use of the **Pug templating engine** to render dynamic content and create reusable HTML components that we were able to deploy across multiple views on the site. |
| 33 | + |
| 34 | +### Dynamic Templating with Pug |
| 35 | +For instance, we created a Pug mixin (the Pug equivalent of a JS function) to create relevant checkins across different views. We paired this with a component that took an array of checkin objects to dynamically render the associated checkins in its context (checkins by user on homepage, checkins about brewery on brewery page, etc.) |
| 36 | + |
| 37 | +Pug code snippet of checkins mixin: |
| 38 | +```pug |
| 39 | +mixin checkin(checkin) |
| 40 | + .checkin |
| 41 | + head |
| 42 | + link(rel="stylesheet" type="text/css" href="/styles/checkin.css") |
| 43 | + img.checkin__profile-picture(src=checkin.User.photo) |
| 44 | + .checkin__main |
| 45 | + p #[a(href=`/users/${checkin.User.id}`) #{checkin.User.firstName} #{checkin.User.lastName}] drank #[a(href=`/beers/${checkin.Beer.id}`) #{checkin.Beer.name}] from #[a(href=`/breweries/${checkin.Beer.Brewery.id}`) #{checkin.Beer.Brewery.name}] |
| 46 | + .checkin__rating |
| 47 | + p Rating: |
| 48 | + span.checkin__rating-val=checkin.displayRating |
| 49 | + //-created from the script |
| 50 | + if checkin.comment |
| 51 | + p=checkin.comment |
| 52 | + else |
| 53 | + p No comment |
| 54 | + div.checkin__other-info |
| 55 | + span.checkin__date=checkin.createdAt |
| 56 | + if checkin.isSessionUser |
| 57 | + span.checkin__delete #[a(href=`/checkins/${checkin.id}/delete`) Delete checkin] |
| 58 | + img.checkin__profile-picture(src=checkin.Beer.Brewery.image) |
| 59 | +``` |
| 60 | +Pug code snippet of dynamically rendering all the checkins for a particular view: |
| 61 | +```pug |
| 62 | +section.recent-activity |
| 63 | + include checkin |
| 64 | + head |
| 65 | + link(rel="stylesheet" type="text/css" href="/styles/recent-activity.css") |
| 66 | + h2 Recent Activity |
| 67 | + div#checkin__container |
| 68 | + if checkins.length |
| 69 | + each checkin in checkins |
| 70 | + +checkin(checkin) |
| 71 | + else |
| 72 | + p It looks like there aren't any reviews yet |
| 73 | +``` |
| 74 | + |
| 75 | + |
| 76 | + |
| 77 | +### Refactoring the Way to Reusable Code |
| 78 | +The most challenging aspect of the front end of Tappdin was probably the sheer number of different views that we had to create, and how to serve content dynamically into them. |
| 79 | + |
| 80 | +This required us to get creative in how we created that content, using Pug mixins, various layouts, and a whole lot of CSS code. We also had to figure out how to send the relevant data to the views form the server to make code reusable across different views. |
| 81 | + |
| 82 | +There was no secret sauce that we used to make the code module and reusable. Our general process was: |
| 83 | +1. hard coding how we wanted something to look with Pug, CSS, and dummy data provided inline. |
| 84 | +2. Then we would refactor to add dynamic data from the server |
| 85 | +3. Finally, we’d modularize the component to reuse accross other parts of the site. |
| 86 | + |
| 87 | + |
| 88 | +## Backend Overview |
| 89 | +Our backend was primarily a collection of RESTful APIs that we used to query our database for relevant data on beer, breweries, and app users. |
| 90 | + |
| 91 | +We made extensive use of the Sequelize ORM to make fairly complex queries of data associated across multiple tables. Once we had the database built and setup in the ORM, these queries were fairly straightforward, if somewhat challenging to execute due to the sometimes obtuse Sequelize syntax. |
| 92 | + |
| 93 | +### Authentication and Application Security |
| 94 | +We used a JSON Web Token (JWT) to authorize our users across sessions. We stored the JWT in a cookie in the browser, which we would send along for verification with backend server requests. We used the [jsonwebtoken](https://www.npmjs.com/package/jsonwebtoken) node library for this. |
| 95 | + |
| 96 | +We also used the [csurf](https://www.npmjs.com/package/csurf) package on our frontend server to protect against CSURF attacks and the [bcryot](https://www.npmjs.com/package/bcrypt) hashing library to protect user passwords. |
| 97 | +### Relational Database Model |
| 98 | +One of the larger challenges of the project was to design a relational database schema to associate our data. Before we wrote a single line of code, we designed the database with all the tables we’d need and their relationships to each other. |
| 99 | + |
| 100 | +We then had to translate that to 0ur Sequelize models where we we created associations between the tables so that we easily query across them (basically the Sequelize version of standard postgres INNER JOIN). |
| 101 | + |
| 102 | +This was the final database schema: |
| 103 | + |
| 104 | + |
| 105 | +**Notes on the database schema**: |
| 106 | +* Foreign keys are denoted by FK |
| 107 | +* Yellow boxes represent many-to-many join tables |
| 108 | +* Blue boxes have one-to-many relationships with associated foreign keys |
| 109 | +* As of writing (5/24/20), Tappdin doesn’t yet have implemented the Liked Brewery and beer List functionality. However, these tables are in the database, and the relations are set up in the Sequelize models. We would like to implement this functionality at a later point. |
| 110 | + |
| 111 | +### Seeding the Database |
| 112 | +Seeding the database was probably the most technically intensive part of the entire project. As noted above, we used the BreweryDB API to seed our database with information about beers and breweries. |
| 113 | + |
| 114 | +While BreweryDB was a great (and free!) resource for generating seed data, the way that the data was structured in BreweryDB was not compatible with our database design. |
| 115 | + |
| 116 | +BreweryDB used 6-character strings as the primary keys for their breweries, whereas we had to use integers at primary keys (PKs) due to restrictions in the Sequelize ORM only permitting integer PKs. |
| 117 | + |
| 118 | +Matters were further complicated by the fact that we needed to seed the breweries for the database before we seeded the beer to allow for the foreign keys (FKs) in the Beers table to be dependent on the Breweries table. However, the relationships within BreweryDB API structure required that we query beers before we could access the dependent breweries. |
| 119 | + |
| 120 | +We therefore had to: |
| 121 | +1. Create a list of all breweries we were to use in our seed data. |
| 122 | +2. Add integer primary keys to each brewery instance |
| 123 | +3. Reassociate these brewery primary keys with their associated beers |
| 124 | + |
| 125 | +To solve this problem, we first did a pass through all 500 beers we were going to use where we created a [Javascript Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) to capture only the unique breweries. |
| 126 | + |
| 127 | +**Seed Set Code:** |
| 128 | +```js |
| 129 | +const seed = require('./raw-data') |
| 130 | + |
| 131 | +const breweriesSet = new Set(); |
| 132 | +seed.forEach(beer => { |
| 133 | + if (beer.breweries && beer.breweries[0].id) { |
| 134 | + breweriesSet.add( |
| 135 | + beer.breweries[0].id |
| 136 | + ) |
| 137 | + } |
| 138 | +}); |
| 139 | + |
| 140 | +``` |
| 141 | + |
| 142 | +We then converted that set into an array, so we could easily create PKs from the position in the array. Our PKs, were just the position+1. |
| 143 | + |
| 144 | +**Converting the set into useable array:** |
| 145 | +```js |
| 146 | +const brewerySeed = []; |
| 147 | +seed.forEach(beer => { |
| 148 | + if (beer.breweries && beer.breweries[0].id) { |
| 149 | + if (breweriesSet.has(beer.breweries[0].id)) { |
| 150 | + brewerySeed.push({ |
| 151 | + name: beer.breweries[0].name, |
| 152 | + key: beer.breweries[0].id, |
| 153 | + location: `${beer.breweries[0].locations[0].locality}, ${beer.breweries[0].locations[0].region}`, |
| 154 | + description: beer.breweries[0].description, |
| 155 | + website: beer.breweries[0].website, |
| 156 | + image: beer.breweries[0].images ? beer.breweries[0].images.squareLarge : null, |
| 157 | + createdAt: new Date(), |
| 158 | + updatedAt: new Date() |
| 159 | + }); |
| 160 | + breweriesSet.delete(beer.breweries[0].id); |
| 161 | + } |
| 162 | + } |
| 163 | +}); |
| 164 | +``` |
| 165 | +Once we had the brewery data in a Sequelize-compatible format, we reassociated it with the beer table, adding the relevant beer as a FK referenced by it’s ID. |
| 166 | + |
| 167 | +We then removed and/or renamed keys in the beer and brewery JSON objects to be compatible with the database schema. |
| 168 | + |
| 169 | +Finally, we wrote the data out into JS files, in which we exported the arrays of beer/brewery POJOs to the Sequelize seed file, from where we added it to the database. |
| 170 | +## Conclusion |
| 171 | +This project represented our first full-stack application. It was, to put it modestly, a challenge. But with that being said, we would also consider it to be a very successful effort—we met our MVP goals and created a full-stack CRUD application that now lives on the internet, and a pretty decent looking one too. |
| 172 | + |
| 173 | +While the project has been deployed that doesn’t mean we are done with it yet. A couple of features that we haven’t been able to add, but would like to are: |
| 174 | +* Make the whole project responsive |
| 175 | +* Add functionality for Liked Breweries and Lists of beers (already built into database, as noted above, but not yet implemented in app) |
| 176 | +* Refine search functionality |
| 177 | +* Comprehensively review error handling to make sure that we properly handle all |
| 178 | +* Add view and backend API to render all beers associated with a particular brewery |
| 179 | + |
| 180 | +Thanks for reading, cheers! 🍻 |
0 commit comments