Control Information

Version

Delivery

Feedback

Deadline

Delivered

Received

Integrated

V1

29-08-2023

29-08-2023

V2

01-09-2023

01-09-2023

V3

15-09-2023

Disclaimer

This document is written as an example of a reasonable requirements document, using the temnplate defined by Bertrand Meyer in his Handbook of Requirements and Business Analysis [1] (2022). It does not has the ambition of being a perfect implementation of this template, as it mixes different sources and methods (e.g., [2]) to fit the objectives of COMPSCI/SFWRENG 3RA3 at McMaster. In addition of the two authors, this document is built on top of the expertise and discussions with Mireille Blay-Fornarino (Université Côte d’Azur), Jean-Michel Bruel (Université de Toulouse), and Richard Paige (McMaster University).

In this document, we use The Firebird as an imaginary client. The objective is to root the document into a concrete example for McMaster’s students, which host since 1969 a restaurant with a similar name. It is important to note that this is a fictional case study.

Authors

Thomas Chiang.

Thomas is a Software Engineering PhD candidate at McMaster University, specialized in model driven engineering, language engineering, and safety engineering. His research interests are about improving safety engineering through model-driven engineering techniques, as well as developing principles for graphical modeling language development. You can reach him at chiangte@mcmaster.ca, and find more information here: https://www.linkedin.com/in/thomas-chiang-908362a1.

Sébastien Mosser, P.Eng., Ph.D.

Sébastien is Associate Professor of Software Engineering at McMaster University. His research interest are related to software engineering, more specifically language engineering and modelling in a DevOps context. He is teaching McMaster’s Requirements Engineering (3RA3) course since Fall 2023, after having taught equivalent courses at Université Côte d’Azur and Université du Québec à Montréal since 2012. You can reach him at mossers@mcmaster.ca, and find more information here: https://mosser.github.io

(G) Goals

Control Information

Table 1. ATCO Eats — Versionning Information — Goal Book
Section Version Lead Delivered on Reviewer Approved on

G.1

Milestone #1

SM

28-08-2023

TC

29-08-2023

G.2

Milestone #1

SM

28-08-2023

TC

29-08-2023

G.3

Milestone #1

TC

29-08-2023

SM

29-08-2023

G.4

Milestone #1

TC

25-08-2023

SM

28-08-2023

G.5

Milestone #2

TC

31-09-2023

SM

01-09-2023

G.6

Milestone #2

TC

30-09-2023

SM

31-09-2023

G.7

Milestone #1

SM

28-08-2023

TC

29-08-2023

(G.1) Context and Overall Objectives

The COVID-19 crisis hit the food and hospitality industry really hard, and restaurants are still recovering from it. By investing in the deployment of a new app, The Firebird Pub & Grill aims to integrate their food offer into McMaster’s community in a seamless way, by interacting with internal information systems for event caterings, as well as providing an ideal support for students' life on campus with mealboxes. Launching this new system will also targets the expansion of the patrons' pool, by focusing on McMaster as part of the Hamiltonian community.

(G.2) Current situation

The Firebird operates as a classical restaurant on campus. Events are organized to attract graduate students, and a patio was added for outdoor seating in the 90’s to increase seat capacity during summer months. Often desribed as Hamilton’s hidden jewel, its location does not help to attract external patrons (e.g., no parking). Local patrons would consider it as any restaurant in the area: for example, staff cannot order catering for events through Mosaic, and have to consider it as any other invoice.

(G.3) Expected Benefits

The expected benefits of this app primarily center around increasing the on campus population. Despite the fact that Covid-19 is mostly under control, people are still generally shy to go out and be in person on campus with all of the new infrastructure allowing them to complete many of their tasks for school from the comfort of their home. However we have seen a sharp increase in people enjoying going out with their friends and family once the pandemic restrictions were lifted. Therefore the largest benefit that this app can bring is an increase in the on campus population. This is enabled for students by having the new take-out box system that allows students to order whenever and pick up warm and delicious food between classes easily as well as accepting student meal plan cards. It is also enabled by the integration with Mosaic to facilitate payment from departments and faculty for catering for events which can entice more people to be present for in-person events to enjoy the delicious food from the Firebird. Finally the loyalty program will incentivize repeat customers so that they can enjoy complimentary benefits at the Firebird! (note that the exact nature of the benefits has not been determined at the time of creating this document and will be refined at a later date.)

The goals that present these benefits, as well as the stakeholders that they affect can be seen in this goal model diagram:

goal model.drawio
Figure 1. Goal model for the app

(G.4) Functionality overview

The high level functional requirements for the application based on client input can be defined as follows in no particular order:

  • Integration with campus staff. Client wants to be able to leverage the location of The Firebird to allow McMaster’s staff to order food for events directly through their internal information system and automatically support billing (instead of staff paying with their credit card and then submitting an expense report). This can be done primarily through Mosaic or something like Mosaic

  • Integration with campus life. Client wants the app to facilitate student life ie. Enable students to easily access food in between classes and during busy periods like midterms and exams. This can be done by enabling food order in boxes and quick pickup in restaurant.

  • Attacting new customers. Client hopes to use the app to encourage repeat customers. A loyalty program or card was given as an example to encourage patrons to enjoy The Phoenix patio during the summer, as well as points acquisition for potentially free appetizers during a visit.

  • Device Compatibility. To reach the broadest possible audience, the app that is being developed to be available across multiple operating systems and environments (Apple, Android, web browser).

  • Accepting meal plan cards As part of the clients desire to integrate with Campus, having a payment method that accepts credit, debit, and student meal cards is critical to the functionality of the app.

Of these functional requirements, 2 that are of critical importance is the integration with campus staff and integration with campus life. Integration with campus staff is critical to facilitate catering services of The Phoenix across campus through various system integrations. One of the main goals of the integrations is to reduce burden on staff for ordering catering services by having to pay out of pocket and then seek reimbursement from their department or faculty. Integration with campus life is another critical requirement to enable students to more efficiently get quality meals during particularly time-constrained periods of their studies, thus improving their quality of life during their stay at McMaster.

Some high level non-functional requirements for the application can be defined as follows in no particular order:

  • Compliance with McMaster University by-laws

  • Compliance with Ontario alcohol service laws and regulations

These two non-functional requirements critical for legal reasons. As The Phoenix is on McMaster property, it must comply with the by-laws created and enforced by the university. As The Phoenix is also a bar with a liquor license it is also critical that they operate their business with respect to the by-laws and regulations of the Ontario Government.

(G.5) High-level usage scenarios

use case diagram
Figure 2. High Level use cases diagram

The use case diagram above highlights how we anticipate our direct stakeholders will interact with the app for the principal use cases. More details for these usages are as follows:

  • UC1: Order food.

    1. Customer (hamilton citizen and by extension community member) opens the app to order food

    2. Customer accesses the meal box menu

    3. Customer goes through menu looking for food

    4. Customer finds food and places order for meal boxes

    5. Customer pays for food

  • UC2: Receive "order status" update.

    1. The system pushes a notification when an order has been received

    2. The system pushes pushes another notification when the payment is completed

    3. The system sends a receipt to the customer

    4. Line cook marks when food cooking is complete

    5. The system pushes notification for food cooking complete

  • UC3: Pay for food.

    1. The system determines the price of the order (including loyalty rewards and green box discounts, if any)

    2. Customer select their payment type.

    3. Payment is submitted to the right provider (External or Internal) to be processed.

  • UC4: Submit catering invoice.

    1. The restaurant receives catering order by traditional means (e.g. email, phone)

    2. The restaurant processes the catering order using their regular process

    3. Restaurant manager creates an order and select INTERNAL as payment type

    4. They fill out the required accounting information provided by their client

    5. They save the order in ATCO Eats, which transmit it to Mosaic for payment

  • UC5: Check sales reports.

    1. Restaurant manager opens web-portal to access app

    2. Restaurant manager accesses sales for the day

    3. Restaurant manager generates sales report

    4. App prompts manager to save report to local machine

  • UC6: Finalize Order.

    1. The line cook has a list of meal boxes to prepare for the next pickup slot

    2. When they have finished their current batch, they push a button to change their status to READY

(G.6) Limitations and Exclusions

Below is a list of limitations that the system will not do:

  • System will not integrate with social media to do advertising or allow cross-posting

  • System will not be responsible for checking if food has been picked-up by customer. Once the food ready alert has been sent out system role is over.

(G.7) Stakeholders and requirements sources

Table 2. Stakeholders for ATCO Eats
Stakeholder Persona Category

Patrons

Community member

Cameron

Direct

Citizen of Hamilton

Carter

Direct

Indirect Customer

Administrative Assistant

Logan

Direct

Restaurant staff

Restaurant Manager

Drew

Direct

Line Cook

Dylan

Direct

Mosaic Operational Maintainers

Indirect

Payment Gateway operators

Indirect

McMaster Senate

Indirect

(G.7.1) Direct Stakeholders

Patrons

Patrons directly interact with The Firebird, by booking tables and participating to events organized by the restaurant (e.g., Trivia night on Tuesdays). They can be refined into community members, already on McMaster campus (supporting the objective of better integrating with the community), and citizens of Hamilton (supporting the objective of extending the pool of patrons).

Cameron (Community member)

Cameron is a grad student in Engineering, splitting their time between working on campus as a teaching assistant and their research work on biomedical nano-robots. They are not living on campus, and coming to Mac is a 25 minutes commute. They are on a tight budget, and cannot afford eating out too often. They enjoy spending time with their friends (other grad students, or from outside McMaster).

Carter (Citizen of Hamilton)

Carter lives in Stoney Creek, and work as an assistant manager in a local grocery store. With their partner, they have two teenage children, and enjoy spending quality time together dining in nice restaurants. They are not necessarily looking for fancy food, but more for nice, fun and positive atmosphere for their monthly family dinner.

Indirect customer

Indirect customers are staff members who classicaly book catering or tables on behalf of other members. They usually do not participate to these events: they are handling the booking, then a faculty/staff member would pay the bill and submit an expense report. They have then to fill out and validate such report with Account Payable.

Logan (Administrative Assistant)

Logan works as an administrative assistant at McMaster Centre for Awesome Research on Everything (CARE) since 2016, helping out a group of 12 professors. When CARE organizes events or conferences, they are in charge of organizing the agenda, including ordering food for breaks. They are also in charge of organizing the itinerary when guests are hosted by CARE, including booking restaurants for dinners. They usually only work with providers able to submit invoices directly through Mosaic to lighten their workload.

Restaurant Staff

Restaurant staff are directly impacted by ATCO Eats, from the front-house (e.g., welcoming patrons, taking orders) to the back-house (preparing food ordered through the app).

Drew (Restaurant Manager)

Drew started working at The Firebird in 2022, with the great re-opening as part of the Back to Mac operation. With 10+ years of experience in restaurant management in the GTA, they were hired to help adapt The FireBird to its new post-covid operational context. They are known for their direct management style, favoring problem-solving over finger pointing.

Dylan (Line Cook)

Dylan has worked as a line cook at The Firebird since 2019. Preparing tasty food that patrons will enjoy is really important for them, that’s why they were a little bit skeptical when they heard top-management starting to talk about "meal boxes". They fear that such approaches might jeopardize the quality of food they like to serve.

(G.7.2) Indirect Stakeholders

  • Mosaic Operational Maintainers: As ATCO Eats will be integrated into Mosaic, it needs tro comply to operational constraints required by Mosaic for integration purposes.

  • Payment Gateway operators: ATCO Eats will support payment mechanisms, and as such will have to interact with payment service providers such as Stax, Stripe, …​

  • McMaster Senate: The Senate is in charge of voting by-laws that might influence the operations of ATCO Eats

(G.7.3) Requirements Sources

(E) Environment

The Environment book describes the application domain and external context, physical or virtual (or a mix), in which the system will operate. [1]

Control Information

Table 3. ATCO Eats — Versionning Information — Environment Book
Section Version Lead Delivered Reviewer Approved

E.1

Milestone #1

SM

28-08-2023

TC

29-08-2023

Milestone #2

SM

31-08-2023

TC

01-09-2023

E.2

Milestone #2

SM

29-08-2023

TC

30-08-2023

E.3

Milestone #2

TC

30-08-2023

SM

31-08-2023

E.4

Milestone #2

TC

30-08-2023

SM

31-08-2023

E.5

Milestone #1

TC

25-08-2023

SM

28-08-2023

E.6

Milestone #1

TC

25-08-2023

SM

28-08-2023

(E.1) Glossary

(E.1.1) Vocabulary

Catering Services

McMaster operates its own internal catering system, in compliance of the by-laws controlling food operations on campus grounds. Extensive information of Catering operations can be found here: https://hospitality.mcmaster.ca/catering-gifts/catering-services/

Green Box

As part of McMaster sustainability program, Community member can subscribe to a reusable container program. More information available here: https://hospitality.mcmaster.ca/wellness-sustainability/sustainability/choose-to-reuse/reusable-containers/.

MacID

Mac ID is the local Single Sign On (SSO) deployed as McMaster as a unique and centralized way to support authentication among the different apps used by the university (e.g., Mosaic, Avenue to Learn)

McMaster community

McMaster’s community includes Staff, as well as students (undergrad and graduate ones).

Meal Box

New offer available at The Firebird. It consists in pre-made meals that are designed to be affordable, healthy and balanced, allowing McMaster Community to focus on their busy life and not on cooking meals. A meal box includes a small starter, a main dish, and a dessert. Boxes are cooked to order to ensure freshness and meal quality.

Meal Plan

The meal plan is an opt-in option that the majority of students who live in residence take to get meals, and is continually offered to all students. They are able to prepay money to their Mosaic account and use their student card to purchase food on campus, or other local restaurants that accept student meal plans as a form of payment.

Mosaic (Information System)

Mosaic is McMaster’s internal portal. It acts as a unique entry point aggregating each and every tool used to support McMaster’s community. Students use it for course enrollment, staff for expense reports, faculty for accessing class rosters. Acting as a portal, it covers Student Administration, Finance, HR, Research Administration, and Facilities Maintenance Management.

Staff

When referring to staff, this document refers to persons employed by McMaster to support its operations, who might commit to expenses in food and hospitality. This generally includes administration staff and full-time faculty members.

University Technology Service

McMaster internal IT service, in charge of operating its technological infrastructure. It includes, among others, MacID, Mosaic, Avenue to Learn (course management system).

(E.1.2) Domain Model

domain model
Figure 3. Domain Model for ATCO Eats

(E.2) Components

The system interacts with two external components:

  • Mosaic: The component hosted by UTS and providng services related to McMaster processes, such as meal plan and supporting internal billing. This legacy compomnent is out of scope for ATCO Eats, which needs to interact with it.

  • Payment Gateway: The component implementing the interface from the payment provider used to process payments (Visa, Mastercard, GoogleWallet, ApplePay). As the provider is not selected yet, we assume here a "global" interface which is compatible with out preliminary study of the provider market.

(E.3) Constraints

  • Interactions with Mosaic: To support a meal plan debit, ATCO Eats needs to send a request for payment to the system Internal billing works the other way around: the system exposes an endpoint providing pending invoices, and periodically Mosaic collect them and start the accounting reconciliation process.

  • Mobile support: The system must work with classical smartphone, i.e., Apple and Android devices and comply with app store policy.

  • Internet support: The system must work with internet browsers (i.e., Chrome, Safari, Edge) to support staff and in the event that customers do no wish to download the app.

(E.4) Assumptions

Some assumptions made can be found below:

  • Operating system support: We assume that we will have to support mobile operating systems that are still supported by mobile companies (iOS 15 and Android 11 at the time of writing).

  • Internet browser support: We assume that we only need to support three major internet browsers (Edge, Chrome, Safari).

  • Integration with existing restaurant infrastructure: We assume that for the minimum viable product for this application we do not need to integrate with pre-existing systems for sales reporting and inventory tracking.

(E.5) Effects

Some of the potential effects of the application can be defined as follows:

  • Increase in student happiness, health, and morale. This is possible due through the facilitation of access to food, preventing students from having to make the choice to eat or attend class. It can also promote more social interactions among the student population through easier catering options or just promoting more attractions of the The FireBird.

  • Increase in on-campus student population. This is possible as the app may promote more reasons for students to be on campus through the loyalty program that rewards them for their in person patronage, even if it’s just by picking up their orders.

  • Increase in events on campus. This is possible through integration with staff on campus and allowing seamless payment through departments, faculties, and clubs. This would also promote competition on campus, potentially allowing for better prices on catering for events or better quality food for catered events.

(E.6) Invariants

Some Invariants of this system can be defined as follows:

  • The Firebird will operate specifically within the McMaster University Campus, on land owned by McMaster

  • The Firebird can assume that McMaster will be responsible for their own systems, outside of the application being developed for The Firebird

  • The Firebird can assume that there will always be patrons under the legal drinking age based on the legal drinking age set by the Ontario Government

(S) System

the System book refines the Goal one by focusing on more detailed requirements.

Control Information

Section Version Lead Delivered Reviewer Approved

S.1

Milestone #2

SM

29-08-2023

TC

01-09-2023

S.2

Milestone #2

TC

31-08-2023

SM

01-09-2023

S.3

Milestone #2

SM

31-08-2023

TC

01-09-2023

S.4

Milestone #2

TC

31-08-2023

SM

01-09-2023

S.5

S.6

Milestone #2

SM

01-09-2023

TC

01-09-2023

(S.1) Components

The system relies on the following four software components:

  • Patron Manager: The component in charge of managing the patrons database (Manage Patrons), as well as providing services related to the loyalty program (Loyalty). It centralizes the business logic related to customer management in ATCO Eats.

  • Menu Provider: The component in charge of exposing the menu to the patrons using the system. It exposes an administration interface (Manage Menu), as well as a way to seach for items (Lookup). The component focuses only on what is available for ATCO Eats, and will not contain 100% of the restaurant menu.

  • Order Manager: The component in charge of processing orders made through the system (Process Order). It implements the business logic related to selling goods (mealboxes or catering services), and listing elements to be cooked by the kitchen (List Impeding).

  • Billing: The component acting as an integrated gateway to external payment services (Process Payment) and internal meal plans (MealPlan Payment). It also exposes a way to collect Pending Invoices when requested, to support interaction with Mosaic.

In addition to these components, the system will interact with two external components to support integration with Mosaic and payment processing (see E.2 for details).

Patrons use Client-App (a mobile application) to interact with the system, for the loyalty program as well as ordering meal boxes. this application can also be accessed in a web browser. Restaurant staff use a web-based system named Web-Portal to administrate the system (patrons database, catering orders). It is important to note that Administrative Staff does not interact directly with the system, and will continue ordering catering or booking tables by phone or email

component mobile
Figure 4. Components involved in ATCO Eats mobile app
component web
Figure 5. Components involved in ATCO Eats administration (web) app

(S.2) Functionality

(S.2.1) Patron Manager

Functional Requirements
  1. Sign-up service: Patron manager shall allow customers the option to sign-up and create an account to gain access to the loyalty program. (F211)

  2. Log-in/out service: Patron manager shall allow customers to login and logout when desired without losing any points previously earned. (F212)

  3. Check loyalty status: Patron manager shall allow customers to check the status of their loyalty points including points until next available reward. (F213)

  4. Password recovery: Patron manager shall allow customers to recover password in the event they have forgotten their account credentials. (F214)

Non-Functional Requirements
  1. Password encryption: Patron manager shall encrypt passwords during login/sign-up process. (NF211)

  2. Personal Data Privacy: Patron Manager shall ensure that the patron database is not accessible outside of the restaurant management team. (NF212)

(S.2.2) Menu Provider

Functional Requirements
  1. Provide menu: Menu manager shall provide customer with access to the menu so that they can choose their desired item for order. (F221)

  2. Search through menu: Menu manager shall provide customer with the ability to lookup specific items in the menu. (F222)

  3. Update menu provider: Menu manager shall provide an interface to staff to update the menu with new items or remove old ones. (F223)

  4. Select menu item: Menu manager shall allow customers to select the items that they wish to purchase. (F224)

Non-Functional Requirements
  1. Accessibility: Menu manager shall be compatible with screen readers and other accessibility services available on client side. (NF221)

  2. Pictures of food: Menu manager shall provide some pictures of menu items to entice customers to purchase food that looks particularly delicious. (NF222)

(S.2.3) Order Manager

Functional Requirements
  1. Complete food order (Process Order): Order manager shall provide customer with an interface to complete food order purchase. (F231)

  2. Receive food order: Order manager shall provide line cook with ordered list of food that requires cooking and preparation (if required). (F232)

  3. Food order complete: Order manager shall provide line cook with interface to state when food cooking is complete.

  4. Food order complete notification Order manager shall prompt user with notification when food is ready for pickup. (F233)

  5. Catering order (Process Order): Order manager shall provide contact information to staff that wish to order catering for an event. (F235)

Non-Functional Requirements
  1. Push notifications: Order manager shall by default enable push notifications from the app (mobile app specifically) to customer smartphone. (NF231)

  2. Device operating system security compliant: Order manager shall send notifications to user smartphone only in compliance with security settings on user device. (NF232)

(S.2.4) Billing

Functional Requirements
  1. Order payment (Process Payment): Billing shall provide user with an interface to pay for their order using an external payment service. (F241)

  2. Order payment (Pending Invoices): Billing shall provide restaurant manager with an interface to create invoices for catering orders using department number of faculty. (F242)

  3. Sales reports: Billing shall provide restaurant manager with an interface to request and review sales reports though the app. (F243)

  4. Use loyalty points: Billing shall prompt user if they want to use loyalty points (if they have enough) before completing payment. (F244)

Non-Functional Requirements
  1. Secured Communication: Billing shall ensure secured communication with external (Debit, Credit, Interac) and internal (meal plans, catering) payment services, using state-of-the-art protocols validated with partners. (NF241)

  2. Tax and accounting compliant: Billing shall comply with accounting regulations set by McMaster University, the Ontario Government, and the Government of Canada. (NF242)

(S.3) Interfaces

(S.3.1) APIs

The ATCO Eats system only offers one API to the external world: PendingInvoice. This interface is used to integrate the system with Mosaic, which will regularly pull pending invoices and start payment processing.

external API
Figure 6. External API exposed by ATCO Eats
  • The interface exposes one single operation, to list the pending invoices.

  • The system shall receive a single argument, being an authentication token which grants access to the system

  • The system shall answer with all catering orders with payed? attribute being false and status being DELIVERED.

(S.3.2) Wireframe Mockups

We focus here on the two parts of the system that differs the most from "classical" food ordering systems such as DoorDash or Uber Eats.

(S.3.2.1) Impeding Orders (Line Cook)

The Line Cook stakeholder (Dylan) needs to have quick access to the next batch of mealboxes to prepare (to ensure good quality of freshly prepared food). As they are working in a kitchen, they cannot rely on classical "tablet-like" interfaces that would requires clean hands. As such, they need to interact with a Flush! physical push button located in the kitchen that automaticallt update the status of the ordered food on their behalf.

Impeding Order
Figure 7. Line Cook: Impeding Order Screen
(S.3.2.2) Submit Catering Invoice (Restaurant Manager)

The Restaurant Manager fills out all the information provided by the Administrative Assistant using traditional means (e.g., phone, email). Then, they submit the invoice on their side, and wait for the payment to be processed by Mosaic. The interface shall allow the restaurant manager (Drew) to submit the information expected by McMaster’s accountant to process the invoice (see the domain model, E.1) .

Submit Catering
Figure 8. Restaurant Manager: Submitting Catering Invoice

(S.4) Detailed usage scenarios

(S.4.1) Ordering food from the app

  • Use Case: UC1, UC2, UC3

  • Primary Actor: Community member

  • Precondition: Community member has internet access and the app downloaded

  • Trigger: Community member wants to get some food in between classes

  • Main Success Scenario

    • 1. Community member opens the ATCO Eats app.

    • 2. App offers mealbox menu options for the Community member to choose from.

    • 3. Community member uses the lookup function to find food that they want.

    • 4. Community member selects food and then goes to checkout.

    • 5. Community member specifies pickup time. Default is ASAP.

    • 6. Community member pays for food using credit card. Payment success and order goes through.

    • 7. After some time Community member receives notification that food is ready.

  • Secondary Scenarios

    • 1.1. Community member creates a new user account.

    • 1.2. Community member logs into already existing account if not already logged in.

    • 5.1. Community member pays using McMaster ID card.

    • 5.2. Upon successful payment, Community member decides to save payment information to account for next purchase.

    • 5.3. If community member already has an account, prompt community member to use loyalty points to pay for food.

    • 5.4. Payment is rejected, Community member is unable to complete purchase.

  • Success Postcondition: Community member receives email for purchase and notification when food is ready.

This scenario is important as it demonstrates how community members are most likely to interact with the app in order to get food and meet the demands of their busy schedules. We can expect them to have multiple different payment methods, and change they’re dining plans on a whim if class gets cancelled or they decide to skip class because they are exhausted.

activity order food
Figure 9. Activity diagram for 'Ordering food from the app'

This diagram helps to explain this usage scenario as it helps us to see all the different decisions that happen during this scenario. These will very likely turn into if statements for the software development. It also covers the "guest" mode descriobed by the fourth scenario.

(S.4.2) Line cook using the app (for impending order and finalizing cooking)

  • Use Case: List Impending Food Orders (S.3), UC6.

  • Primary Actor: Line cook

  • Precondition: Line cook is already at station preparing food

  • Trigger: Customer inputs new order

  • Main Success Scenario

    • 1. Line cook receives sound notification for new meal box order.

    • 2. the app puts it in cooking queue.

    • 3. Line cook begins preparing food for order.

    • 4. Upon completion, line cook places food in box for pickup and marks order as complete in system.

  • Secondary Scenarios

    • 4.1. Customer arrives prior to completion, wants to eat in restaurant instead of take-out.

    • 4.2. Line cook puts food on plate instead of box and hands off to waitress.

This scenario is important as it demonstrates the potential workflow that a line cook might take to integrate online orders with in-person orders. We can expect that they will want minimal contact with the app so having it be a one button scenario is good so that they can focus on cooking.

(S.4.3) Usage Scenario 3: Submit catering order

  • Use Case: UC4

  • Primary Actor: Restaurant manager

  • Precondition: Admin assistant has already called and placed order for food and has catering order number

  • Trigger: Admin assistant wants to use Department number to pay for the catering order

  • Main Success Scenario

    • 1. Restaurant manager opens the ATCO Eats web-portal.

    • 2. Restaurant manager logs in.

    • 3. Restaurant manager navigates to the catering section of the app.

    • 4. Restaurant manager inputs catering order number into the app. App then displays payment process screen.

    • 5. Restaurant manager prepares invoice for the catering event

    • 6. Restaurant manager sends invoice to Mosaic through web-portal.

    • 7. Restaurant manager begins to prepare for catering event

  • Secondary Scenarios

    • 4.1. Admin assistant inputs wrong catering order. Reject order.

    • 4.2. Restaurant manager inputs wrong catering order number. Redo invoice

    • 5.1. Admin assistant inputs wrong department number. Reject payment

    • 5.2. Restaurant manager inputs wrong department number. Redo invoice.

  • Success Postcondition: Admin assistant receives email for catering service payment receipt.

This scenario is important as it demonstrates the potential workflow that an admin assistant might take to pay for catering services. This shows how it can be easier to pay for catering services if the app is integrated with Mosaic and able to access department accounts to withdraw the required money.

(S.4.4) Hamilton Citizen wants to eat at the Firebird

  • Use Case: UC1, UC2, UC3

  • Primary Actor: Hamilton citizen

  • Precondition: Hamilton citizen is on picnic at Cootes

  • Trigger: Hamilton citizen is hungry

  • Main Success Scenario

    • 1. Hamilton citizen opens browser to look for food options during picnic because they didn’t pack enough.

    • 2. Citizen find the Firebird is nearby, navigates to ATCO Eats app website (Client-App).

    • 3. Citizen goes through mealbox menu to find options that they might enjoy and drinks that they crave.

    • 4. Citizen access the app as a guest (no account), order boxes and pay.

    • 5. Citizen decides to run to restaurant as soon as and then goes to play road hockey.

  • Secondary Scenarios

    • 2.1. Citizen doesn’t know how to navigate to app website, - gives up and goes to Subway.

    • 3.1. Citizen doesn’t like options, gives up and goes to Grain&Grit.

    • 4.1. Citizen is differently-abled, rolls up to the Firebird instead, popping wheelies out of excitement.

  • Success Postcondition: Hamilton Citizen dines at restaurant and loves food.

This scenario is important to show why having a website as well as downloadable application to attract more customers to the restaurant. As not everyone who is on campus is necessarily a community member, having someway to be discovered and learn more information about the restaurant is critical for attracting curious customers.

activity browse
Figure 10. Activity diagram for "Hamilton Citizen wants to eat at the Firebird"

This diagram helps to explain this scenario as it justifies the existence of the app on the internet for not just staff but users too. It help to show the importance of online presence for attracting more customers, satisfying one of the goals of having more customers.

(S.4.5) Restaurant Manager checks sales report

  • Use Case: UC5

  • Primary Actor: Restaurant manager

  • Precondition: Restaurant manager is at computer

  • Trigger: End of the day and manager needs to tally up sales for the day

  • Main Success Scenario

    • 1. Restaurant manager opens up ATCO Eats app in browser on computer.

    • 2. Restaurant manager logs in.

    • 3. Restaurant manager navigates to sales tab.

    • 4. Restaurant manager clicks on 'generate sales report'.

    • 5. App summarizes sales for the day in easy to use and read format.

    • 6. App prompts restaurant manager to download and save report to local computer.

    • 7. Restaurant manager closes app and then prints sales report document.

  • Secondary Scenarios

    • 6.1. Restaurant manager views sales report on computer and hates report. Ignores problems and blames staff.

  • Success Postcondition: Restaurant manager has sales report document on local machine and physical copy.

This scenario is important as the restaurant manager will need to see the sales reports of the day/week/month to determine current success of app and restaurant. These sales reports are a major part of what makes the app useful as it will be able to generate these reports on command for a desired time frame in order to summarize information critical to the success of the restaurant.

(S.5) Prioritization

Nothing available (yet).

(S.6) Verification and acceptance criteria

For the functional requirements, the validation will be done during development through acceptance testing. Acceptance testing will complement unit testing by providing a way to express and automate feature validation using the Gherkin Language. Early validation will be supported by the definition of mock-ups and their validation by relevant stakholders (see S.3 for an example with the Line Cook stakeholder). As part of the release process of ATCO Eats (see P.3 for release milestones), we will organize pre-deployment acceptance workshop(s) involving key personel from The Firebird, as well as representative instances of our other patrons-related personas.

For the non-functional requirements:

  • User Privacy: We will take measures when designing and developing ATCO Eats to integrate a privacy by design approach, leveraging visibility and encryption at the code level. This effort will be validated by an internal audit as part of the release process.

  • Encrypted Communications: Communications with Mosaic as well as payment gateways (see E.2) needs to ensure secured payment. The implementation will follow good practices in the field (evaluated by internal code reviews), and an internal audit will be conducted as part of the release process.

  • Accessibility: Developers will validate when delivering user interface related features that they are compliant with the accessibility checklists identified in G.7. This audit will be part of the pull request that integrates the new feature into the product.

  • Respect of accounting rules: as we don’t have an accountant (direct) stakeholder, we will rely on information available in the Account Payable policies and the knowledge of our Admin Assistant (Logan) to create a formal checklist of mandatory elements to be transmitted to Mosaic as part of the payment process. This will be automatically validated by dedicated unit tests.

(P) Project

Control Information

Section Version Lead Delivered Reviewer Approved

P.1

P.2

P.3

P.4

P.5

P.6

Milestone #1

TC

29-08-2023

SM

29-08-2023

P.7

Milestone #1

SM

29-08-2023

TC

29-08-2023

(P.1) Roles and personnel

This section is a DRAFT

  • Security expert

  • Product Owner

(P.2) Imposed technical choices

This section is a DRAFT

  • Multiplatform (mobile/web) for client application

(P.3) Schedule and milestones

Nothing available (yet).

(P.4) Tasks and deliverables

Nothing available (yet).

(P.5) Required technology elements

This section is a DRAFT

  • Compliance with external API for Mosaic

  • Compliance with external API for Payment Gateway

  • IoT physical button to supportt LineCook

(P.6) Risk and mitigation analysis

Some of the risks present during development are listed below:

  • Difficulties integrating with Mosaic. One major aspect of this project is integration with existing infrastructure at McMaster. Thus this will require close work with the system administrator for Mosaic. In the event that documentation on the system is poor, or it becomes difficult to get a representative to work with it can be extremely difficult to accomplish the integrations on schedule. One mitigation strategy for this would be to start working on integration from the start of the project, in parallel to the actual application. This would allow more time to documentation to be provided, and ideally allow for more flexibility to get a representative from the administration team to assist with the integration without taking away too much time from their primary responsibilities.

  • Competition with Heavenly catering. Heavenly catering already has a monopoly for catering on campus. Thus they can present a hurdle to the completion of the application by attempting to stall it or get it shut down altogether. This can be mitigated by involving high level McMaster administration to ensure that we have the university support for developing the application, as well as getting support from various faculty to support more competition for catering services on campus.

(P.7) Requirements process and report

We will rely on interviews to interact with direct stakeholders indentified in G.7. For each stakeholder, we identify the kind of interview, and the most important question to be asked.

  • Community member (Cameron):

    • Type of interview: Closed. The objective is to gather structured information about how the person interacts with the Firebird.

    • Question: "When looking for a place to eat on campus, what are the 5 key decision factors for your choice?". We are targetting the local community, and want to understand what they are looking for.

  • Citizen of Hamilton (Carter):

    • Type of interview: Open. The objective is to collect as much information as possible on how hamiltonians select new restaurants to try out.

    • Question: "When looking for a new restaurant, what are you looking for?". We will use this question as an opener and bounce between the different topics the interviewee might raise to gather as much feedback as possible.

    • Remark: Based on preliminary interviews, we could build a survey to validate the collected data at scale.

  • Administrative Assistant (Logan):

    • Type of interview: Closed. We want to identify precisely what drives the decision of chosing one catering partner over another oner.

    • Question: "When ordering catering, what aspects affect your choice of one provider instead of another?". We will use this question to get information related to motivational choice (as the pain point of expense report was already identified).

    • Remark: The expense report pain point is assumed, but might have to be validated at some point.

  • Restaurant Manager (Drew):

    • Type of interview: Closed. We want to validate the results of the Ideation Workshop Report (Appendix A) by zooming in the remaining ambiguities.

    • Question: "Can you elaborate a process that would support the Loyalty Program identified during the workshop?". This question help to clarify the ambiguity existing around this feature.

  • Line cook (Dylan):

    • Type of interview: Open. We want to understand their line of work as part of the kitchen staff, and how introducing meal boxes could impact their work.

    • Question: "How is your shift organized in the kitchen?". This question is essential to understand the daily routine of a line cook, as this is a particular expertise that none of the project developers have.

References

  • [1] Bertrand Meyer. Handbook of Requirements and Business Analysis. Springer. 2022.

  • [2] Ian Sommerville and Peter Sawyer. Requirements Engineering: A good Practice Guide. Wiley. 1997.

Appendix A: Interaction with the Client

The first two sections of this chapter are extracted from a version of this requirement document originally written by ChatGPT.

First Contact

Subject: Collaboration Inquiry - "ATCO Eats" Food Ordering App

Dear ACME sales team,

We hope this email finds you well. The Firebird Management Team is reaching out to explore the possibility of collaborating with your esteemed team for the development of our upcoming food ordering app, "ATCO Eats." We are impressed by your expertise in software development, particularly in the food industry, and believe your skills align perfectly with our project requirements.

The primary objective of "ATCO Eats" is to offer a user-friendly and feature-rich platform that enhances our customers' food ordering experience. Key functionalities include seamless order placement, real-time tracking, secure payment processing, and a comprehensive loyalty program. We are confident that your contributions will play a vital role in transforming this vision into a practical and successful application.

Should you be interested in pursuing this collaboration, we kindly request your availability for an initial meeting to delve deeper into the project scope and discuss potential collaboration terms. Your professionalism and expertise will undoubtedly be an asset in the development of "ATCO Eats." We eagerly await your response and the opportunity to work together.

Best regards,

The Firebird Management Team

First Meeting with Client (Minutes)

Date: August 1, 2023

Attendees: The Firebird Management, Project Team Members

Agenda: Requirements Gathering for Food Ordering App - ATCO Eats

Meeting started at 02:15PM.

Meeting Summary:

On August 1, 2023, The Firebird Management and the project team members convened for the first meeting to discuss the requirements for the development of the "ATCO Eats" food ordering app.

The Firebird Management conveyed their vision for a user-friendly and efficient app that would provide a seamless food ordering experience for their restaurant. ATCO Eats innovation is its Smart Menu Recommendation System. Unlike traditional food ordering apps, ATCO Eats employs advanced artificial intelligence algorithms to analyze customer preferences, order history, and even real-time data, enabling it to make personalized menu recommendations for each user. This feature sets the app apart from its competitors, creating a more engaging and delightful ordering process that keeps customers coming back for more.

Key requirements highlighted during the meeting include:

  1. Real-time Order Tracking: The Firebird emphasized the importance of offering customers real-time order tracking to enable them to monitor their food delivery status accurately.

  2. Personalized Recommendations: The management expressed interest in incorporating personalized menu recommendations based on customers' previous orders and preferences.

  3. User Interface and Navigation: The Firebird emphasized the significance of an intuitive and visually appealing user interface that simplifies navigation and enhances the overall app experience.

  4. Loyalty Program Integration: The management desires to implement a loyalty program in the app, providing customers with rewards, discounts, and exclusive offers to foster customer retention.

  5. Menu Customization: The Firebird wishes to enable users to customize their orders, allowing them to tailor menu items according to their taste and dietary requirements.

  6. Notification System: The management intends to implement a notification system to inform users of special deals, limited-time offers, and new menu additions.

  7. Payment Methods: The Firebird aims to offer various payment methods, including credit cards, debit cards, mobile wallets, and cash on delivery, to accommodate user preferences.

  8. Additional Features: The management expressed openness to additional features that enhance user engagement and app functionality, such as feedback submission and in-app help.

The project team diligently recorded all requirements and addressed various queries raised by The Firebird. Both parties acknowledged the importance of data privacy and security, regulatory compliance, and seamless integration with existing systems.

More specifically, the following key elements were listed in terms of operational concerns:

  1. Network Connectivity: The app heavily relies on network connectivity to function properly. Operational constraints may arise in areas with poor or unreliable internet access, leading to potential difficulties in placing orders or tracking delivery status.

  2. Payment Processing: The app’s secure payment processing system relies on external payment gateways. Operational constraints may occur if there are issues with these payment providers, causing payment delays or failures.

  3. Server Capacity: The app’s server infrastructure needs to handle high traffic during peak hours, especially during weekends or special events. Insufficient server capacity may result in slow response times or even system crashes.

  4. Device Compatibility: ATCO Eats needs to support a wide range of devices, including various smartphones and operating systems. Ensuring compatibility across different devices can be challenging and might lead to operational constraints if not adequately addressed.

  5. Data Security and Privacy: The app handles sensitive customer information, including payment details and personal data. Strict adherence to data security and privacy regulations is essential to avoid potential breaches or legal complications. Failure to maintain robust security measures could lead to significant operational constraints and reputational damage.

Next Steps:

The project team will consolidate the gathered requirements and prepare a comprehensive document for review and validation by The Firebird. A follow-up meeting is scheduled for December 6, 2023 to present the finalized requirements and initiate the app development phase.

Adjournment:

With a shared sense of enthusiasm and commitment, the meeting concluded on a positive note, reflecting the dedication of The Firebird and the project team towards creating a successful ATCO Eats food ordering app.

Meeting adjourned at 04:30PM.

End of Minutes

Response from ACME to The Firebird

Subject: Request for Ideation Workshop

Dear Firebird Management Team,

We’ve identified some initial similarities between ATCO Eats and existing platforms like Uber Eats. To ensure that ATCO Eats is tailor-made for your needs and stands out in the market, we propose an ideation workshop. This session will allow us to collaboratively brainstorm and refine the project’s direction to meet your unique requirements effectively.

Your participation in this workshop would be invaluable in shaping the project’s path. Please let us know your availability, and we will arrange a suitable time for the session.

Thank you for your cooperation.

Best regards,

Ideation Workshop Report

Date: August 15, 2023

Location: ACME Inc. HQ

Participants:

  • The Firebird Management

  • ACME Project Team Members

During the ideation workshop, The Firebird and the ACME Requirements Engineering Team engaged in collaborative discussions to refine the project’s direction and identify features.

The Firebird quickly agreed that their initial description of ATCO Eats was similar to systems like DoorDash or Uber Eat and, as such, might not be the product they had initially envisioned.

As a result of the ideation discussion, The Firebird identified a new list of priorities for ATCO Eats, which replaces the initial ones.

  • Integration into Campus: ATCO Eats must leverage that The Firebird is located at the heart of McMaster’s historic campus. They are envisioning an integration between ATCO Eats and system like Mosaic to allow McMaster’s staff to order food for events directly through their internal information system and automatically support billing (instead of staff paying with their credit card and then submitting an expense report).

  • Integration with Campus life: ATCO Eats needs to reflect the campus life, i.e., support students when they need it the most (e.g., exam periods) or during their daily routine (e.g., short lunch break). The Firebird envisions a pick-up mechanism where students can order meal boxes in advance and pick them up quickly at the restaurant.

  • Attracting new customers: ATCO Eats is also a way to expand their patron’s pool. A loyalty card can bring people on campus and enjoy the patio, especially during summer times. The Firebird envisions a loyalty card with points that can be accumulated and used to get some appetizers.

During the meeting, The Firebird management team mentioned several times that University by-laws regulate campus life and that ATCO Eats will have to be compliant with these by-laws.