Fab Academy
Randomizer

Interface Guide

The sidebar panels give you quick access to session data. Click the vertical tab selection buttons on the right edge of the sidebar to open each panel.

📋 Today's List (Main Sidebar)

• Shows all students and their status for today's session: present, absent, or special mention.
• Click any student row to jump the map to their lab and show the popup.
• Use the search box at the top of the sidebar to find a student quickly by name or lab.

🗺️ Labs Tab

• Lists all registered FabAcademy labs with their respective students.
• Shows how many students are in each lab and how many have presented.
• Click a student name to fly the map to that lab's location.

📆 Weeks Tab

• Displays a log of past presentation sessions by week number.
• Use this to review which students presented, were absent, or received a special mention in previous weeks — useful for verifying fairness over time.
• 💡 You can drag and drop a student entry from one week to another in this panel to reassign them to a different week.

✨ Special Tab

• Shows all students who raised their hand to present during extra time. A small red badge shows the number of students in the waiting list.
• Useful as a quick reference during endorsement rounds or extra-work review moments.
• Click the Good Work ⭐ badge to award a student a special mention.

Data & Import

Student data is synchronised with Firebase. When you first log in, the system checks whether historical data already exists in the shared database.

📥 Importing Data

• If the database is empty, import your people.json or presented.json via Settings → Data Management → Import.
• You can upload a file directly or paste raw JSON into the text field.
• Importing overwrites all current student data — use with care.

📤 Exporting Data

• At the end of each session, click the Export button (bottom-left) to download an updated presented.json.
• Keep this file safe — it contains the full presentation history used to seed future sessions.

Settings

Open the Settings panel via the ⚙️ icon (bottom-left). Changes sync immediately to all connected instructors.

🗺️ Map & Appearance

• Zoom Depth: How far the map zooms in when a student is selected.
• Fly Speed: Duration of the animated map flight to a lab.
• Show all labs on map: Toggle marker visibility for labs that haven't been called yet.
• Dark Mode: Switch between light and dark themes.

🎲 Randomizer Parameters

• History Depth (1–10): How many recent picks are remembered for penalty calculation.
• Penalty Strength (1–10): How strongly recent picks are deprioritised. Higher = more variety enforced.
• Decay Rate (0.1–0.9): How fast the penalty fades. 0.1 = long memory, 0.9 = quick recovery.
• Include Continuing / Absent Students: Toggle whether these groups enter the selection pool.

⚠️ Data Management

• Delete local & remote data: Permanently wipes the shared Firebase database for all users. Extreme caution required.

Randomizer Engine

The engine uses a Stochastic Decaying Penalty model to guarantee fairness and geographic diversity across sessions.

🧠 How Selection Works

• Every eligible student is assigned a probability weight.
• Students from recently selected labs or regions receive a reduced weight — less likely to be picked again, but never excluded entirely.
• A random value is drawn proportional to total weight (Roulette Wheel Selection). The student whose weight range contains the value is selected.

🌍 Two-Stage Geographic Selection

• Stage 1: A geographic region is chosen by weighted random draw.
• Stage 2: A lab within that region is chosen by weighted random draw.
• This prevents high-population labs from dominating and ensures a consistent global spread across sessions.

📉 Penalty Decay Formula

• Penalty at history index i: P(i) = max(0.01, 1 − (S/10 × R^i))
• Every student always retains a minimum non-zero chance of selection.
• Tune Penalty Strength and Decay Rate in Settings to control the intensity of variety enforcement.

Instructor Synchronisation

Multiple instructors can share the same Instructor Key to run perfectly synchronised sessions in real time via Firebase.

🔄 What Syncs Automatically

• Active spin result and selected student
• Student status changes (present, absent, special)
• Settings changes (zoom, fly speed, theme, randomizer parameters)
• Map zoom level and pan position

💾 Exporting in a Shared Session

• All instructors share identical state — any one of them can click Export to download the final session data.
• Only one export is needed; the file will be the same for all.

🔑 Weekly Key Rotation

• The Instructor Key is changed weekly by the admin via the Admin Panel.
• When the key changes, all active instructor sessions are invalidated. Re-enter the new key to continue.

Settings & Configuration

Tweak the application behavior to suit your preference. These settings only affect your current browser session.

🗺️ Map Controls

• Zoom Depth: Click the gear icon (bottom left) to adjust how far the map zooms in on a student.
• Fly Speed: Adjust the duration of the animated map flight to a lab.

👥 Student Pool

• Include Continuing Students: Toggle whether past students (Level 1/2) appear in the pool.
• Include Absent Students: Toggle whether students previously marked absent are re-added to the rotation.

Randomizer Engine

The engine uses a Stochastic Decaying Penalty model to ensure variety and fairness.

🧠 How it works

• The engine assigns weights to students based on their geographic location.
• Recently selected labs and regions receive a significant penalty, making them less likely to be picked again immediately.
• The penalty decays over time based on the Decay Rate set in the Settings.

Import & Export

Practice data management using local JSON files.

📥 Import

• You can practice importing custom JSON data via Settings > Data Management to see how the system handles formatting.

📤 Export

• Export locally modified lists to download a timestamped presented.json file.