azpect/Potion
1
1
Fork 0
Code Issues 9 Pull Requests Actions Packages Projects Releases Wiki Activity
Potion/doc/TechnicalSpecification.md
Hayden Hargreaves b17c5774e9 (UI): Implemented much of the frontend recipe creation wizard. 
Most everything is implemented, included a state handler and a pretty
simple (but workable) system for managing state in HTML. Nice and simple
for now.

There is still much work to be done, but the rest is simple backend
creation and error handling. And then input validation...a nightmare.
2025-06-29 22:30:20 -07:00

13 KiB
Raw Blame History

Technical Specifications

Application specifications.

Devices & Responsiveness

This application is a web app, however, it is built following a "mobile-first" pattern. Which means the desktop interface is lacking and will be designed after the completion of the mobile web interface.

Page Requirements

This section outlines the specific technical requirements for the application. It is broken down by page.

Home

The home page will server as the landing page where users can search recipes, filter their search, as well as view lists of recently made recipes, recently viewed and trending recipes lists.

UI Requirements

  • Welcome Banner

    • Video display with large text overhead
    • Sub text below the video with a "Call to Action"
    • Interactive banner that can be hidden with a "Got it!" or "X"

  • Message & Pills Banner

    • Message with text like "Craving Something Specific?"
    • Pill buttons below which allow for a direct search for meal type

  • Search bar

    • Ability to search for recipes, meals, and tags

  • Filter drop down

    • Filter by meal - E_Meal enum type
    • Filter by time requirements - 15min, 30min, 1hr, 1.5hr, +1.5hr
    • Filter by difficulty - 1 to 5 stars
    • Filter by serving size - 1 to 16

  • Recipe of The Week

    • Single recipe display of the best performing recipe, with spotlight effect
    • Display recipe details in depth - Title, duration, image*, meal category, simplified description
    • Make now button to allow easy access to meal directions

  • Recently Viewed List

    • Scrolling list of the most recent 5-10 recipes viewed
    • Display recipe details - Title, duration, image*, meal category, and a heart to like the recipe

  • Make Again List

    • Scrolling list of the most recent 5-10 recipes made
    • Display recipe details - Title, duration, image*, meal category, and a heart to like the recipe

  • Create Recipe CTA (call-to-action)

    • Large CTA banner with text prompting users to create a recipe
    • Button to take the user to the create page

'*': Not sure yet, still under consideration

API Requirements

  • Message & Pills Banner

    • Search all recipes of a specific meal type

  • Search bar

    • Text search on titles based on search query
    • Text search on tags based on search query
    • Text search on meal based on search query

  • Filter drop down

    • Update search to only contain meals from selected filter
    • Update search to only contain means that meet the time requirement of the selected filter
    • Update search to only contain meals that meet the difficulty level of the selected filter
    • Update search to only contain meals that meet the serving size of the selected filter

  • Recipe of The Week

    • Fetch the most performing recipe of the last 7 days and all of the required meta data
      • Most views (W: 0.1)
      • Most makes (W: 0.5)
      • Most likes (W: 0.3)
      • Most reviews (W: 0.4)
      • Highest avg rating (W: 0.2/star, 0.0 - 1.0)
    • Direct a user to the recipes display page
    • Telemetry data to collect clicks for each recipe

  • Recently Viewed List

    • Fetch a list of recently viewed meals and all required meta data
    • Like a post and store it in user's liked posts list
    • Direct a user to the recipes display page
    • Telemetry data to collect clicks for each recipe

  • Make Again List

    • Fetch a list of recently viewed meals and all required meta data
    • Like a post and store it in user's liked posts list
    • Direct a user to the recipes display page
    • Telemetry data to collect clicks for each recipe

'**': Not sure implementation

Favorites

Create

The create page will contain a page to create a new recipe. It will include all of the required details without any need to move to other pages. The entire creation process will take place here

UI Requirements

  • Create Recipe Heading Banner

    • Large, simple text banner that displays a header
    • Smaller text section that contains some useful information for using the wizard

  • Recipe Creation Wizard

    • Recipe Details: required
      • Recipe title: small text input (1 to 128)
      • Recipe description: large text input
      • Meal category: pill radio buttons or drop down*
      • Service size: numeric input (1 to 16)
      • Difficulty rating: star buttons that can be selected (up to 5)
      • Duration: prep and cook time, individual numeric inputs
    • Ingredients: required
      • Dynamic ingredient list: List of each ingredient
        • Content: name and quantity (both text inputs)
        • Actions: delete button and reorder element*
      • Add ingredient button: Simple button to add a blank ingredient row
    • Instructions: required
      • Dynamic instructions list: Numbered list of each instruction
        • Content: number and large text instruction
          • Rich text editor?*
        • Actions: delete button and reorder element*
      • Add step button: Simple button to add a blank instruction element
    • Media & Tags: optional
      • Image Upload
        • Single image selector for the thumbnail image
        • Small image display once one has been upload
        • Remove button to remove the image
        • Replace button to replace the image
      • Tags
        • Text input to add tags
        • Using list of existing tags, use a prefill while typing
        • Tags that don't exist will be added
        • Display a small list of added tags
        • Clicking a tag will remove it from the list
    • Footer & Submit
      • Save recipe button to complete the form
      • Button is disabled until the minimum required fields are complete*

  • Input Validation

    • Required elements should have a required indicator
    • Required elements will be validated input
      • Valid: Green outline or indicator* maybe a small, green check mark
      • Invalid: Red outline or indicator* maybe a red border with error text

'*': Not sure yet, still under consideration

API Requirements

  • Middleware

    • Authentication: User must be logged in to access this page
    • Authentication: User must be logged in to submit the creation of a recipe (fallback)

  • Recipe Creation Wizard

    • Create a new recipe object in the database
    • Recipe should be attached to a user (logged in)
    • User should be directed to the view recipe page on a successful creation

Shopping List

Profile

Database Requirements

This section outlines the specific technical requirements for the database store for this application. It will describe the required tables, fields, and other expectations.

Table ID Choice

Typically, I like to use UUID's for ID's. However, after some research I have concluded that for this application, the use of the SERIAL or SERIAL type will work sufficiently. Security is not a huge concern with this application since no major data will be stored, however, measures will still be in place (of course).

One of the biggest reasons I choose UUID's is their obscurity which provides some basic security against specific attack styles (enumeration attacks, etc.), however, I do not anticipate that being a large concern, so the simplicity of using an integer will surpass the small, niche benefits of using UUID's.

Tables

Below is a breakdown of the required tables and their respective fields. The fields will also have a list of attributes which are to be implemented at the database level. JSONB data fields will also have a small example object. A more in-depth data structure can be found in OTHER section.

  • Recipes: Represents a single recipe.

    • ID (PK) Serial
    • Title (Required) string(128)
    • Description (Required) text
    • Instructions (Required) string(1024)[]
    • Serves (Required) int(0..16)
    • Difficulty (Required) int(1..5)
    • Duration (Required) JSONB({ "total": int, "prep": int, "cook": int })
    • Category (Required) E_Meal (defined in the enums section)
    • Ingredients (Required) JSONB({ "item_a": [{ "name": string, "quantity": string }], "item_b": ... })
    • UserId (FK: User.Id) Serial
    • Modified () date/time stamp
    • Created (Required) date/time stamp

  • Users: Represents a single user.

    • ID (PK) Serial
    • GoogleId (Unique, Required) text
    • Name (Required) string(64)
    • Email (Unique, Required) string(128)
    • ImageURL () text
    • GoogleRefreshToken () text
    • Created (Required) date/time stamp

  • Engagements: Represents a single engagement from a single user.

    • ID (PK) Serial
    • Message () text (Used to store any relevant notes, if needed)
    • Entity (Serial) Serial (Used to relate an entity, if needed)
    • UserId (FK: User.Id, Required) Serial
    • Created (Required) date/time stamp

  • Likes: Many-to-many table to represent a list of recipes liked by a user.

    • ID (PK) Composite key**
    • UserId (FK: User.Id, Required) Serial
    • RecipeId (FK: Recipe.Id, Required) Serial
    • Created (Required) date/time stamp

  • Tags: Represents a single tag that can be had by many recipes.

    • ID (PK) Serial
    • Name (Unique, Required) string(32)
    • Created (Required) date/time stamp

  • RecipeTags: Many-to-many table to represent a list of tags on a recipe.

    • ID (PK) Serial
    • RecipeId (FK: Recipe.Id, Required) Serial
    • TagId (FK: Tag.Id, Required) Serial
    • Created (Required) date/time stamp

  • Lists: Represents a single users shopping list.

    • ID (PK) Serial
    • UserId (FK: User.Id, Required) Serial
    • Content (Required) JSONB([ { "name": string, "quantity": string }, ... ])
    • Created (Required) date/time stamp

  • Images: Represents a single image used by a single recipe.

    • ID (PK) Serial
    • RecipeId (FK: Recipe.Id, Required) Serial
    • Alt (Required) string(128) (alt text for accessibility, same as recipe title)
    • Url (Required) text
    • Created (Required) date/time stamp

  • Reviews: Represents a single review on a recipe from a single author.

    • ID (PK) Serial
    • Comment (Required) text
    • Rating () int(0..5) (Optional b/c nested replies don't need a rating)
    • ReviewId (FK: Review.Id) Serial (This is used for nested replies)
    • RecipeId (FK: Recipe.Id, Required) Serial
    • UserId (FK: User.Id, Required) Serial
    • Created (Required) date/time stamp

  • Notifications: Represents a single user notification.

    • ID (PK) Serial
    • UserId (FK: User.Id, Required) Serial
    • Type (Required) E_Notification
    • Message (Required) text
    • Entity (Serial) Serial (Used to relate an entity, if needed)
    • Read (Required, Default: F) boolean
    • Created (Required) date/time stamp

'**': Not sure implementation

Enums and Types

Below is a breakdown of the required enumerated types that should be stored in the database. Various tables will reference these types.

  • E_Meal: Type to represent the type of meal of a recipe.

    • breakfast: string
    • lunch: string
    • dinner: string
    • dessert: string
    • snack: string
    • side: string
    • other: string

  • E_Notification: Type to represent a type of user notification.

    • comment: string
    • like: string
    • system: string

  • E_Engagement: Type to represent a type of user engagement.

    • made: string
    • liked: string
    • viewed: string
    • shared: string
    • reviewed: string
    • rated: string