MS3 Cheat-Hub
A cheatsheet hub.
An app that organizes your code snippets into collections of cheat sheets and allows you to view, like and save others'.
The project is developed as part of MS3 Data Centric module at Code Institute. It is written with a Flask/Python restful backend API, and a React/Typescript CRA frontend.
Please visit the project at cheathub.vercel.app.
Additionally, the restful backend API can be viwed at cheathub-backend.herokuapp.com. For a sample response, please visit the /api/snippets endpoint.
In Development
Note: Scripts in root
package.jsonimplement Yarn workspaces only to run development-specific scripts from root assuming all backend/frontend-specific configs have been set up. Runningyarnfrom root has not yet been tested. For the meantime,cding to frontend and installing the React-App is the minimal reliable option to develop the app with a fixed and unchanging backend API. The backendpackage.jsonis solely for running python scripts from root. Backend API and data layer are superuser-specific given the production deployment, although local env variables are described in case anyone wants to locally serve a Mongo Atlas connection string from scratch. To be updated.
Contents
UX
User Stories
New Visitor Goals
- As a new vistor, I want to have a good understanding of what the website does.
- As a new visitor, I want to be able to register for an account.
Returning Visitor Goals
- As a Returning Visitor, I want to be able to log in securely.
- As a Returning Visitor, I want to be able to create a code snippet.
- As a Returning Visitor, I want to be able to see my code snippet.
- As a Returning Visitor, I want to be able to edit my code snippet.
- As a Returning Visitor, I want to be able to delete my code snippet(s).
- As a Returning Visitor, I want to be able to create a collection of my code snippets.
- As a Returning Visitor, I want to be able to see collections of my code snippets.
- As a Returning Visitor, I want to be able to edit collections of my code snippets.
- As a Returning Visitor, I want to be able to delete a collection of my code snippets.
Frequent Visitor Goals
- As a Frequent Visitor, I want to be able to search code snippets I have created.
- As a Frequent Visitor, I want to be able to search code snippets created by others.
- As a Frequent Visitor, I want to be able to like/fave code snippets created by others.
- As a Frequent Visitor, I want to be able to see my favorite code snippets created by others.
- As a Frequent Visitor, I want to be able to unlike/unfave code snippets created by others I have previously liked.
- As a Frequent Visitor, I want to be able to reference and copy code snippets to the the clipboard.
- As a Frequent Visitor, I want to able to delete my account.
Wireframes
Concept
The project can be understood as a library of user-created Albums or Playlists with the ability to organize, query and add items or tracks to those collections
Design
Accordion Cards
- A consistent border is applied to all nodes with dynamic content. These discrete borders are designed to convey the scale of snippet item relative to a collection. These containers only vary in spacing and height and are responsible for visually conveying open and closed states of snippets in collections of snippets.
Theme
- Chakra-UI's
ThemeProviderwraps the app in order to pass styles down the component tree. See Chakra-UI.
Colors
- The app features two sets of neutral tones for light mode and dark mode. Tones are applied to backgrounds while borders are rendered to highlight items and convey feedback. Tones are minimally set to three values within
#fafafaand#010f08in order to reserve state-changes to border sizes and scales.
Features
Existing Features
User Registration
- The website features the ability to
sign up,sign inandsign outin order to conditionally access existing features. A user is based on theusermodel, which requiresusername,emailandpasswordfor new users and only the latter two for existing users. For security, only usernames are stored inlocal storagewhiletokensare stored in memory. To ensuresign outacross multiple open windows, a logout event triggers astorage event listenerwhich clears tokens and usernames in the memory of the current window. -
Actions:
- Ability to create an account. (any User)
- Ability to sign in to an account. (Registered Owner)
- Ability to sign out of an account. (Registed Owner)
Code Snippets
- The website features the ability to create, update and delete a code snippet. A snippet is based on the
snippetmodel and each field is represented as either aformfield or asectionin anarticledepending on whether a code snippet is being edited or being featured. -
Actions:
- Ability to create, edit and delete a code snippet. (Registered Owner)
- Ability to
faveandunfavea code snippet. (Registered User)
Collections
- The website features the ability to group any and all existing code snippets into named collections aka
cheat sheets. A collection is based on thecollectionmodel, which is a name and a list of snippets. Each field is represented as either aformfield or aheaderfollowed by auldepending on whether a collection is in edit or display mode. -
Actions:
- Ability to create, edit and delete a named collection. (Registered Owner)
- Ability to add and remove snippets to/from a collection. (Registered Owner)
Search
search_textindices are attached to the title and description fields of thesnippetscluster. The frontend UI of the search feature is designed to return snippet cards that match a query. Additionally, the ability to query bytagsandlanguageis enabled by filtering these existing fields in the database.-
Actions:
- Ability to search code snippets created by others. (any User)
- Ability to filter snippets by language. (any User)
- Ability to filter snippets by tags. (any User)
- Ability to copy snippets to the clipboard. (any User)
- Ability to
faveorunfavesnippet results from search. (Registered User) - Ability to perform
crudoperations on snippet results from search. (Registered Owner)
Features Left to Implement
- Add query params to all resources
- Extend query parser to parse more than one query at a time
- Optimize performance by dereferencing database records
- User profile page
- Ability to add friends
- Ability to share snippets
Technologies
Frameworks and Libraries
-
Please visit the frontend sub directory for details on ReactJS Typescript frameworks and libraries.\cd frontend
-
Please visit the backend root directory for details on Python Flask frameworks and libraries.cd backend
Programs and Software
- VSCode: Visual Studiio Code 2020.3.2 by Microsoft is the IDE used to locally construct the project
- Git: Git is used as the version control system and is utilized via the WebStorm terminal to
committo Git andpushto GitHub. - GitHub: GitHub is used to store the project's code and directory upon concurrent
pushes via Git. - Adobe InDesign: Adobe InDesign is used to mock wireframes.
Notes
- Styles are written in-component and merge both Chakra-format and Framer-motion-format to achieve desired UI results. This is done by declaring motion boxes in Typescript to accespt Motion-Framer's HTML style props and Chakra's.
- Pagination is only for search endpoint.
- Access Token is stored in memory. Only usernames are stored in local storage, along with storage event listener for key
app-logoutwhich is triggered on logout and ensures all windows are logged out while the tokens are stored in atoken blocklistcluster.
Testing
User Testing
Arrival
- As a new vistor, I want to have a good understanding of what the website does
- User arrives at home page.
- The screen for
Cheathubappears with a description of its functionality. - User reads description.
- The screen for
- User continues.
- User arrives at home page.
Sign Up
- As a new visitor, I want to be able to register for an account.
- User is clicks
Switch to sign up- The sign up form appears
- The username field is in focus
- User types types a username, email and password.
- The username is taken.
- An error toast alert appears.
- User modifies username
- User is redirected to his/her
collectionsprofile.
- The sign up form appears
- User continues
- Review:
- A user is able to securely create an account.
- User is clicks
Sign In
- As a Returning Visitor, I want to be able to log in securely.
- User clicks
Switch to sign in- The sign in form appears - The email field is in focus - User types types email and password. - User hits enter. - A success toast alert appears.
- User is redirected to his/her
collectionsprofile.
- User is redirected to his/her
- The sign in form appears - The email field is in focus - User types types email and password. - User hits enter. - A success toast alert appears.
- User continues
- User clicks
Add and View Snippet
-
As a Returning Visitor, I want to be able to create a code snippet.
- User clicks
Add new snippet- A form appears.
- The title field is in focus.
- User inputs
title,description,language - User pastes a code snippet.
- User inputs
- User clicks submit.
- A success toast alert appears.
- The title field is in focus.
- User is redirected to his/her
collectionsprofile.
- A form appears.
- User continues
- User clicks
-
As a Returning Visitor, I want to be able to see my code snippet.
- User arrives at
Collectionsprofile.- A snippet card appears.
- User sees code snippet interface with his/her
- A snippet card appears.
- User continues
- User arrives at
Add Collection
- As a Returning Visitor, I want to be able to create a collection of my code snippets.
- User clicks
Add New Collection- A form appears.
- The
namefield is in focus.- User inputs names collection
- User selects existing code snippets to add.
- User clicks submit.
- A success toast alert appears.
- The
- User is redirected to his/her
collectionsprofile.
- A form appears.
- User continues
- User clicks
View Collection
- As a Returning Visitor, I want to be able to see collections of my code snippets.
- User arrives at
Collectionsprofile.- A
collectionscard appears.- User sees
collectioninterface that includes snippets added.
- User sees
- A
- User continues
- User arrives at
Edit Collection Details
- As a Returning Visitor, I want to be able to edit collections of my code snippets.
- User clicks
Edit this Collection- A form appears.
- The
namefield is in focus.- User renames collection.
- User uses
selectinput add more snippets. - User uses
selectinput to remove previous snippets.
- User clicks submit.
- A success toast alert appears.
- The
- User is redirected to his/her
collectionsprofile. - An updated
collectionappears.
- A form appears.
- User continues
- User clicks
Edit and View Snippet
- As a Returning Visitor, I want to be able to edit my code snippet.
- User clicks
Edit this snippet- A form appears.
- The title field is in focus.
- User modifies
description - User updates code snippet.
- User adds optional
sourceurl. - User adds optional
tags
- User modifies
- User clicks submit.
- A success toast alert appears.
- The title field is in focus.
- User is redirected to his/her
collectionsprofile.
- A form appears.
- User continues
- User clicks
Delete Snippet
- As a Returning Visitor, I want to be able to delete my code snippet(s).
- User clicks
Edit this snippet- A form appears.
- The title field is in focus.
- User clicks
Delete- Modal appears
- The cancel button is in focus
- User confirms
- The modal is closed
- A success toast alert appears.
- User clicks
- The title field is in focus.
- User is redirected to his/her
collectionsprofile.
- A form appears.
- User continues
- User clicks
Delete Collection
- As a Returning Visitor, I want to be able to delete a collection of my code snippet(s).
- User clicks
Edit this Collection- A form appears.
- The name field is in focus.
- User clicks
Delete- Modal appears
- The cancel button is in focus
- User confirms
- The modal is closed
- A success toast alert appears.
- User clicks
- The name field is in focus.
- User is redirected to his/her
collectionsprofile.
- A form appears.
- User continues
- User clicks
Search Snippets
- As a Frequent Visitor, I want to be able to search code snippets I have created.
- User clicks
Snippets- User is rerouted to
Snippetspage. - A feed of all public snippet cards appear.
- The
Snippets Searchinput appears. - The
searchfield is in focus.- User types a
search text- The snippet cards return snippets that match
search text
- The snippet cards return snippets that match
- User uses
selectinput to query bylanguage- The snippet cards return snippets written in
language
- The snippet cards return snippets written in
- User uses
selectinput to query bytags- The snippet cards return snippets that include input
tag
- The snippet cards return snippets that include input
- User clickes
Show All- The snippet cards return most recent snippets posted.
- User scrolls to end of page
- The
paginationbuttons appear - User clicks
Next- Snippet cards for next page appear.
- The
- User types a
- User continues
- User is rerouted to
- User clicks
Fave/Unfave Snippet and View Faved/Unfaved Snippets
- As a Frequent Visitor, I want to be able to like/fave code snippets created by others.
- User is in
Snippetspage.- A feed of all public snippet cards appear.
- User finds a snippet card.
- User clicks
Fave- A success toast appears
- A feed of all public snippet cards appear.
- User continues
- User is in
- As a Frequent Visitor, I want to be able to unlike/unfave code snippets created by others.
- User is in
Snippetspage.- A feed of all public snippet cards appear.
- User finds a snippet card.
- User clicks
Unfave- A success toast appears
- User clicks
Collections - The faves collection appears.
- User sees updated Faves.
- A feed of all public snippet cards appear.
- User continues
- User is in
- As a Frequent Visitor, I want to be able to see my favorite code snippets created by others.
- User is in
Collectionspage.- A collection named
Favesappears.- User finds all favorite snippts as a collection.
- A collection named
- User continues
- User is in
Copy Snippet to Clipboard
- I want to be able to reference and copy code snippets to the clipboard.
- User is in
Searchpage.- A feed of all public snippet cards appear.
- User finds a snippet card.
- User clicks
Copybutton- The copy button changes to a success icon.
- The code snippet is copied to the clipboard.
- A feed of all public snippet cards appear.
- User continues
- User is in
Delete Account
- As a Frequent Visitor, I want to be able to delete my account.
- User is clicks
Delete my account- Modal appears
- The cancel button is in focus
- User confirms
- The modal is closed
- Page is redirected to
/ - User is no longer able to log in with credentials
- The cancel button is in focus
- Modal appears
- User continues
- Review:
- A user is able to securely remove his/her history from the database.
- User is clicks
Switch Theme
Note: All screen shots of expected results of User testing can be viewed in the public docs directory. Please view them here
Code Testing
Frontend
Performance, Accessibility, Best Practices, SEO, PWA
- Lighthouse via Vercel is used to test performace, which produces unique results on every
git push. lighthouse-badges is used to generate new badges for every deployment by installingnpm i -g lighthouse-badgesand pushing the new hashed url to the array of urls:lighthouse-badges -o docs/badges -r -u https://cheathub.vercel.app/ [... all other urls] # Output to docs/badges # Badges will contain the respective average score(s) of all the urls supplied, combined - Lighthouse's metrics, namely Accessibility and Performance generate specific flags on each audit. Adjustments are made on each push that specifically address any issues.
Accessibility Testing
- ChromeVox Extension was used to ensure that screen-reader accessibility standards are met. This was done by walking through the entire project with the screen-reader plugin enabled. Various adjustments were made following these tests. Notably, the tab-index order of nav elements, and changing refining HTML5 semantic elements for
roleclarity.
Browser Testing
- Throughout the development of the project, in-browser dev tools were used to test for consistency across browsers. The browsers themselves were equally used for general use-case testing. The following browsers' per-device applications were accessed with an iPhone 11 Pro, MacBook Pro 15" and iPad Pro 12.9":
- Chrome Version: 83
- Firefox 82
- Opera 72
- Safari 14
Deployment
- The project frontend is written in Typescript developed with React, bootstrapped with Create React App and deployed with Vercel. The backend is written in Python, developed with Flask to serve a restful database via Mongo DB.
Please visit the frontend root directory for details on deployment steps.cd frontend
Please visit the backend root directory for details on deployment steps.cd backend
Cloning This Repo
- Clone this repo by running
git clone httpsL//github.com/israelias/cheathub - at the jump,
cdto the name of this repo:cd cheathub
Please visit the frontend root directory for details on required modules viacd frontendyarn installand to start the frontend development server onlocalhost:3000.
Please visit the backend root directory for details on required modules viacd backendrequirements.txtand to start the backend development server onlocalhost:5000.
Credits
Content and Media
- Code snippets used to fill the database are public cheat sheets gathered throughout the development of the project include url references in the snippet cards. The
hello worldfeature collection is references from Sayhello worldin 28 different languages
Acknowledgments
ESLint and Typescript Configuration
- ESlint Typescript with Prettier
- Create-React-App: Typescript, ESLint & Prettier with Airbnb style guides on VSCode
- Airbnb Javascript style guide — Key takeaway -Config ESLint, Prettier in Typescript React App
ReactJS and Typescript References
Flask backend with React frontend References
Monorepo
Mentoring
- Aaron Sinnott
- Code Institute tutors
- Fellow Code Institute students
5 May 25, 2022
2 May 14, 2022
1 Jan 7, 2022
2 Feb 6, 2022
3 Nov 17, 2022
0 Dec 26, 2021
5 Dec 15, 2021
2 Sep 14, 2022
20 Nov 12, 2022
1 Jan 7, 2022
8 Aug 6, 2022
1 Oct 21, 2021
30 Oct 13, 2022
215 Dec 20, 2022
2 Nov 30, 2021
1.6k Jan 4, 2023
0 Jan 14, 2022
1 Apr 4, 2022
