# Project export: StudyWithKat 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 2026 - Tagline: StudyWithKat is a Tamagotchi-style education app that gamifies flashcards, quizzes, and Pomodoro focus, rewarding learning progress with coins to care for an interactive virtual cat. - Devpost: https://devpost.com/software/temp-2eh69k - GitHub: https://github.com/xushengou/2x2 - Video: https://www.youtube.com/embed/KdDG7rDYqTU?enablejsapi=1&hl=en_US&rel=0&start=&version=3&wmode=transparent - Team: 0 GitHub contributor(s) — ## Devpost submission (written by the team) ### Inspiration We wanted to create a tool that not only makes studying productive but also rewarding. Inspired by the Tamagotchi style, StudyWithKat enhances the learning experience to be interactive and motivating, allowing students to incentivize their learning. ### What it does StudyWithKat is a Tamagotchi-style education app that transforms studying into a game. Users can earn coins by completing learning inspired tasks such as creating flashcards, taking quizzes, and using the focus mode. The coins can be used to take care of your interactive virtual cat, which reflects the user’s effort towards studying with Kat. ### How we built it We built StudyWithKat using HTML, CSS, and JavaScript to create the frontend. The backend was built with Flask to send and receive information from Firebase, bridging our frontend to our database. Firebase was used for data storage and authentication, while the ChatGPT API is used for creating flashcard generation from file imports, quizzes, and daily tasks. ### Challenges we ran into We encountered challenges connecting our HTML frontend to our Firebase database. This obstacle slowed our progress and ultimately prevented us from implementing some of the additional features we wanted to include. This experience provided us with insight into database integration and helped us understand the importance of preparing for potential connectivity issues. ### Accomplishments we're proud of While developing StudyWithKat, we took pride in planning early and monitoring tasks with a well-organized task list. Having a clear structure allowed us to make progress promptly. Completing the frontend felt like a major accomplishment, as it was one crucial component to establishing the app. ### What we learned As our codebase became more complex, we realized the importance of outlining our plans for the frontend and backend components. Keeping active communication between both sides was vital to ensuring that features were implemented effectively. This taught us that efficient collaboration and planning are just as crucial as writing code when it comes to developing a functional app. ## README (from the GitHub repository) No README available. ## Detected evidence (automated analysis) Indexed codebase: 20 recognized source files, 123 KB. - CSS (language) — detected in the code - Flask (technology) — detected in the code - HTML (language) — detected in the code - JavaScript (language) — detected in the code - OpenAI (technology) — detected in the code - Python (language) — detected in the code - Firebase (technology) — claimed on Devpost, not found in the code ## Codebase structure (from repository index) ### Files (27 of 27) ``` .DS_Store .gitignore .vscode/settings.json app.py flashcardtest.txt requirements.txt template/.DS_Store template/dashboard.html template/login.html template/scripts/daily_quests.js template/scripts/firebase_sync.js template/scripts/flashcards_study_modal.js template/scripts/flashcards_sync.js template/scripts/focus_timer.js template/scripts/logout_fix.js template/scripts/pet_chat_ai.js template/scripts/pet_sync.js template/scripts/pet.js template/scripts/profile_edit.js template/scripts/script_auth.js template/scripts/script.js template/scripts/sidebar_hover_fix.js template/scripts/timer.js template/scripts/todo_sync.js template/signup.html template/styles/.DS_Store template/styles/style.css ``` ### Dependencies - requirements.txt: firebase-admin@==6.5.0, Flask@==3.0.3, flask-cors@==4.0.1, gunicorn@==22.0.0, openai, python-dotenv@==1.0.1, requests@==2.32.3 ### Recent commits (newest first) - Initial clean commit ## Key source files (fetched from GitHub, selected and truncated for size) ### requirements.txt ``` Flask==3.0.3 flask-cors==4.0.1 firebase-admin==6.5.0 python-dotenv==1.0.1 requests==2.32.3 gunicorn==22.0.0 openai ``` ### app.py ```python import os import random import datetime from functools import wraps import requests from dotenv import load_dotenv from flask import Flask, request, jsonify, session, send_from_directory, redirect from flask_cors import CORS import firebase_admin from firebase_admin import credentials, auth, firestore # OpenAI is optional (only needed for /api/petchat) try: from openai import OpenAI except Exception: OpenAI = None # ============================== # Config / init # ============================== load_dotenv() BASE_DIR = os.path.dirname(os.path.abspath(__file__)) TEMPLATE_DIR = os.path.join(BASE_DIR, "template") # Serve HTML from /template and also serve static assets from /template # so links like /styles/style.css and /scripts/script.js work. app = Flask( __name__, template_folder="template", static_folder="template", static_url_path="", ) # Cookies (helps with session) app.config.update( SESSION_COOKIE_HTTPONLY=True, SESSION_COOKIE_SAMESITE="Lax", ) CORS(app, supports_credentials=True) # REQUIRED ENV VARS: # - FLASK_SECRET_KEY # - FIREBASE_API_KEY # - GOOGLE_APPLICATION_CREDENTIALS (path to serviceAccountKey.json) app.secret_key = os.getenv("FLASK_SECRET_KEY", "dev_change_me") FIREBASE_API_KEY = os.getenv("FIREBASE_API_KEY") SERVICE_ACCOUNT_JSON = os.getenv("GOOGLE_APPLICATION_CREDENTIALS") # Friendly fallback: if GOOGLE_APPLICATION_CREDENTIALS is not set, # try serviceAccountKey.json in the project folder. if not SERVICE_ACCOUNT_JSON: local_key = os.path.join(BASE_DIR, "serviceAccountKey.json") if os.path.exists(local_key): SERVICE_ACCOUNT_JSON = local_key if not FIREBASE_API_KEY: raise RuntimeError("Missing FIREBASE_API_KEY in .env") if not SERVICE_ACCOUNT_JSON: raise RuntimeError( "Missing GOOGLE_APPLICATION_CREDENTIALS in .env (or serviceAccountKey.json not found next to app.py)" ) if not firebase_admin._apps: firebase_admin.initialize_app(credentials.Certificate(SERVICE_ACCOUNT_JSON)) db = firestore.client() # OpenAI client (optional) OPENAI_API_KEY = os.getenv("OPENAI_API_KEY", "") openai_client = OpenAI(api_key=OPENAI_API_KEY) if (OPENAI_API_KEY and OpenAI) else None # ============================== # Helpers # ============================== def login_required(fn): @wraps(fn) def wrapper(*args, **kwargs): if not session.get("uid"): return jsonify({"error": "Not logged in"}), 401 return fn(*args, **kwargs) return wrapper def user_ref(uid: str): return db.collection("users").document(uid) def ensure_user_doc(uid: str, email: str, username: str = ""): ref = user_ref(uid) snap = ref.get() if snap.exists: return ref ref.set( { "email": email, "username": username, "coins": 0, "pet": {"hunger": 50, "thirst": 50, "health": 50, "happiness": 50}, "flashcard_counter": 0, "todo_counter": 0, "chat": { # No logs stored. Just a persona/settings blob. "persona": "You are a friendly virtual pet. Keep replies short, playful, and encouraging.", }, } ) return ref def parse_int(v, default=None): try: return int(v) except Exception: return default def next_counter(ref, field_name: str) -> int: tx = db.transaction() @firestore.transactional def _inc(transaction): snap = ref.get(transaction=transaction) current = int(snap.get(field_name) or 0) new_val = current + 1 transaction.update(ref, {field_name: new_val}) return new_val return _inc(tx) def firebase_password_login(email: str, password: str): """Firebase Admin SDK cannot verify email/password. Use Firebase Auth REST API signInWithPassword. """ url = ( "https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword" f"?key={FIREBASE_API_KEY}" ) payload = {"email": email, "password": password, "returnSecureToken": True} r = requests.post(url, json=payload, timeout=15) if r.status_code != 200: try: code = r.json().get("error", {}).get("message", "LOGIN_FAILED") except Exception: code = "LOGIN_FAILED" return None, code return r.json(), None # ============================== # Pages # ============================== @app.get("/") def root(): return redirect("/login.html") @app.get("/login.html") def login_page(): return send_from_directory("template", "login.html") @app.get("/signup.html") def signup_page(): return send_from_directory("template", "signup.html") @app.get("/dashboard.html") def dashboard_page(): return send_from_directory("template", "dashboard.html") # ============================== # Auth APIs # ============================== @app.post("/api/signup") def api_signup(): body = request.get_json(silent=True) or {} username = str(body.get("username", "")).strip() email = str(body.get("email", "")).strip() password = str(body.get("password", "")).strip() if not username or not email or not password: return jsonify({"error": "username, email, password required"}), 400 try: u = auth.create_user(email=email, password=password, display_name=username) ensure_user_doc(u.uid, email=email, username=username) # auto login data, err = firebase_password_login(email, password) if err: return jsonify({"error": "Signup succeeded, but login failed", "code": err}), 401 session["uid"] = data["localId"] session["email"] = email return jsonify({"ok": True}) except auth.EmailAlreadyExistsError: return jsonify({"error": "Email already in use"}), 400 except Exception as e: return jsonify({"error": "Signup failed", "detail": str(e)}), 400 @app.post("/api/login") def api_login(): body = request.get_js [truncated — 11725 more characters] ``` ### template/login.html ```html Study-Gotchi | Login

😸 StudyWithKat

Welcome back!

Create Account
``` ### template/signup.html ```html Study-Gotchi | Sign Up

StudyWithKat

Join The Club!

Already a member? Login here!
``` ### template/scripts/logout_fix.js ```javascript async function logout() { try { await fetch("/api/logout", { method: "POST", credentials: "include" }); } catch (e) { // incase of a fail request, it redirects the user away from the dashboard console.warn("Logout request failed:", e); } window.location.href = "login.html"; } ``` ### template/dashboard.html ```html Study-Gotchi | Dashboard
◀