From 456b104fb7e93f0503d62245202da83d25569ccc Mon Sep 17 00:00:00 2001 From: Hayden Hargreaves Date: Sun, 1 Jun 2025 22:24:31 -0700 Subject: [PATCH] (DOCS): More work on the technical specifications. Moved them to a dedicated directory, but I cannot use doc since ExDoc generates code there which is ignored by the git ignore file. --- TechSpecs.md | 144 -------------------- spec/TechnicalSpecification.md | 232 +++++++++++++++++++++++++++++++++ 2 files changed, 232 insertions(+), 144 deletions(-) delete mode 100644 TechSpecs.md create mode 100644 spec/TechnicalSpecification.md diff --git a/TechSpecs.md b/TechSpecs.md deleted file mode 100644 index e383f3f..0000000 --- a/TechSpecs.md +++ /dev/null @@ -1,144 +0,0 @@ -# Technical Specifications - - -- [Technical Specifications](#technical-specifications) - - [Page Requirements](#page-requirements) - - [Home](#home) - - [UI Requirements](#ui-requirements) - - [API Requirements](#api-requirements) - - [Favorites](#favorites) - - [Create](#create) - - [Shopping List](#shopping-list) - - [Profile](#profile) - - [Database Requirements](#database-requirements) - - [Tables](#tables) - - -Application specifications. - - -## Page Requirements - -This section outlines the specific technical requirements for the application. It is broken down -by page. - - -#### Home - -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, and other (**undetermined**) lists. - -##### UI Requirements -- Search bar - - [ ] Ability to search for recipes, meals, and tags - -- Filter drop down - - [ ] **Filter by meal** - *breakfast, lunch, dinner, side, any* - - [ ] **Filter by time requirements** - *15min, 30min, 1hr, 1.5hr, +1.5hr* - - [ ] **Filter by difficulty** - *1 to 5 stars* - -- Make again list - - [ ] Scrolling list of the most recent 5-10 recipes **made** - - [ ] **How do we determine what recipes were made?*** - - [ ] **Display recipe details** - Title, duration, **image***, and a heart to like the recipe - -- Another scrolling list* - - -'*': Not sure yet, still under consideration - - -##### API Requirements - -- 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 - -- Make again list - - [ ] Fetch a list of recently made meals** - - [ ] Like a post and store it in user's liked posts list - - -'**': Not sure implementation - - - -#### Favorites - - - - - - - -#### Create - - - - - - - -#### 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. - -### Tables - -- [ ] Recipe: Represents a single recipe. - - [ ] ID (PK) *UUID or serial*** - - [ ] Title (Unique, Required) string(128) - - [ ] Description (Required) text - - [ ] Instructions (Required) string(1024)[] - - [ ] Serves (Required) int(0..16) - - [ ] Ingredients (Required) JSONB({ "item_a": [{ "name": string, "quantity": string }], "item_b": ... }) - - [ ] Difficulty (Required) int(1..5) - - [ ] Duration (Required) JSONB({ "total": int, "prep": int, "cook": int }) - - [ ] Author (FK: User.Id) *UUID or serial*** - - [ ] Created (Required) date/time stamp - -- [ ] User: Represents a single user. - - [ ] ID (PK) *UUID or serial*** - - [ ] Name (Required) string(64) - - [ ] Email (Unique, Required) string(128) - - [ ] Password (Required) string(128) *stored as hash*** - - [ ] Created (Required) date/time stamp - -- [ ] Like: **Many-to-many** table to represent a list of recipes liked by a user. - - [ ] ID (PK) *Composite key*** - - [ ] UserId (FK: User.Id, Required) *UUID or serial*** - - [ ] RecipeId (FK: Recipe.Id, Required) *UUID or serial*** - - [ ] Created (Required) date/time stamp - -- [ ] Tag: **Many-to-many** table to represent a list of tags that can be had by many recipes. - - [ ] ID (PK) *UUID or serial*** - - [ ] Name (Unique, Required) string(32) - - [ ] RecipeId (FK: Recipe.Id, Required) *UUID or serial*** - - [ ] Created (Required) date/time stamp - -- [ ] List: Represents a single users shopping list - - [ ] ID (PK) *UUID or serial*** - - [ ] UserId (FK: User.Id, Required) *UUID or serial*** - - [ ] Content (Required) JSONB([ { "name": string, "quantity": string }, ... ]) - - [ ] Created (Required) date/time stamp - -'**': Not sure implementation diff --git a/spec/TechnicalSpecification.md b/spec/TechnicalSpecification.md new file mode 100644 index 0000000..6dee12b --- /dev/null +++ b/spec/TechnicalSpecification.md @@ -0,0 +1,232 @@ +# Technical Specifications + + +- [Technical Specifications](#technical-specifications) + - [Page Requirements](#page-requirements) + - [Home](#home) + - [UI Requirements](#ui-requirements) + - [API Requirements](#api-requirements) + - [Favorites](#favorites) + - [Create](#create) + - [Shopping List](#shopping-list) + - [Profile](#profile) + - [Database Requirements](#database-requirements) + - [Table ID Choice](#table-id-choice) + - [Tables](#tables) + - [Enums and Types](#enums-and-types) + + +Application specifications. + + +## Page Requirements + +This section outlines the specific technical requirements for the application. It is broken down +by page. + + +#### Home + +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, and other (**undetermined**) lists. + +##### UI Requirements +- [ ] Search bar + - [ ] Ability to search for recipes, meals, and tags + +- [ ] Filter drop down + - [ ] **Filter by meal** - *breakfast, lunch, dinner, side, any* + - [ ] **Filter by time requirements** - *15min, 30min, 1hr, 1.5hr, +1.5hr* + - [ ] **Filter by difficulty** - *1 to 5 stars* + +- [ ] Make again list + - [ ] Scrolling list of the most recent 5-10 recipes **made** + - [ ] **How do we determine what recipes were made?*** + - [ ] **Display recipe details** - Title, duration, **image***, and a heart to like the recipe + +- Another scrolling list* + + +'*': Not sure yet, still under consideration + + +##### API Requirements + +- [ ] 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 + +- [ ] Make again list + - [ ] Fetch a list of recently made meals** + - [ ] Like a post and store it in user's liked posts list + + +'**': Not sure implementation + + + +#### Favorites + + + + + + + +#### Create + + + + + + + +#### 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 `BIGSERIAL` 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. + +- [ ] Recipe: Represents a single recipe. + - [ ] ID (PK) BigSerial + - [ ] Title (Unique, 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](#enums-and-types) section) + - [ ] Ingredients (Required) JSONB({ "item_a": [{ "name": string, "quantity": string }], "item_b": ... }) + - [ ] UserId (FK: User.Id) BigSerial + - [ ] Modified () date/time stamp + - [ ] Created (Required) date/time stamp + +- [ ] User: Represents a single user. + - [ ] ID (PK) BigSerial + - [ ] Name (Required) string(64) + - [ ] Email (Unique, Required) string(128) + - [ ] Password (Required) string(128) *stored as hash*** + - [ ] Created (Required) date/time stamp + +- [ ] Engagement: Represents a single engagement from a single user. + - [ ] ID (PK) BigSerial + - [ ] Message () text (Used to store any relevant notes, if needed) + - [ ] Entity (BigSerial) BigSerial (Used to relate an entity, if needed) + - [ ] UserId (FK: User.Id, Required) BigSerial + - [ ] Created (Required) date/time stamp + +- [ ] Like: **Many-to-many** table to represent a list of recipes liked by a user. + - [ ] ID (PK) *Composite key*** + - [ ] UserId (FK: User.Id, Required) BigSerial + - [ ] RecipeId (FK: Recipe.Id, Required) BigSerial + - [ ] Created (Required) date/time stamp + +- [ ] Tag: Represents a single tag that can be had by many recipes. + - [ ] ID (PK) BigSerial + - [ ] Name (Unique, Required) string(32) + - [ ] Created (Required) date/time stamp + +- [ ] RecipeTag: **Many-to-many** table to represent a list of tags on a recipe. + - [ ] ID (PK) BigSerial + - [ ] RecipeId (FK: Recipe.Id, Required) BigSerial + - [ ] TagId (FK: Tag.Id, Required) BigSerial + - [ ] Created (Required) date/time stamp + +- [ ] List: Represents a single users shopping list. + - [ ] ID (PK) BigSerial + - [ ] UserId (FK: User.Id, Required) BigSerial + - [ ] Content (Required) JSONB([ { "name": string, "quantity": string }, ... ]) + - [ ] Created (Required) date/time stamp + +- [ ] Image: Represents a single image used by a single recipe. + - [ ] ID (PK) BigSerial + - [ ] RecipeId (FK: Recipe.Id, Required) BigSerial + - [ ] Alt (Required) string(128) (alt text for accessibility, same as recipe title) + - [ ] Url (Required) text + - [ ] Created (Required) date/time stamp + +- [ ] Review: Represents a single review on a recipe from a single author. + - [ ] ID (PK) BigSerial + - [ ] Comment (Required) text + - [ ] Rating () int(0..5) (Optional b/c nested replies don't need a rating) + - [ ] ReviewId (FK: Review.Id) BigSerial (This is used for nested replies) + - [ ] RecipeId (FK: Recipe.Id, Required) BigSerial + - [ ] UserId (FK: User.Id, Required) BigSerial + - [ ] Created (Required) date/time stamp + +- [ ] Notification: Represents a single user notification. + - [ ] ID (PK) BigSerial + - [ ] UserId (FK: User.Id, Required) BigSerial + - [ ] Type (Required) E_Notification + - [ ] Message (Required) text + - [ ] Entity (BigSerial) BigSerial (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 + - [ ] desert: 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