bloomtech-labs / story-squad-be-archived

API Documentation

Getting started

Check the wiki for a setup guide

Backend framework

Express

• Useful libraries such as helmet and CORS.
• Well documented.

TypeORM

• Simplifies database creation, connections, queries, etc
• Plays well with Typescript
• Simple seeding.

Jest

• Maintains consistency with front-end testing

SuperTest

• Simplifies endpoint testing
• Integration testing

Endpoints

Postman Documentation

Authorization Routes

Method	Endpoint	Access Control	Description
POST	/auth/register	all users	Creates parent account and Stripe customer.
USE	/auth/login	adult users	Returns parent token.

Admin Routes

Method	Endpoint	Access Control	Description
GET	/admin/	admin users	Returns list of admins/moderators
GET	/admin/me	admin users	Returns self information
GET	/admin/:id	admin users	Returns matching admins/moderator
POST	/admin	admin users	Returns added admin/moderator id
POST	/admin/login	admin users	Returns admin token
PUT	/admin/register	admin users	Returns admin token

Parent Routes

Method	Endpoint	Access Control	Description
GET	/parents/me	adult users	Returns logged in parent.

Child Routes

Method	Endpoint	Access Control	Description
GET	/children/list	adult users	Returns a list of child accounts associated with logged in parent
POST	/children/list	adult users	Adds a new child account
GET	/children/list/:id	adult users	Returns specified child account
PUT	/children/list/:id	adult users	Updates specified child account
DELETE	/children/list/:id	adult users	Deletes specified child account
GET	/children/me	child users	Returns logged in child
GET	/children/preferences	child users	Returns child's preferences
GET	/children/progress	child users	Returns Progress of current week
POST	/children/progress	child users	Updates progress of current week
GET	/children/cohort	adult users	Returns cohort the child is in
GET	/children/parent	child users	Returns the child's parent
POST	/children/:id/login	adult users	Returns JWT for Child

Canon Routes

Method	Endpoint	Access Control	Description
GET	/canon/	admin users	Returns a list of pdf
GET	/canon/:week	all users	Returns a matching pdf
POST	/canon	admin users	Creates a new pdf

Cohort Routes

Method	Endpoint	Access Control	Description
GET	/cohort/	all users	Returns Cohort ID of logged in child
GET	/cohort/list/	admin users	Returns a list of all Cohorts
POST	/cohort/list/	admin users	Creates a new Cohort
PUT	/cohort/list/:id/	admin users	Updates specified Cohort
DELETE	/cohort/list/:id/	admin users	Deletes specified Cohort

Payment Routes

Method	Endpoint	Access Control	Description
GET	/cards	adult users	json list of user's cards
POST	/cards	adult users	adds card as payment source to Stripe
POST	/subscribe	adult users	creates a subscription
DELETE	/cards/:id	adult users	deletes a payment method

Submissions Routes

Method	Endpoint	Access Control	Description
GET	/submissions	child users	json list of user's submissions
GET	/submissions/:week	child users	json object of a user's submission for a specific week
POST	/submissions	child users	upload image and receive json object of a user's new submission and the transcribed text
DELETE	/submissions/:week	child users	delete and receive json object of a user's removed submission

Versus Routes

Method	Endpoint	Access Control	Description
GET	/versusRoutes/versus	child	Gets a childs full match data

Voting Routes

Method	Endpoint	Access Control	Description
GET	/votingRoutes/voting	child	Gets a random match to vote on
POST	/votingRoutes/voting	child	Submits a vote

Story Routes

Method	Endpoint	Access Control	Description
GET	/storyRoutes/:week	child	Returns a story based on week
GET	/storyRoutes/children/:id	admin	Returns all stories for child with :id
GET	/storyRoutes/children/:id/week/:week	admin	Returns story based on week for child with :id
PUT	/storyRoutes/stories/:id	admin	edits isFlagged value for story with :id. Body needs {"isFlagged": boolean}

Illustration Routes

Method	Endpoint	Access Control	Description
GET	/illustrationRoutes/:week	child	Returns a picture based on week
GET	/illustrationRoutes/children/:id	admin	Returns all pictures for child with :id
GET	/illustrationRoutes/children/:id/week/:week	admin	Returns picture based on week for child with :id
PUT	/illustrationRoutes/illustration/:id	admin	edits isFlagged value for picture with :id. Body needs {"isFlagged": boolean}

Final Routes

Method	Endpoint	Access Control	Description
GET	/finalRoutes/time	child	Returns true or false, depending on whether or not voting time is over
POST	/finalRoutes/results	child	Returns the results of the match for the child that is logged in. assumes voting time is over

Game Walkthrough from Labs24

• https://www.loom.com/share/20308b4772d2411fb76616053133d5ee

Known issues at the end of Labs24 6/24/20

• The versus switcheroo bug https://github.com/Lambda-School-Labs/story-squad-be/blob/master/src/timers/pointalloc.timers.ts#L156-L194 - this happens to generate 1 on 1 matches because it became really needed for voting

  and it saves everything into this https://github.com/Lambda-School-Labs/story-squad-be/blob/master/src/database/entity/Versus.ts

  but versus still just recalculates using the same thing https://github.com/Lambda-School-Labs/story-squad-be/blob/master/src/routes/versus/versus.Routes.ts#L48-L82

  The general LEFT/RIGHT/points structure still needs to be followed, but it doesn't need to "sortbypoints" and find the matches again

  If teammates end up with the same number of points for both their stories, then recalculating could in an off-chance swap 1 person for the other on the matchmaking screen.

• The Week 2+ submissions bug For any week after week 1, the front end will think that players have already submitted a story and picture, even if they haven't. This is because they are checking for Array.length in https://github.com/Lambda-School-Labs/story-squad-fe/blob/master/src/app/components/child-dashboard/kid-progress/kid-progress.component.tsx#L52-L80 - The Checkboxes

  We need to send an array for only the current week in this endpoint - https://github.com/Lambda-School-Labs/story-squad-be/blob/master/src/routes/child/child.routes.ts#L12-L36

  Alternatively, you could alter what the front end checkboxes are looking for.

Contributing

When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change. Please note we have a code of conduct. Please follow it in all your interactions with the project.

Attribution

These contribution guidelines have been adapted from this good-Contributing.md-template.

Documentation

See Frontend Documentation for details on the frontend of our project.

For information on database entities and environment variables, see the backend documentation.

story-squad-be-archived's Issues

Match allocation edge cases

Currently, the matchMaking and versusRoutes endpoints handle matchmaking for four individuals, 2 teams of 2 correctly.

Although DS will allocate players to matches with less than 4 players, BE cannot dynamically handle matches if one, two or three players are left out, or what to do if child.id = 0 is present in a match object.

Possibly 2 vs 1 scenario, 1 vs 1 scenario, or duplicate some submissions to be used multiple times to fill in for the missing players.

*Stakeholder aware of issue

Pages need to request browser to deny caching

While working with the voting-component, due to the large size Chrome began caching the webpages, which then caused the pages to return the same error message constantly.

The temporary fix is to visit the cached URL in a new tab and refresh until it updates, then you can continue.

See engineering standards

https://github.com/Lambda-School-Labs/story-squad-be/blob/4adedb635db9d5ac9723a732d453cb2e570e5a4b/src/routes/admin/admin.routes.ts#L153

RE: https://lambda-school-labs.github.io/labs-engineering-standards/topics/code-quality/#cq-120-code-cleanliness

auth/reg invalid password error handling

auth/reg route doesn't have error handling for password being too short

Unidentified Matchmaking Bug

Unknown replication steps, using specifically child ID's 9-16, when attempting to generate the matches, the "not enough submissions" error was given back, even though all children had illustrations and stories tied back.

Full reset resolved the problem.

Possibly the wrong ID values being checked in the matchmaking route? Unknown.

New canon data inconsistencies

If a new canon is set for a week, previous match-ups still exist. Previous story submissions seem to stay too. However, it also allows generating another set of the same match-up now for some reason.

Faulty submit cases not accounted for

https://github.com/Lambda-School-Labs/story-squad-be/blob/f4a348a18c783d6f23a9bb215ffd346a84c9aac7/src/routes/submissions/submissions.routes.ts#L51

Cases such as illustration being a regular string will break the python scripts, crashing the backend. There needs to be validation protecting datascience scripts so that they aren't fed anything unseemly.

Matchmaking can still happen without illustration submissions

Matchmaking can still happen even if illustration submissions doesn't exist

Possible solutions

• check progress and see if drawing is true before including the submissions to match

Sometimes readability.py breaks

readability.py will break the server if not send an object with a story key/value pair.

ES: code cleanliness

https://github.com/Lambda-School-Labs/story-squad-be/blob/4adedb635db9d5ac9723a732d453cb2e570e5a4b/src/routes/submissions/submissions.routes.ts#L59

RE: https://lambda-school-labs.github.io/labs-engineering-standards/topics/code-quality/#cq-120-code-cleanliness

Submissions entity many to one relation has a named column

https://github.com/Lambda-School-Labs/story-squad-be/blob/b4751b59c2103c907454c02f8e19611fc44a11ae/src/database/entity/Submissions.ts#L11

This might cause issues when attempting to write over a record with update and copying the previous record. It caused issues within Child entity, so the named columns were removed but submissions column name is currently being used within matchmaking.

Stories disappearing mysteriously

There's a case I'm currently unable to replicate where story submissions will sometimes disappear. illustrations are safe for some reason. Match-ups that pre-exist stay but due to no stories, the allocation page won't render successfully.

Add this task to Trello

https://github.com/Lambda-School-Labs/story-squad-be/blob/f7f7093af470d737652a44e1908ec3713534f8ca/src/routes/admin/admin.routes.ts#L79

Data SEEDING would be really helpful

And isn't set up with submissions

Avatar entities/ backend still doesn't exist

We need a way to store avatar/ or the text of the avatar so we can use it later

PUT /battlesRouts/battles doesn't save the correct points

Possible Solution

• change the code in PUT /battles in battles.routes.ts

need a separate get to check matches

https://github.com/Lambda-School-Labs/story-squad-be/blob/5ae891cbd93d8fcc5308d53107750685e9f343b1/src/routes/submissions/submissions.routes.ts#L30

If the child has been matched(match exists for that week for that child), prevent rendering of refresh button(the one that removes submission)

SC-200 violation

RE: #sc-200-never-store-secrets

Stripe secret key: This lives in the secrets world

https://github.com/Lambda-School-Labs/story-squad-be/wiki/Setup-Guide

fix progress so front-end can determine completion of illustration/story separately

https://github.com/Lambda-School-Labs/story-squad-be/blob/5ae891cbd93d8fcc5308d53107750685e9f343b1/src/database/entity/Progress.ts#L12

discussed removing submission & using illustration (or just adding an illustration progress field) check routes to see how these fields are being checked/assigned as well as FE and meet with the team to determine what we shoul do

DS Integration

DS Integration is setup in the experimental NestJS branch but not master.
Setting up DS Integration is quite simple actual.

Reference materials for setting it up:

• DS Integration example: https://github.com/Lambda-School-Labs/story-squad-ds/tree/master/integration