MAD-Treasure-Hunt/DB/DB-instructions.md

Database Structure & Game Rules

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: Individual vs Business

Individual Users (isBusiness: false)

Private Game Creation Rules:

• Individuals can create one private game per account.
• Auto-creates:
  • Subgroup 0: Admin subgroup (empty on creation).
  • Subgroup 1: Members subgroup (individual joins as member, not admin).
• MaxMemberSubgroups is set to 1 (no additional subgroups can be created).
• Individual has SGid = 1 and IsAcceptedAdmin = false.
• If an individual tries to create a game again, returns the existing game.

Team Participation:

• Individuals can create and join teams only in subgroup 1.
• Cannot access admin functions or view Admin Hub.
• Game management is simplified: "Manage Game" screen instead of "Admin Hub".

Business/School Users (isBusiness: true)

Private Game Creation Rules:

• Businesses can create unlimited private games (tracked per creator CreatedByUid).
• Auto-creates:
  • Subgroup 0: Admin subgroup (business becomes member).
  • No automatic subgroups 1+ (must be created manually).
• MaxMemberSubgroups is set to 999 (supports up to 999 subgroups).
• Business creator has SGid = 0 and IsAcceptedAdmin = true (immediately accepted).

Admin Approval Flow:

• When a new admin joins via "Join as Admin for Private Game":
  • If an active admin already exists (hasActiveAdmin check for SGid 0, IsAcceptedAdmin true):
    • Request added to admin-waitlist.json with status pending.
    • User is notified: "Admin access request submitted. You will see admin tools after approval."
  • If no active admin exists:
    • User is auto-promoted to accepted admin immediately.
    • IsAcceptedAdmin is set to true.

Team Participation & Admin Restrictions:

• Admins cannot create or join teams (checked via canJoinTeamForSubgroup logic).
• Admins in subgroup 0 see a warning in Game Lobby: "Admins cannot participate in teams. Manage your game from the Admin Hub instead."
• Team controls are hidden for admin users.

Subgroup Visibility & Management

Manage Subgroups Page

• Only business users can access (individuals see an informational message).
• Only displays subgroups with SGid > 0 (member subgroups).
  • Subgroup 0 (admin) is hidden to avoid confusion.
• Features:
  • Search bar to filter by subgroup name or ID.
  • Card-based display showing:
    • Bold subgroup name
    • ID: [SGid]
    • Status: [Active|Inactive] (based on IsGameStarted flag)
    • Teams: [true|false]
  • Create form at bottom for adding new subgroups (up to MaxMemberSubgroups limit).

Visibility API

• getVisibleSubgroups(gid) returns only subgroups where SGid > 0.
• Used by ManageSubgroupsPage for filtering.
• Maintains admin-only (subgroup 0) separation in UI.

Admin Logic

• Group creator is auto-set as admin (SGid = 0) only if business account.
• Individual creators are set to subgroup 1 (members) and are never admins.
• Admins cannot create/join teams (blocked by canJoinTeamForSubgroup check).
• 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.

Timestamp Format

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

Summary: Game Flow Decision Tree

User Registration
├─ Individual (isBusiness = false)
│  └─ Login → "Manage Private Game" 
│     ├─ Has created game before? 
│     │  ├─ Yes → "Manage Game" screen (team manager)
│     │  └─ No → "Create Game" screen → creates game with subgroups 0 & 1
│     └─ Never sees Admin Hub
│
└─ Business (isBusiness = true)
   └─ Login → "Manage Private Game"
      ├─ "Create New Private Game" → creates game with subgroup 0 only
      └─ "Join as Admin for Private Game" → requests admin access
         ├─ Active admin exists? 
         │  ├─ Yes → queued in admin-waitlist (pending)
         │  └─ No → auto-promoted (accepted)
         └─ Once accepted → Admin Hub access
            ├─ Create a Game
            ├─ Manage Existing Game (blocked from teams)
            └─ Manage Subgroups (create/search member subgroups)