Merge pull request #3 from dcsil/documentation

A2 - CUJ Framework, Reflections, and Sprint Documentation

Author: malek72

cuj/README.md

@@ -0,0 +1,53 @@
+# Rapid MVP – Classroom Presentation Randomizer
+
+This repository contains the code for our **Rapid MVP** developed as part of **Assignment 2: Rapid MVP & CUJ Framework**.  
+The goal of this sprint was to build a simple, functional web application under tight time constraints and use it as a testbed for conducting a **Critical User Journey (CUJ)** analysis.
+
+The application is a **Classroom Presentation Randomizer** designed to help instructors manage in-class group presentations by randomly selecting teams, tracking which teams have presented, and managing presentation and Q&A timing.
+
+---
+
+## Code Repository
+
+**GitHub Repository:**  
+https://github.com/dcsil/PyGuard-Presentation-Randomizer
+
+---
+
+## Tech Stack
+
+- **Frontend:** React (Vite)
+- **Backend:** Express.js
+- **Database:** SQLite (via Prisma ORM)
+- **Architecture:** Decoupled frontend and backend, running locally
+
+This structure is intentionally designed to be **local-to-cloud ready** for future assignments.
+
+---
+
+## Local Setup Instructions
+
+The application consists of a decoupled frontend and backend, which must both be running locally.
+
+### Backend Setup
+
+```bash
+cd backend
+npm install
+npx prisma migrate dev --name init
+npm run seed
+npm run dev
+```
+
+### Frontend Setup
+
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+Open the app at:
+```
+http://localhost:5173/
+```

cuj/assets/all teams have presented.png

@@ -0,0 +1,128 @@
+# CUJ Framework Document
+
+## User Goal and Persona
+
+**Persona**  
+A busy instructor managing an in-person class of approximately 40 students giving group presentations.
+
+**Value-Driven Goal**  
+To conduct in-class presentations **fairly, efficiently, and with minimal cognitive overhead**, allowing the instructor to focus on evaluating presentations rather than managing logistics.
+
+---
+
+## The Journey Audit
+
+### Step-by-Step Actions (Happy Path)
+
+1. Download or clone the project code from GitHub  
+2. Set up the application using terminal commands  
+3. Open the browser and navigate to the app URL  
+4. Verify that the list of teams is correct  
+5. Click the **Randomize** button to select the next team  
+6. Announce the selected team to the class  
+7. Start the presentation timer  
+8. Monitor the 2-minute warning  
+9. Start the Q&A timer  
+10. End Q&A and proceed to the next team by clicking **Randomize**  
+11. Repeat until all teams have presented  
+
+---
+
+### Unhappy Path Scenarios
+
+- The instructor forgets to start the Q&A timer, or finds the transition between timers not intuitive (there is no hint before nor between the switch) (refer to picture "timer switching to Q&A phase.png")
+- A selected team is temporarily unavailable (e.g., technical issues or bathroom break), there is no way to skip a group (refer to "cannot skip a selected team.png")
+- The instructor loses track of whether the timer has been started or not
+- A new user is unsure whether the timer section includes a Q&A phase (refer to "landing page : initial stage.png")
+
+---
+
+### Context Switches
+
+**Physical Context Switches (Leaving the App)**
+
+- Switching to a presentation rubric to evaluate the current team  
+- Checking slides or lecture notes in a separate window
+- Looking at a phone or watch to confirm elapsed time if unsure whether the timer is running
+
+**Mental Context Switches (Within the App)**
+
+- Interpreting whether the current timer is for **Presentation** or **Q&A**  
+- Remembering whether the timer needs to be manually restarted between phases
+- Inferring the meaning of visual cues (e.g., greyed-out team tags indicating “presented”)
+- Re-orienting after interruptions such as student questions or technical delays
+
+These context switches increase cognitive load and raise the likelihood of timing errors, especially when repeated across many teams in a single session.
+
+---
+
+### Time Tracking
+
+**One-Time Setup**
+
+- Download / clone the code from GitHub: ~1 minute  
+- Set up using terminal commands: ~30 seconds  
+- Open browser and navigate to the app: ~10 seconds  
+- Verify team list: ~30 seconds  
+
+**Per-Team Cycle**
+
+- Click the **Randomize** button: ~1 second  
+- Announce selected team: ~10 seconds 
+- Start presentation timer: ~1 second  
+- Monitor presentation and warning period: ~2 minutes  
+- Start Q&A timer: ~1 second
+
+Small delays accumulate over many iterations, making friction more noticeable during longer sessions.
+
+---
+
+### Evidence
+
+- Landing page (initial state)
+- Presentation timer with 2-minute warning active  
+- Transition from presentation phase to Q&A phase  
+- Q&A timer completed (session end state)  
+- All teams marked as presented  
+
+---
+
+## Analysis & Recommendations
+
+### Highlights / Lowlights
+
+**Great**
+
+- Visual marking of “presented” teams significantly reduces mental bookkeeping  
+- Randomized selection improves perceived fairness  
+- The 2-minute warning is clear and easy to notice  
+
+**Moderate**
+
+- Timer controls require conscious attention and manual interaction  
+- Phase switching (Presentation vs Q&A) is not immediately obvious to first-time users
+
+**Severe**
+
+- If the instructor forgets to start a timer, the app provides no safeguard, which can lead to uneven timing and perceived unfairness  
+- New users may not realize that a Q&A timer exists after the presentation timer  
+- The meaning of greyed-out team tags is not self-evident without prior explanation  
+
+---
+
+### Product Recommendations
+
+1. **Phase-Aware Prompt**  
+   After the presentation timer ends, display a clear visual cue such as  
+   *“Next event: Q&A”* to reduce confusion and missed transitions.
+
+2. **Session-State Indicator**  
+   Add a lightweight progress indicator (e.g., *“3 / 10 teams presented”*) to help users quickly re-orient after interruptions.
+
+---
+
+## Future User Advice (Pro Tips)
+
+- Pre-load and verify the team list before class begins  
+- Use the app in full-screen mode to minimize distractions  
+- Keep the app open between presentations to avoid re-orienting or reinitializing the session  

cuj/assets/both timers are finished.png

@@ -0,0 +1,13 @@
+# Post-Mortem Reflection: Insights from the CUJ Framework
+
+Before conducting the Critical User Journey (CUJ) analysis, our team largely equated “done” with “functional.” As long as the core features worked—randomizing teams, displaying information, and running timers—we felt the product was complete enough to move on. The CUJ framework challenged this assumption by forcing us to slow down and examine how the tool is actually used in a real classroom context, step by step, under time pressure.
+
+One of the most impactful shifts in perspective came from explicitly **quantifying user friction**. Breaking the workflow into concrete actions and assigning rough time estimates made us realize how even small inefficiencies accumulate across many repetitions. For example, starting a timer takes only a second, but when repeated for every team, across presentation and Q&A phases, any confusion or missed step compounds quickly. What initially felt like a minor inconvenience became clearly visible as recurring cognitive load.
+
+The CUJ process also highlighted the difference between a feature existing and a feature being usable. Our timers worked as intended, but the analysis revealed that transitioning between presentation and Q&A required the instructor to remember the workflow rather than being guided by the interface. From a development perspective, the feature was “done.” From a user perspective, it was fragile—easy to forget, easy to misuse, and easy to misinterpret under real classroom conditions.
+
+Another important insight came from identifying context switches. We initially assumed that the instructor would remain focused on the app during presentations. The CUJ made it clear that this assumption was unrealistic. In practice, instructors frequently switch attention to rubrics, slides, student questions, or technical issues. When they return to the app, the interface needs to help them quickly re-orient. The lack of session-state feedback (for example, how many teams have already presented) stood out as a usability gap that we would not have noticed without explicitly mapping the journey.
+
+Quantifying friction also helped us become more disciplined about scope. Instead of immediately adding features to “fix” every problem, we learned to distinguish between critical usability issues and acceptable limitations of an MVP. The CUJ framework encouraged us to document pain points honestly rather than prematurely solving them, reinforcing that learning and iteration—not polish—were the goals of this assignment.
+
+Overall, the CUJ framework reframed our understanding of progress. A product can be technically complete while still placing unnecessary mental burden on the user. By measuring friction, we shifted from asking “Does this work?” to asking “Does this help the user do their job under realistic conditions?” This distinction between “done” and “usable” is a perspective we will carry forward into future projects, especially when building tools intended for real-world, time-constrained environments.

cuj/assets/cannot skip a selected team.png

@@ -0,0 +1,9 @@
+# Team Principles Reflection
+
+One of the top priorities we agreed upon in our Team Principles during the first assignment was that, as a team, we would communicate clearly and hold each other accountable while building and shipping features. The "Rapid MVP" assignment, where we had to actually build and ship a product, was the first time our Team Principles were truly tested. Since we had to begin tasks where performance really mattered, we were able to put our methods for managing Feedback, Accountability, and Conflict into practice.
+
+We managed accountability based on how we divided the assignment. Since the project required both a UI and functionality, we split the work into frontend and backend tasks. We structured accountability around the understanding that for one person to progress, their partner needed to fulfill their requirements, as certain backend parts could not be completed without specific frontend features, and vice versa. Therefore, we ensured that any parts dependent on future tasks or features from the other person were treated as high priority. Instead of constantly monitoring and reminding each other about every step, we decided to let each other work however we wanted, with the single rule that the feature must be finished and functional by the deadline. This allowed us to work autonomously without issues. This approach worked perfectly, as every single feature in our plan was completed on or before the deadline.
+
+One of the biggest conflicts we faced during this sprint involved decisions regarding design and usability,specifically, whether the user would find the features easy to understand. Since the features we were launching depended not just on functionality (working vs. not working) but also on user experience, the decision-making process shifted from objective to subjective. Opinions and personal preferences played a huge role in how each of us quantified "ease of use." To handle these debates efficiently and fairly, we used a SWOT analysis for each option we considered. For example, when building the timer, Malek suggested adding a sound to alert the user when 2 minutes remained, arguing that we shouldn't risk them forgetting the time. Yunling, however, wanted to turn the timer red to catch the user's eye, arguing that while it is essential to notify the user, disturbing the presentation with a sound caused more harm than the risk of them forgetting. Upon conducting the SWOT analysis, we found that Yunling’s idea had far more Strengths and Opportunities compared to Weaknesses and Threats than Malek’s idea, so we decided to go with the visual cue.
+
+Feedback was another important factor in this assignment sprint. We prioritized constructive feedback and strictly avoided negative or harmful comments. As a group, we define constructive feedback as input that points out what was wrong, explains why it was wrong, indicates how to fix or improve the problem, and suggests how to avoid it in the future. Our feedback method focused not just on identifying errors, but on the constructive aspect,meaning how the person could improve and learn from the experience. We believe this is the most important part, as our goal is to grow our skills not only as software engineers but also as entrepreneurs.