# 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.