User Stories and Characteristics Demo 4 - COS301-SE-2026/Mealchemy GitHub Wiki
User Stories and Characteristics
Intended Users and System Usage
Home Cook
The primary user of Mealchemy. A home cook uses the app to store recipes in a private vault, manage their personal pantry inventory, create shopping lists, view recipe suggestions based on the ingredients they already have, as well as their preferences, and discover new recipes. They save a profile containing their preferred measurement units, dietary restrictions, allergies, disliked ingredients, available cooking equipment, flavour preferences (cuisine affinities) and nutritional goals so that every recommendation is personalised to them. They use Guided Discovery to swipe through recipe suggestions, watch short cooking videos (Sizzles), and can build a shopping list for the ingredients they are missing after selecting a recipe. They follow recipes step by step using Hands-Free Cooking with cooking timers, and can create shared vaults to share and collaborate on recipes with friends, family, or other users of their choosing.
Shared Vault Member
A home cook who belongs to a shared vault. Each member has one of three roles:
- Owner: created the vault; manages members, invitations and roles, and can add, edit and delete shared recipes, as well as edit the shared meal plan and generate shopping lists from the meal plan.
- Editor: can add, edit and delete shared recipes, as well as edit the shared meal plan and generate shopping lists from the meal plan.
- Viewer: can browse shared recipes but cannot edit them, as well as view the shared meal plan and generate shopping lists from the meal plan. Users who accept invitations join as a Viewer.
Community Member
A home cook who additionally participates in the community repository (global vault). Community members can publish recipes to the global vault, browse recipes shared by others, save those recipes to their own private vault, and report (flag) recipes that violate community guidelines. Every registered user can act as a community member.
Moderator
A privileged user responsible for moderating the community repository. Moderators review flagged recipes, remove recipes that violate community guidelines, and manage the safety and integrity of the shared recipe space. Moderators do not manage individual users' private vaults or pantries.
1. Authentication (Core)
1.1. As a new user, I want to register with my name, email, and password, so that I can create a personal account and access my data across sessions.
1.2. As a returning user, I want to log in with my email and password, so that I can securely access my private vault, pantry, and preferences.
1.3. As a logged-in user, I want to log out, so that my account is protected when I am not using the app.
1.4. As a user, I want my account to be protected against repeated failed login attempts, so that others cannot guess my password.
2. Recipe Vault (Core)
2.1. As a home cook, I want to create my own recipe with a title, description, cuisine, preparation time, cooking time, serving size, ingredients with quantities and units, ordered steps, an optional photo and/or video, and required equipment, so that I can keep all my personal recipes in one place.
2.2. As a home cook, I want to paste a URL from an external website and save it to my vault under My Links, so that I can access recipes I find online without losing them.
2.3. As a home cook, I want to edit or delete a saved external link, so that I can keep my links accurate and remove ones I no longer need.
2.4. As a home cook, I want to browse recipes shared by other users in the community repository (global vault), so that I can discover new meals beyond my own vault.
2.5. As a home cook, I want to save a community recipe directly to my private vault, so that I can access and edit it as my own.
2.6. As a home cook, I want to open any saved recipe and see its overview, ingredients, steps and nutrition in separate tabs, so that I can follow it while cooking without confusion.
2.7. As a home cook, I want to delete a recipe from my vault, so that I can remove recipes I no longer need.
2.8. As a home cook, I want to create and edit folders and move recipes into them, so that I can keep my private and shared vaults organised by categories of my choosing.
2.9. As a home cook, I want to switch between my Private Vault and my Shared Vaults using a vault selector, so that I can navigate easily between them, keeping personal recipes separate from recipes shared with others.
2.10. As a home cook, I want to save a recipe from Recipe Details or Sizzles in a vault folder of my choice, so that I can find it again later.
2.11. As a community member, I want to publish one of my recipes to the global vault, so that others can discover it.
3. Recipe Recommendation (Core)
3.1. As a home cook, I want the app to recommend recipes based on the ingredients currently in my pantry and their freshness, so that I can decide what to cook without manually searching for ideas.
3.2. As a home cook, I want to see clearly which ingredients in a suggested recipe I already have and which I still need to buy, so that I can make an informed decision about whether to cook it.
3.3. As a home cook with dietary requirements, I want the app to use my saved preference profile details when recommending recipes, so that every suggestion is suitable for me to eat without having to re-enter my restrictions each time.
3.4. As a health-conscious home cook, I want the app to use my saved nutritional goals (for example, Low Carb or High Protein) when recommending recipes, so that every suggestion aligns with my goals.
3.5. As a home cook, I want to specify how many people I am cooking for, so that ingredient quantities and nutritional info are scaled to the right portion size automatically.
3.6. As a home cook, I want to watch short cooking videos (Sizzles) and swipe vertically between them, so that I can be inspired and decide what to cook without manually searching for ideas.
3.7. As a home cook, I want to open the full recipe or save it directly from a Sizzles video, and mute or unmute the sound, so that I can act on a video I like.
4. Guided Discovery (Core)
4.1. As a home cook who struggles with decision fatigue, I want to see one recipe suggestion displayed as a card at a time, so that I can focus on a single option without being overwhelmed by a list.
4.2. As a home cook, I want to swipe right (or tap the heart) on a recipe card to indicate I like it, so that the app records my preference and moves me to the next suggestion.
4.3. As a home cook, I want the recipes I like to be saved to my Favourites folder in my private vault, so that I can access them later without having to find it again through the recommender.
4.4. As a home cook, I want to swipe left (or tap the cross) on a recipe card to dislike it, so that I can dismiss recipes that do not interest me and move on quickly.
4.5. As a home cook, I want to skip a recipe card without expressing a like or dislike, so that I can pass on recipes I feel indifferent towards.
4.6. As a home cook, I want to expand a recipe card to see the recipe details, and what ingredients I am missing before deciding whether to like or pass, so that I can make an informed choice.
4.7. As a home cook, I want to filter Guided Discovery by categories such as All, Quick Meals, High Protein and Vegetarian, so that I only see relevant recipes.
4.8. As a home cook, I want to unlike a recipe if I change my mind, so that I do not have to sort through recipes I no longer like to find a newly added one.
4.9. As a returning home cook, I want the discovery feed to surface recipes that better match my taste over time based on my swipe history, so that the app becomes more useful the more I use it.
5. Shopping List (Core)
5.1. As a home cook, I want the app to automatically generate a shopping list containing only the ingredients I am missing for a chosen recipe, so that I know exactly what to buy without cross-referencing my pantry manually.
5.2. As a home cook, I want the option to generate a shopping list containing all the ingredients from a chosen recipe, so that I can buy for a specific meal if I would like.
5.3. As a home cook doing a bulk grocery shop, I want to add missing ingredients from several recipes to a single shopping list, so that I can do one consolidated grocery shop for multiple meals.
5.4. As a home cook, I want to create, open, edit and delete multiple shopping lists, so that I can keep different shopping trips separate.
5.5. As a home cook, I want to manually add, edit and remove items on a shopping list, so that I can adjust the list to my needs.
5.6. As a home cook who is shopping, I want to tick items as purchased, and use Select all or Deselect, so that I can track what I have already bought.
5.7. As a home cook who has just finished shopping, I want to send my purchased items to my pantry with an Update Pantry action, so that my pantry stays up to date and future recipe generation reflects what I now have available.
5.8. As a home cook, I want to delete selected items from a shopping list in one action, so that I can clear items I no longer need.
6. Pantry Inventory (Core)
6.1. As a home cook, I want to add an ingredient to my pantry by selecting it from the ingredient catalogue and entering a quantity and unit, so that the app knows what I currently have available and can generate accurate recipe suggestions.
6.2. As a home cook, I want to view all ingredients currently in my pantry grouped by category, showing the quantity, unit and freshness status of each ingredient, so that I know at a glance what I have available without having to rely on memory and what needs to be used up.
6.3. As a home cook, I want to search my pantry and filter it by category, so that I can quickly find a specific ingredient.
6.4. As a home cook, I want to update the quantity or unit of an existing pantry item, so that my inventory stays accurate after I partially use an ingredient.
6.5. As a home cook, I want to remove an ingredient from my pantry, so that items I have run out of are no longer included in recipe suggestions.
6.6. As a home cook, I want to add a pantry ingredient quickly from my Home dashboard, so that I can update my pantry without leaving the main screen.
7. Recipe Editing (Core)
7.1. As a home cook, I want to update a saved recipe's information such as title, description, cuisine type, preparation time, cooking time, serving size, ingredients, steps, recipe photo and/or video, and equipment needed so that my recipe library stays accurate and well-labelled.
7.2. As a home cook who likes experimenting, I want to duplicate any saved recipe to create an independent copy, so that I can adapt it into a new variant without overwriting or losing the original version.
7.3. As a home cook, I want to see validation messages when I save a recipe with missing or incorrect fields, so that I can correct them before saving.
8. Preference Profile (Core)
8.1. As a home cook, I want to choose Metric or Imperial as my preferred units, so that quantities are displayed in the system I understand.
8.2. As a home cook, I want to set and save my dietary restrictions and critical allergies to my profile, so that I do not have to re-enter them every time I start a discovery session.
8.3. As a home cook, I want to specify ingredients I dislike (aversions) and save them to my profile, so that recipes containing those ingredients are automatically excluded from suggestions.
8.4. As a home cook, I want to select flavour profiles (cuisines) that match my taste and save them to my profile, so that the app uses them to personalise every recommendation.
8.5. As a home cook, I want to specify the cooking equipment I have available, so that the app does not recommend recipes for which I lack the equipment.
8.6. As a home cook, I want to select nutritional goals such as High Protein or Low Carb, so that recommendations reflect my nutritional targets.
9. Nutritional Analysis (Core)
9.1. As a home cook, I want to see the total calories and macronutrients (protein, carbohydrates, fat) as well as other nutrients (for example fibre and sodium) for a recipe, so that I can understand what I am eating.
9.2. As a home cook, I want to switch between per-recipe and per-serving values, so that I can see the values for the amount I will actually eat.
9.3. As a home cook, I want to expand an ingredient breakdown showing each ingredient's contribution, so that I can see what drives the totals.
10. Offline Access (Core)
10.1. As a home cook, I want to browse previously loaded recipes, vaults, discover content, pantry and shopping lists when I have no connection, so that I can still use the app in the kitchen or at the shops.
10.2. As a user, I want a clear offline banner and a "saved X minutes ago" indicator, so that I know I am seeing cached data and how fresh it is.
11. Navigation and Dashboard (Additional)
11.1. As a user, I want a Home dashboard showing a pantry summary, a smart suggestion, and recommended recipes, and my private meal planner, so that I have an overview and shortcuts as soon as I open the app.
11.2. As a user, I want shortcuts from Home to my shopping lists, profile, notifications and help, so that I can reach them from anywhere.
12. Community Moderation (Additional)
12.1. As a community member, I want to report (flag) a recipe in the community repository by selecting a reason, so that a moderator can review and take action on content that violates community guidelines.
12.2. As a moderator, I want to view all recipes that have been flagged by users, so that I can review potentially inappropriate content in one place.
12.3. As a moderator, I want to view the details and report reason of any flagged community recipe, so that I can make an informed decision about whether it should remain in the community repository.
12.4. As a moderator, I want to remove a recipe from the community repository, so that content that violates community guidelines is no longer visible to other users.
12.5. As a moderator, I want to dismiss a flagged recipe that is deemed acceptable, so that it can remain in the community repository.
13. Collaborative Vaults (Wow)
13.1. As a home cook, I want to create a shared vault by giving it a name, so that I can share recipes with other people. I become its Owner.
13.2. As a vault Owner, I want to invite other users to the shared vault by email and cancel pending invitations, so that I control who can join.
13.3. As an invited user, I want to view my incoming invitations and accept or decline them, so that I can choose which shared vaults to join.
13.4. As a vault Owner, I want to view the vault's members and change a member's role (Viewer or Editor) or remove them, so that I can manage who can contribute.
13.5. As a vault Owner or Editor, I want to add recipes and folders to a shared vault and edit shared recipes, so that we can all contribute.
13.6. As an Editor, I want the app to lock a shared recipe while I am editing it, so that two members cannot overwrite each other's changes. If someone else is editing, I want to be told to wait.
13.7. As a vault Viewer, I want to browse shared recipes without being able to edit them, so that I can use the vault without changing it.
13.8. As a home cook, I want to save a recipe that another member has added in the shared vault to my private vault, so that I can access and edit it as my own.
13.9. As a home cook, I want changes made to a shared copy of a recipe not to affect the original in my private vault, so that my personal recipes stay unchanged.
13.10. As a shared vault member, I want an in-app notifications inbox showing invitations, recipe updates, role changes and other vault activity, so that I stay informed about what happens in my vaults.
13.11. As a user, I want to open a notification to go directly to the related invitation, vault or recipe, mark all notifications as read, and refresh the inbox, so that I can act on activity quickly. If I no longer have access, I want to be told.
14. Transparency Cards and Algorithm Personalisation (Wow)
14.1. As a home cook, I want each recommended recipe to show why it matches me (for example pantry match, freshness, cuisine preference, nutritional goals), so that I can trust the recommendation.
14.2. As a home cook, I want the app's understanding of my taste to adapt from my likes, dislikes and skips, so that recommendations improve with use without my having to reconfigure anything.
14.3. As a home cook, I want recipes I dislike to be hidden for a period and recently seen recipes to be shown less often, so that I do not see the same suggestions repeatedly.
14.4. As a home cook, I want to adjust what matters most to me (for example cooking from my pantry, ingredient freshness, cuisine and nutritional goals), so that the recommendations reflect my current priorities.
15. Meal Planning (Wow)
15.1. As a home cook, I want to create a meal plan, so that I can organise what I intend to cook over a period of time.
15.2. As a home cook, I want to add a recipe to my meal plan and allocate it to a timeslot (Breakfast, Lunch, Dinner, or Other), so that I know what I am cooking and when. Each timeslot should validate the time entered and reject any time that falls outside its range.
15.3. As a home cook, I want to view a recipe I have planned, so that I can check its details before I cook it.
15.4. As a home cook, I want to edit a planned entry, so that I can adjust my plan when my circumstances change.
15.5. As a home cook, I want to remove a planned recipe from my meal plan, so that my plan only contains meals I still intend to cook.
15.6. As a home cook, I want to view all planned recipes between a specified start and end date, so that I can see what I have lined up for a particular period.
15.7. As a home cook, I want the app to recommend a recipe based on my pantry and saved preferences, so that I can decide what to cook without manually searching for ideas. Where earlier planned recipes have not yet been cooked, the app should use pantry projection to weigh the pantry match, so that the recommendation reflects what I will realistically have on hand.
15.8. As a home cook, I want to create a shopping list from a single recipe, so that I can buy everything I need for that meal.
15.9. As a home cook, I want to create a shopping list containing all the ingredients from recipes planned between a start and end date, so that I can do one shop for the whole period.
15.10. As a home cook, I want a smart-add option on my shopping list that includes only the ingredients I do not already own, so that I do not buy things I already have. Smart add can only create a fresh list and cannot add to an existing one.
15.11. As a home cook, I want to be asked to confirm before overwriting an existing planned recipe entry, so that I do not accidentally replace a meal I meant to keep.
15.12. As a home cook who shares a vault, I want to create and add to a meal plan in a shared vault, provided I have the right permissions, so that the people I cook with can plan meals together.
15.13. As a home cook, I want only recipes I have access to be addable to my meal plan, so that I never plan a meal I cannot actually view or cook.
16. Hands-Free Cooking (Wow)
16.1. As a home cook, I want to start cooking mode from a recipe and see one step at a time, so that I can follow instructions without scrolling.
16.2. As a home cook, I want the app to read each step aloud, and to pause or replay it, so that I can cook without looking at my phone.
16.3. As a home cook, I want to change the reading speed, so that instructions are spoken at a pace that suits me.
16.4. As a home cook with messy hands, I want to say commands such as "next", "back" and "repeat", so that I can move through the recipe without touching the screen.
16.5. As a home cook, I want a step counter and progress bar, so that I always know where I am in the recipe.
16.6. As a home cook, I want to add multiple named cooking timers while cooking, and pause, resume or cancel each one, so that I can manage several parts of a meal at once.
16.7. As a home cook, I want my active timers and a Continue cooking shortcut on the Home dashboard, so that I can leave the cooking screen and return to my current step.