TreasureTrails/application_requirements.md

Treasure Trails - Development Stories

This document outlines the Epics and User Stories for the "Treasure Trails" online scavenger hunt application.

Base requirements:

1. All libraries and dependecies should be open source.
2. We will use OpenStreetMaps for all mapping.
3. This is meant to be a fun game.

I. Epic: Game Master Functionality - Design, Manage, and Oversee Hunts

Goal: Enable users to design, manage, and oversee scavenger hunts.

Story 1: Create a Scavenger Hunt

As a Game Master, I need to create a scavenger hunt with configurable details so that I can design engaging and unique experiences.

• Requirements:
  • Ability to name the scavenger hunt.
  • Ability to set a start date and time.
  • Ability to choose between public and private visibility.
  • Ability to add a description and prize details.
  • Ability to define a location and search radius on OpenStreetMap for treasure locations.
  • Ability to create and sequence "legs" or clues with descriptions and conditions (e.g., photo proof, purchase, etc.).
  • Ability to see individual leg distances in km or miles.
  • Ability to see total sum of different routes (combinations of legs) distnace in km or miles.
  • Ability to set time limits per leg.
  • Ability to set a time deduction penalty for navigation warnings.
• Acceptance Criteria:
  • All fields are validated (e.g., name required, date in the future).
  • OpenStreetMap integration works for location selection and searching.
  • Leg creation is intuitive and supports different condition types.
  • Game master can save a draft game.
• Testing Steps:
  1. Create a new scavenger hunt with valid data.
  2. Create a new scavenger hunt with invalid data (e.g., missing name, past date).
  3. Verify that OpenStreetMap functionality allows for accurate location selection.
  4. Verify leg creation and sequencing functionality.
• Negative Testing:
  1. Attempt to create a hunt with blank fields. Verify appropriate error messages.
  2. Attempt to save a hunt with a start date in the past. Verify an error.
  3. Simulate slow network conditions during save. Ensure proper loading indicators and error handling.

Story 2: Manage a Live Game (Game Master Dashboard)

As a Game Master, I need a real-time dashboard to monitor and control a live scavenger hunt so that I can efficiently guide teams and ensure fair play.

• Requirements:
  • Display a list of participating teams with their current clue/location.
  • Real-time map view showing team positions (approximate within 500m).
  • Ability to view chat messages between teams and the Game Master.
  • Ability to view photo submissions as proof of completion.
  • Ability to advance teams to the next clue (individually or multiple teams).
  • Ability to manually apply time deductions to teams.
  • Ability to declare a winning team.
  • Ability to disqualify teams.
  • Display a leaderboard of clues completed.
• Acceptance Criteria:
  • Dashboard updates in near real-time.
  • Map icons clearly represent teams and their location.
  • Time deduction functionality applies the penalty correctly, with countdown timer visible.
  • Disqualification removes team from the game and displays their status.
• Testing Steps:
  1. Simulate a live game and verify all dashboard elements update correctly.
  2. Verify advancing teams and applying time deductions.
  3. Verify disqualification functionality.
• Negative Testing:
  1. Simulate high game participation to test dashboard performance under load.
  2. Disconnect/reconnect the dashboard. Verify data is recovered correctly.

Story 3: Public/Private Game Visibility

As a Game Master, I need to control the visibility of my scavenger hunt so that I can cater to both open and invite-only experiences.

• Requirements:
  • Option to set game to 'Public' or 'Private' during creation.
  • Public games listed on a searchable/filterable game list.
  • Private games accessible only via invite.
  • Option for the game master to publish a private game for public viewing after the game has started.
• Acceptance Criteria:
  • Public games are displayed on the list.
  • Private games are not shown on the list and require an invite link.
  • Invite links are unique and secure.
• Testing Steps:
  1. Create a public game and verify it appears on the game list.
  2. Create a private game and confirm it's not visible on the list.
  3. Create a private game and verify access with an invite link.
• Negative Testing:
  1. Attempt to access a private game without an invite.
  2. Try to modify game visibility without proper authorization.

II. Epic: Team Member Functionality - Participate in Hunts

Goal: Allow users to join and participate in scavenger hunts.

Story 4: Join a Scavenger Hunt & Team Formation

As a User, I need to be able to find, join, and create a team for a scavenger hunt so that I can participate with friends or strangers.

• Requirements:
  • Browse and search for public scavenger hunts.
  • Receive invites to private scavenger hunts.
  • Create a team of 3-5 members.
  • Ability for team members to elect a captain.
  • View a list of games you will be a part of, including their scheduled date and time if any.
  • Have a simple way to join a game when it starts if you are the team captain.
• Acceptance Criteria:
  • Searching and filtering for public hunts works correctly.
  • Invite links grant access to the correct game.
  • Team creation enforces the size limits.
  • Captain election is managed via the device during game startup.
• Testing Steps:
  1. Search for a public game and join.
  2. Receive an invite link and verify access.
  3. Create a team and add/remove members.
  4. Verify the captain election process.
• Negative Testing:
  1. Attempt to join a hunt with an invalid invite link.
  2. Try to create a team with fewer or more than the allowed number of members.

Story 5: Team Device Interface During Game

As a Team Captain, I need a mobile-friendly interface with real-time updates and tools to complete the hunt so that I can navigate and interact with the game effectively.

• Requirements:
  • Display the current clue.
  • Display the team's position on the map.
  • Display approximate positions of other teams (within 500m).
  • Photo submission button.
  • Chat functionality to communicate with the Game Master and other teams.
  • Navigation warning system if the browser tab is closed or a new tab opened.
• Acceptance Criteria:
  • Map displays accurate locations.
  • Photo submissions are clear and easy to send.
  • Chat messages are delivered in real-time.
  • Navigation warnings are displayed appropriately with time deduction information.
• Testing Steps:
  1. Verify all interface elements display correctly.
  2. Test photo submission functionality.
  3. Test chat functionality.
  4. Simulate browser tab closure/new tab opening, and verify the warning message.
• Negative Testing:
  1. Simulate slow network conditions.
  2. Attempt to submit a corrupted photo.

III. Epic: Public Spectator Functionality - View Live Progress

Goal: Enable anyone to view the progress of a public scavenger hunt.

Story 6: Public Game Spectator Dashboard

As a Spectator, I need to view the live progress of a public scavenger hunt so that I can follow along and experience the excitement.

• Requirements:
  • Display a map showing team locations (same approximation as teams have).
  • Display a leaderboard of clues completed.
  • Display team names and statuses.
• Acceptance Criteria:
  • The spectator dashboard accurately reflects the real-time game progress.
• Testing Steps:
  1. View a public game as a spectator.
  2. Verify that the map and leaderboard update dynamically.
• Negative Testing:
  1. Attempt to access a spectator dashboard of a private game.

Additional Notes:

• Technology Stack: Assumed web-based architecture (React/Angular/Vue.js, Node.js/Python/Ruby). Requires integration with OpenStreetMap’s API.
• Scalability: Prioritize scalability for the Game Master dashboard and real-time updates (consider WebSockets).
• Security: Implement robust authentication and authorization.
• Mobile-First Design: Prioritize mobile usability for the Team Device Interface.