🎓 Skibidi Revision

# 📝 Skibidi Revision App (Post-Refactor ✅)

A fun, AI-powered PHP quiz app designed to help students (like Bob!) revise throughout the day — topic by topic, subject by subject — in short bursts. 🎓✨

**AUTHOR:** Abstract Warlock 
**CO-DEVELOPMENT:** Claude Sonnet 4.5
**DATE:** 12 November 2025
**LICENSE:** None

---

## 📌 Overview

Skibidi Revision is a mobile-friendly, themeable, browser-based revision quiz platform. Built for daily learning motivation, powered by OpenAI for smart feedback, and backed by a clean MySQL structure. Now with **year-level filtering** and **secure password-based login**!

You can:
- Jump into any subject for a specific school year
- Answer as many questions as you want
- Get instant AI-marked feedback
- Track progress live with beautifully styled UI

---

## ✅ Refactored Architecture (2025)

- 🔥 Session-less quiz state (only player name stored)
- 🔐 **Password-based login** for existing users
- 🗓️ **Year-level filtering** for questions and progress
- 🔄 All questions & answers from MySQL
- 💡 AI-scored answers with detailed feedback
- 📊 DB-powered daily summary with progress bar
- 🎨 Fully themed with Bootstrap 5 and emoji icons
- 📁 Controllers handle logic → Views handle UI

---

## 🧱 Core Features

### 📚 Daily Quiz Flow
- Select a school year to filter subjects
- Subjects shown as beautiful cards
- Each click = new random question (never repeated today for the selected year/subject)
- Submit answer → see score + correct answer + AI explanation

### 🧠 Scoring
- Answers scored by AI out of 5
- Score ≥ 3 = correct
- Daily stats: correct %, points %, per-subject totals **(now year-specific)**

### 🎯 Clean Views
- `menu`, `question`, `feedback`, `results` all share consistent layout and styling

### 🌈 Themes
- `Teacher`, `Dad`, and `Wife` — can be toggled in UI
- CSS loads via `styles.css?v=<?= time() ?>` for updates

---

## 🗃️ Data Model

### users 

| Field        | Type        |
|--------------|-------------|
| id           | INT (PK)    |
| name         | VARCHAR     |
| password_hash| VARCHAR     | (for secure login)
| created_at   | TIMESTAMP   |

### revision_questions 

| Field       | Type        |
|-------------|-------------|
| id          | INT (PK)    |
| subject     | VARCHAR     |
| topic       | VARCHAR     |
| year        | INT         | (school year level)
| question    | TEXT        |
| answer      | TEXT        |
| type        | VARCHAR     |
| options     | JSON (nullable) |
| created_at  | TIMESTAMP   |

### daily_answers 

| Field        | Type        |
|--------------|-------------|
| id           | INT (PK)    |
| user_id      | INT (FK)    |
| date         | DATE        |
| subject      | VARCHAR     |
| question_id  | INT (FK)    |
| user_answer  | TEXT        |
| ai_score     | INT         |
| ai_feedback  | TEXT        |
| created_at   | TIMESTAMP   |

---

## 🧠 AI Answer Logic

OpenAI (gpt-4.1-mini) evaluates each answer:

- Uses fixed prompt logic (do not alter the scoring prompt)
- Types: `factual_recall`, `multiple_choice`, `explanation`, etc.
- AI returns:
  - `score` (0–5)
  - `isCorrect`
  - `aiExplanation`

---

## 🖥️ Project Structure

```
/
├── index.php                  # Front controller
├── config.php                 # DB + OpenAI config
├── functions.php              # Utilities + score summary
├── openai.php                 # AI scoring
├── controllers/
│   ├── login_controller.php
│   ├── quiz_controller.php
│   ├── answer_controller.php
│   ├── theme_controller.php
│   └── menu_controller.php
├── views/
│   ├── partials/
│   │   ├── header.php
│   │   ├── footer.php
│   │   └── progress.php
│   ├── login_prompt.php
│   ├── menu.php
│   ├── question.php
│   ├── feedback.php
│   └── results.php
└── data/                      # Migration input JSONs (optional)
```

---

## 🚀 Setup

1. Clone repo and upload to PHP server
2. Import the DB schema (see `/sql/` or refactor docs) and **ensure you've added the `year` column to `revision_questions` and `password_hash` to `users`**.
3. **Populate the `year` column** in your `revision_questions` table for all relevant questions.
4. Add OpenAI key to `config.php`
5. Ensure `SESSION` and `PDO` are enabled
6. Visit `index.php` and enter your name. **The first time you log in, you will be prompted to set a password.**

---

## 🛠 TODO

These are polish/future ideas you may want to add soon:

- [ ] Refactor `results.php` into full `results_controller.php`
- [ ] views/menu.php needs slight width/style tweeks
- [ ] Highlight current subject icon in header
- [ ] Merge daily progress bar into header across all pages
- [ ] Leaderboard (daily/weekly)
- [ ] Optional: Smooth transition animations (between views)
- [ ] Optional: Per-topic completion tracking
- [ ] Optional: Full admin question editor
- [ ] Optional: Theme "Dad Mode" and "Wife Mode" CSS final polish

---

## 💬 Credits

Built with ❤️ for Bob — by his team of nerdy, helpful, fun-grown-ups™.  
If you're reading this and thinking "wow this is actually solid" — we agree.

Want a print version?  
🫡 We’ll turn it into a book called *"Refactor Wars: The Session Menace."*

---