MathMatchup

Jump to "Running MathMatchup" Section

Go to MathMatchup Website

Go to MathMatchup App Hosted on Web

Players join the game and are automatically separated into teams of 2 or, if needed, 3. The only catch is that they don't know their teammate. They then have to answer questions to get points, which get added together with their partner's points at the end. Teammates are revealed and the partnership with the most points wins!

Repository Navigation

MathMatchupBackend - Directory that stores the Spring backend to the app and website

math_matchup - Directory that stores the MathMatchup Flutter app

math_matchup_website - Directory that stores the MathMatchup Flutter website (no longer updated, rewritten with Next.js)

nextjs_website - Directory that stores the brand-new MathMatchup website, written with Typescript using Next.js

Roadmap.md - A roadmap of planned features

testingscript.py - A python script that simulates a full class of players, letting you participate in a "real" game when you're using the app. Does everything needed to have a full game, with breakpoints that give you a chance to join the game on the frontend as well as play through the full game.

Why rewrite the website?

It is always hard to throw away code, but I made the decision to completely rewrite the website for MathMatchup. The original website was written in Flutter, which, while familiar to me (something that sped up development), is not a great choice for a mostly static website because it has slow initial loading times and no SEO. Using Next.js solves both of these problems well (and gave me something new to learn), so it was an obvious choice. The app is mostly optimized for small screens, so I needed a computer-screen ready way to manage licenses and start games. A website separate from the app made the most sense. While it is currently labeled the "MathMatchup" website, it will eventually be changed to "MatchupLearning" to allow for more school subjects to be part of the MathMatchup experience. This will only happen when MathMatchup is perfected, though.

Technical Architecture

• Technologies: Dart + Flutter, Java + Spring, Typescript + NextJS, PostgreSQL
• The backend (Spring + PostgreSQL) manages users, games, and analytics. It enforces full endpoint security by verifying Firebase credentials
• Firebase Authentication provides fast, infinitely scalable, secure authentication for MathMatchup. It also allows me to avoid needing an OAuth, website hosting or email blast vendor since that's all included for free.
• The app (Flutter) is used by students to play games. It also handles all question generation (based on teacher-set game settings) to ensure no delay from API calls.
• The website (NextJS) is used by teachers and administrators. On it, admins can handle licenses and teachers can create games. Teachers can also view game analytics (which are more limited than I'd like because I don't want to mess with COPPA)

This architecture minimizes backend load while ensuring ease of use for students, teachers, and administrators.

App Features

• Fully supported internationalization with numbers and languages (currently English and Spanish)
• Responsive screen sizing tailored to phones and tablets
• Efficient state management using Riverpod for a predictable and scalable architecture
• Dynamic theming with light and dark modes, instantly changeable without restarting the app
• Custom splash screen with app logo and HARAN branding
• Comprehensive error handling with user-friendly alert dialogs and behind-the-scenes error logging using Firebase Analytics
• Optimized API calls reduce the number of database writes necessary by generating as much as possible, like all math questions, on the client side
• Endless customizations allow teachers to tailor nearly every aspect of games, ranging from the timer to the difficulty of questions (Easy, Medium, Hard, and Impossible)
• Real time updates for players in game, including scoring, leaderboards, and other players
• Player analytics for teachers to view
• Comprehensive backend test coverage to validate core API functions

Backend Features

• CRUD operations for admin and teacher profiles (students don't need a profile to play)
• Bulk user creation from CSV files
• Integration with Firebase for secure user authentication
• Role-based authorization to ensure users can only access what they are supposed to
• Request logging for debugging and monitoring
• JPA and Hibernate for ORM and database operations
• Easily extendable service, controller, and repository layers
• RESTful API endpoints for user, team, player, and game operations
• Player and combined class analytics for teachers to view
• Comprehensive REST API + PostgreSQL database integration testing suite for complete coverage

NextJS Website

• Serves as the marketing website for MathMatchup
• Allows for school-wide license management
• Easily create teacher accounts by hand, or through CSV upload
• Teachers don't have to deal with annoying, autogenerated passwords. Admins creating accounts for them automatically sends a password reset email
• Teachers can easily create games and view past results (coming soon)

Screenshots

Homescreen

Teacher View Before/During Game

Student View During Game

Teacher View After The Game

Running MathMatchup Spring backend

1. Install Java 17 and PostgreSQL 16.3
2. cd MathMatchupBackend
3. Create a Postgres database (psql then CREATE database database_name;)
4. Modify application.properties (MathMatchupBackend/src/main/resources/application.properties) with database details
5. Run the Spring backend
6. (optional) If you want, you can skip running the frontend and simply visit The MathMatchup Website and it will work with your locally running backend
7. Run the testing script to simulate a classroom environment (python testingscript.py)

Running MathMatchup Flutter frontend

1. Install the Flutter framework
2. cd math_matchup
3. Run flutter pub get
4. and dart run build_runner watch -d
5. then flutter run or flutter build apk --release to compile an apk for installation on android or flutter build web to compile for deployment to the web
6. Run the testing script to simulate a classroom environment (python testingscript.py)

Running MathMatchup NextJS Website

1. Install NextJS and its dependencies
2. cd nextjs_website
3. Run yarn dev
4. Visit localhost:3000
5. Note: Visiting the MathMatchup Website will also work if the backend is running. You can still view static content without the backend.

Running MathMatchup Flutter Website (replaced by NextJS version)

1. Install the Flutter framework
2. Run flutter pub get
3. then flutter run -d chrome or flutter build web to compile for deployment to the web

Other Notes

• CSV format for bulk user upload: email, last name, first name (ex. john.doe@school.edu, doe, john)
• Note that the MathMatchup app is meant for smaller screen sizes and may not look right when viewed on a computer. The end goal is for students to use phones/tablets/chromebooks and teachers to use full-sized computers/laptops with the website rather than the app.
• The teacher's screen is meant to be projected to the class throughout the game.
• The team with 3 players (if there is an odd number of students playing) will have their total points multiplied by 2/3 to make the game even
• The testing script will do everything needed for you to act as a player in a game. It will open the game, add 30 test players, give you a chance to join the game, start the game, submit randomized (within reason) fake player data for the 30 fake players, and finish the game. This covers everything that a teacher and your fellow students would do.