MAD-Treasure-Hunt/README.md

Welcome to the mobile application development repository for our Treasure Hunt Game! This project is built using React Native and Expo.

Get started

1. Install dependencies

   npm i
   

2. Start the app

   expo start --android 
   

Database Structure

This project uses split JSON files in DB/ so each collection behaves like its own REST endpoint.

Purpose

• Keep data modular and readable.
• Mirror server-side endpoint structure before moving to a hosted REST API.
• Allow the app to load all collections into one in-memory state via app/Model/DbController.js.

Files

• users.json: user accounts and role state (Uid, Gid, SGid, TGid, isBusiness, IsAcceptedAdmin).
• groups.json: top-level game groups (Gid), admin approvals, group settings, creator metadata (CreatedByUid, IsBusinessGroup), and subgroup limits (MaxMemberSubgroups).
• subgroups.json: subgroup definitions within each group (SGid scoped by Gid), join codes, cache trigger defaults, and game status (IsGameStarted).
• subgroup-memberships.json: membership bridge from Uid to Gid/SGid.
• admin-waitlist.json: pending admin requests for groups when active admins already exist.
• teams.json: team entities for non-admin subgroup players.
• team-members.json: membership bridge from Uid to Tid.
• game-data.json: per-group game payloads (geocaches, map/game objects).
• game-types.json: available game type options for UI flow.
• db.json: index file listing split JSON resources.

ID Rules

• Uid: unique user ID.
• Gid: unique group/game ID.
• SGid: subgroup ID within a group (0 is admin subgroup; 1+ are member subgroups).
• Tid: unique team ID.
• New IDs are generated from the max existing value in each endpoint collection (users, groups, teams) so no separate counter file is required.

User Types and Private Game Rules

Individual Users (isBusiness: false)

• Private Game Creation: Individuals can create one private game per account.

  • Auto-creates subgroup 0 (admins) and subgroup 1 (members/self).
  • MaxMemberSubgroups is set to 1 (cannot create additional subgroups).
  • Individual becomes a member of subgroup 1, not an admin.
  • Cannot view "Admin Hub" options; instead see "Manage Game" UI for active team management.

• Team Participation: Individuals can create and join teams within their subgroup 1.

  • Admins (those in subgroup 0) are blocked from team participation.

Business/School Users (isBusiness: true)

• Private Game Creation: Businesses can create private games with flexible subgroup management.

  • Auto-creates subgroup 0 (admins) only; no auto-member subgroup.
  • MaxMemberSubgroups is set to 999 (can create up to 999 subgroups).
  • Business creator becomes an accepted admin of subgroup 0 immediately.

• Admin Participation: Business admins (SGid 0, IsAcceptedAdmin true) cannot participate in teams.

  • Game Lobby shows warning message and hides team creation/join controls.
  • Admins must manage subgroups and games from Admin Hub and Manage Subgroups pages.

• Admin Approval Flow: New admins joining a business group go into admin-waitlist.json if an active admin already exists.

  • Auto-promoted if no active admin exists.
  • Promoted admins gain accepted admin status.

Subgroup Visibility

• Manage Subgroups Page: Only displays subgroups with SGid > 0 (member subgroups).
  • Subgroup 0 (admins) is hidden in the UI to avoid confusion.
  • Features search by name/ID and card-based display with status and team info.
  • Only visible to business users; individual users see an informational message.

Admin Logic

• Group creator is auto-set as admin (SGid = 0) if business account.
• New admin join requests go into admin-waitlist.json if active admins exist.
• If no active admin exists, the requester is auto-promoted to accepted admin.
• Group-level ApprovedAdmins stores accepted admin Uid values.
• Admins cannot create or join teams; they manage the game and subgroups.

Game Flow

Login / Registration

1. User registers as Individual or Business/School.
2. Session stores isBusiness and IsAcceptedAdmin flags.

Individual Private Game Flow

1. Individual selects "Manage Private Game" option.
2. Check if they have an existing private game:
   • If existing: Navigate to "Manage Game" screen → "Open Team Manager" → join/create team.
   • If new: Navigate to "Create Game" screen → create game → then to "Manage Game".
3. Individual can only manage their single team in subgroup 1.
4. Cannot access Admin Hub or Subgroup management.

Business Private Game Flow

1. Business user selects "Manage Private Game" option.
2. Presented with:
   • Create New Private Game: Creates a game with admin subgroup 0 only.
   • Join as Admin for Private Game: Submit request to join an existing business group.
3. Once admin (accepted or auto-promoted), access Admin Hub:
   • Create a Game
   • Manage Existing Game (team/lobby controls)
   • Manage Subgroups (search, filter, create member subgroups)
4. Cannot create/join teams in Game Lobby (shows warning).

Team Management

• Teams can only be created/joined in non-admin subgroups (SGid > 0).
• Admin users (SGid 0 + IsAcceptedAdmin) are blocked from team participation.
• Teams are scoped per subgroup.

Timestamp Format

• CreatedAt values are stored at minute precision:
  • format: YYYY-MM-DDTHH:mmZ
  • example: 2026-03-17T14:42Z