# Project export: shortcutz
This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small.
## Project metadata
- Hackathon: CruzHacks 2025
- Tagline: Step into a next-gen math dojo where every question adapts to your level, every answer counts, and AI is your personal sensei. Whether you crush it or slip up, real-time smart feedback helps you.
- Devpost: https://devpost.com/software/shortcutz-4ljo1n
- GitHub: https://github.com/anyajoshi/shortcutz
- Team: 1 GitHub contributor(s) — Aman (1 commits)
## Devpost submission (written by the team)
### Inspiration
Aman and Bhargavi spent the winter quarter being teacher assistants for local high school math classes as UCSC Calteach interns. There, they were shocked to find out how many students had a lack of math foundational topics, to the point where they used calculators for basic addition because they did not know how to do it themselves. It was heartbreaking watching the students feel inadequate because they could not learn advance topics due to their lack of foundational skills. The students were not deterred by this challenge, and showed up to class everyday to get a little better. There, Bhargavi and Aman learned that the students picked up math concepts much faster when they were taught a "shortcut" (I.E. 5 times 10 equals 5 following a 0 or 50). Relearning early math concepts that were reinforced by these "shortcuts" ensured they remembered the lessons they learned. That's how our group came up with the app idea "Shortcutz". We built it for the students that were let down in their earlier math education but are determined to continue learning. Having their growth reinforced by the shortcuts and a fun layout is the main goal of our app.
### What it does
Shortcutz is an AI-powered math training app that dynamically adjusts difficulty based on student performance. It challenges users with multiplication and division problems, provides instant feedback, and delivers personalized AI-generated hints and encouragement powered by Gemini AI.
### How we built it
We built the app using React.js for the frontend, leveraging hooks like useState, useEffect, and useRef to manage the quiz state, user inputs, and adaptive difficulty. The smart feedback loop comes from integrating Gemini AI via the Google Generative Language API, which takes the question and user response context to generate helpful and friendly feedback. The difficulty adjusts in real time using a performance-based algorithm that evaluates accuracy and speed.
### Challenges we ran into
API integration: Parsing the Gemini API’s nested response format correctly took a little tinkering. Adaptive difficulty: Balancing the level progression logic to feel fair, yet challenging, was a puzzle of its own. Layout organization: Restructuring the UI to make the app feel clean and intuitive, especially with split panels for questions vs. feedback.
### Accomplishments we're proud of
Seamless integration of LLM-based feedback into a math app — a super cool AI/education combo. A smooth user experience that tracks performance and improves dynamically over time. Created a complete tool that is both helpful for learners and satisfying to build!
### What we learned
How to connect and manage LLM APIs in a React environment How to craft meaningful, structured prompts that lead to actionable AI responses The power of thoughtful UI/UX when combined with smart algorithms — clarity = confidence in learning!
### What's next
Add leaderboards and streaks to gamify practice Integrate voice input and read-aloud questions for accessibility Expand question types to cover fractions, algebra, and word problems Store user history in the cloud for long-term progress tracking Add multi-language support and mobile responsiveness
## README (from the GitHub repository)
# Getting Started with Create React App
This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app).
## Available Scripts
In the project directory, you can run:
### `npm start`
Runs the app in the development mode.\
Open [http://localhost:3000](http://localhost:3000) to view it in your browser.
The page will reload when you make changes.\
You may also see any lint errors in the console.
### `npm test`
Launches the test runner in the interactive watch mode.\
See the section about [running tests](https://facebook.github.io/create-react-app/docs/running-tests) for more information.
### `npm run build`
Builds the app for production to the `build` folder.\
It correctly bundles React in production mode and optimizes the build for the best performance.
The build is minified and the filenames include the hashes.\
Your app is ready to be deployed!
See the section about [deployment](https://facebook.github.io/create-react-app/docs/deployment) for more information.
### `npm run eject`
**Note: this is a one-way operation. Once you `eject`, you can't go back!**
If you aren't satisfied with the build tool and configuration choices, you can `eject` at any time. This command will remove the single build dependency from your project.
Instead, it will copy all the configuration files and the transitive dependencies (webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except `eject` will still work, but they will point to the copied scripts so you can tweak them. At this point you're on your own.
You don't have to ever use `eject`. The curated feature set is suitable for small and middle deployments, and you shouldn't feel obligated to use this feature. However we understand that this tool wouldn't be useful if you couldn't customize it when you are ready for it.
## Learn More
You can learn more in the [Create React App documentation](https://facebook.github.io/create-react-app/docs/getting-started).
To learn React, check out the [React documentation](https://reactjs.org/).
### Code Splitting
This section has moved here: [https://facebook.github.io/create-react-app/docs/code-splitting](https://facebook.github.io/create-react-app/docs/code-splitting)
### Analyzing the Bundle Size
This section has moved here: [https://facebook.github.io/create-react-app/docs/analyzing-the-bundle-size](https://facebook.github.io/create-react-app/docs/analyzing-the-bundle-size)
### Making a Progressive Web App
This section has moved here: [https://facebook.github.io/create-react-app/docs/making-a-progressive-web-app](https://facebook.github.io/create-react-app/docs/making-a-progressive-web-app)
### Advanced Configuration
This section has moved here: [https://facebook.github.io/create-react-app/docs/advanced-configuration](https://facebook.github.io/create-react-app/docs/advanced-configuration)
### Deployment
This section has moved here: [https://facebook.github.io/create-react-app/docs/deployment](https://facebook.github.io/create-react-app/docs/deployment)
### `npm run build` fails to minify
This section has moved here: [https://facebook.github.io/create-react-app/docs/troubleshooting#npm-run-build-fails-to-minify](https://facebook.github.io/create-react-app/docs/troubleshooting#npm-run-build-fails-to-minify)
# shortcutz
## Detected evidence (automated analysis)
Indexed codebase: 9 recognized source files, 18 KB.
- CSS (language) — detected in the code
- HTML (language) — detected in the code
- JavaScript (language) — detected in the code
- React (technology) — detected in the code
- Google Gemini (technology) — claimed on Devpost, not found in the code
## Codebase structure (from repository index)
### Files (13 of 13)
```
.gitignore
package.json
public/index.html
public/manifest.json
public/robots.txt
README.md
src/App.css
src/App.js
src/App.test.js
src/index.css
src/index.js
src/reportWebVitals.js
src/setupTests.js
```
### Dependencies
- package.json: @testing-library/dom@^10.4.0, @testing-library/jest-dom@^6.6.3, @testing-library/react@^16.3.0, @testing-library/user-event@^13.5.0, framer-motion@^12.6.5, react@^19.1.0, react-dom@^19.1.0, react-scripts@^3.0.1, web-vitals@^2.1.4
### Recent commits (newest first)
- Final changes
- final updates
- Update App.js
- initial commit
## Key source files (fetched from GitHub, selected and truncated for size)
### package.json
```
{
"name": "adaptive-math-app",
"version": "0.1.0",
"private": true,
"dependencies": {
"@testing-library/dom": "^10.4.0",
"@testing-library/jest-dom": "^6.6.3",
"@testing-library/react": "^16.3.0",
"@testing-library/user-event": "^13.5.0",
"framer-motion": "^12.6.5",
"react": "^19.1.0",
"react-dom": "^19.1.0",
"react-scripts": "^3.0.1",
"web-vitals": "^2.1.4"
},
"scripts": {
"start": "NODE_OPTIONS=--openssl-legacy-provider react-scripts start",
"build": "react-scripts build",
"test": "react-scripts test",
"eject": "react-scripts eject"
},
"eslintConfig": {
"extends": [
"react-app",
"react-app/jest"
]
},
"browserslist": {
"production": [
">0.2%",
"not dead",
"not op_mini all"
],
"development": [
"last 1 chrome version",
"last 1 firefox version",
"last 1 safari version"
]
}
}
```
### src/index.js
```javascript
import React from 'react';
import ReactDOM from 'react-dom/client';
import './index.css';
import App from './App';
import reportWebVitals from './reportWebVitals';
const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
);
// If you want to start measuring performance in your app, pass a function
// to log results (for example: reportWebVitals(console.log))
// or send to an analytics endpoint. Learn more: https://bit.ly/CRA-vitals
reportWebVitals();
```
### src/App.js
```javascript
import React, { useState, useEffect, useRef } from "react";
// Utility functions
const getRandomInt = (min, max) => Math.floor(Math.random() * (max - min + 1)) + min;
// Question generation logic based on selected topics
const generateQuestion = (level, topics) => {
const range = level * 5;
const a = getRandomInt(-range, range); // Allow negative values for all operations
const b = getRandomInt(-range, range); // Allow negative values for all operations
const randomTopic = topics[Math.floor(Math.random() * topics.length)];
let question, answer;
switch (randomTopic) {
case "addition":
question = `${a} + ${b}`;
answer = a + b;
break;
case "subtraction":
question = `${a} - ${b}`;
answer = a - b;
break;
case "multiplication":
question = `${a} × ${b}`;
answer = a * b;
break;
case "division":
// Avoid division by zero and ensure the quotient is correct
const divisor = b === 0 ? 1 : b;
question = `${a * divisor} ÷ ${divisor}`;
answer = a;
break;
default:
question = `${a} + ${b}`;
answer = a + b;
break;
}
return { question, answer, topic: randomTopic };
};
const getExplanation = (question, answer) => {
const [left, op, right] = question.split(" ");
const a = parseInt(left);
const b = parseInt(right);
let tip = "";
switch (op) {
case "+":
tip = "Add the numbers together.";
break;
case "-":
tip = "Subtract the second number from the first.";
break;
case "*":
tip = "Multiply the two numbers together.";
break;
case "÷":
tip = "Divide the first number by the second.";
break;
default:
tip = "Follow the appropriate math operation.";
}
return {
tip,
explanation: `${left} ${op} ${right} = ${answer}.\n${tip}`,
};
};
// AI feedback using Gemini API
const getAIFeedback = async (question, isCorrect) => {
const apiUrl =
"https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=AIzaSyBLshtfE2XUAX2O6L23MigyaPt2mTua7j0";
const prompt = isCorrect
? `The student answered correctly. Offer positive reinforcement and a quick follow-up tip for this math question: ${question}`
: `The student answered incorrectly. Give a helpful, step-by-step explanation for how to solve this math question: ${question}`;
try {
const response = await fetch(apiUrl, {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
contents: [{ parts: [{ text: prompt }] }],
}),
});
const data = await response.json();
if (data && data.candidates && data.candidates.length > 0) {
return data.candidates[0].content.parts[0].text;
}
return "No feedback was returned.";
} catch (error) {
console.error("Error fetching AI feedback:", error);
return "Sorry, we couldn't retrieve AI feedback at this time.";
}
};
function calculateNextLevel(history) {
const recent = history.slice(-5);
const correctRatio = recent.filter((h) => h.correct).length / recent.length;
const avgTime = recent.reduce((sum, h) => sum + h.timeTaken, 0) / recent.length;
if (correctRatio >= 0.8 && avgTime < 10) {
return Math.min(history.at(-1).level + 1, 10);
} else if (correctRatio < 0.5 || avgTime > 20) {
return Math.max(history.at(-1).level - 1, 1);
} else {
return history.at(-1).level;
}
}
export default function AdaptiveMathApp() {
const [level, setLevel] = useState(1);
const [questionObj, setQuestionObj] = useState({});
const [userAnswer, setUserAnswer] = useState("");
const [history, setHistory] = useState([]);
const [startTime, setStartTime] = useState(Date.now());
const [topics, setTopics] = useState({
addition: false,
subtraction: false,
multiplication: false,
division: false,
});
const [isStarted, setIsStarted] = useState(false); // To track if the user has selected topics
const containerRef = useRef(null);
const currentTileRef = useRef(null);
const handleSubmit = async () => {
const numericAnswer = parseFloat(userAnswer);
const correct = numericAnswer === questionObj.answer;
const timeTaken = (Date.now() - startTime) / 1000;
const newFeedback = {
question: questionObj.question,
correct,
answer: questionObj.answer,
level,
timeTaken,
aiFeedback: null, // Will be filled on button click
...getExplanation(questionObj.question, questionObj.answer),
};
const newHistory = [...history, newFeedback];
setHistory(newHistory);
const nextLevel = calculateNextLevel(newHistory);
setLevel(nextLevel);
setUserAnswer("");
setQuestionObj(generateQuestion(nextLevel, Object.keys(topics).filter((topic) => topics[topic]))); // Generate question based on selected topics
setStartTime(Date.now());
};
useEffect(() => {
if (currentTileRef.current && containerRef.current) {
currentTileRef.current.scrollIntoView({ behavior: "smooth", block: "center" });
}
}, [history]);
const accuracy = history.length
? (history.filter((h) => h.correct).length / history.length) * 100
: 0;
const handleTopicSelection = (event) => {
setTopics((prev) => ({
...prev,
[event.target.name]: event.target.checked,
}));
};
const handleStart = () => {
if (Object.values(topics).includes(true)) {
setIsStarted(true); // Start the question flow if at least one topic is selected
setQuestionObj(generateQuestion(level, Object.keys(topics).filter((topic) => topics[topic]))); // Generate first question based on selected topics
} else {
alert("Please select at least one topic to start!");
}
};
if (!isStarted) {
// Display topic selection screen
return (