diff --git a/Readme.md b/Readme.md index 85c92a4..8a02a9b 100644 --- a/Readme.md +++ b/Readme.md @@ -1,109 +1,359 @@ -# ๐Ÿ“ Spelling App +# ๐Ÿ“ Modern Spelling & Typing Practice App -A lightweight, multi-user spelling practice app with admin controls, customizable themes, and per-user word list management. Built with **Node.js**, **Express**, and **Docker**. ---- -## [Watch the video](https://www.youtube.com/watch?v=K29zCFZPEjE) -[![alt text](https://img.youtube.com/vi/K29zCFZPEjE/0.jpg)](https://www.youtube.com/watch?v=K29zCFZPEjE) +A comprehensive educational application featuring spelling practice, typing exercises, and Bible verse typing with mode## โš™๏ธ Features Overview + +### ๐ŸŽ“ St### ๐Ÿ‘จโ€๐Ÿ’ผ Admin Panel Featuresde--- + +## ๐Ÿ”ง Configuration + +## ๐Ÿ›ก๏ธ Security Features## Environment VariablestivitiesUI design. Built with **Node.js**, **Express**, and optimized for Docker deployment. --- -## ๐Ÿš€ Quick Start (Docker Compose) +## [Watch the Demo Video](https://www.youtube.com/watch?v=K29zCFZPEjE) +[![Demo Video](https://img.youtube.com/vi/K29zCFZPEjE/0.jpg)](https://www.youtube.com/watch?v=K29zCFZPEjE) -Clone and run from anywhere using Docker Compose: +--- +## ๐Ÿš€ Installation Options + +### Option 1: Docker (Recommended) + +#### Quick Start with Docker Compose ```bash git clone https://git.necloud.us/nmemmert/Spelling.git cd Spelling -docker-compose up --build +docker-compose up -d ``` -Then visit: ๐Ÿ‘‰ http://localhost:3000 +#### Using Pre-built Container +```bash +# Pull and run the latest container +docker run -d \ + --name spelling-app \ + -p 3000:3000 \ + -v ./data:/app/data \ + --restart unless-stopped \ + git.necloud.us/nmemmert/spelling:latest +``` +#### Custom Docker Compose +```yaml +version: "3.9" +services: + spelling-app: + image: git.necloud.us/nmemmert/spelling:latest + container_name: spelling-app + ports: + - "3000:3000" + volumes: + - ./data:/app/data + restart: unless-stopped + environment: + - NODE_ENV=production +``` -## ๐Ÿ‘ฅ Default Login +### Option 2: CasaOS Installation -| Username | Password | Role | -|-----------|----------|--------| -| admin1 | password | Admin | -| student1 | 123456 | Student| +#### Method 1: One-Click Install (Recommended) +1. **Open CasaOS Dashboard** in your web browser +2. Navigate to **App Store** โ†’ **Custom Install** +3. **Paste this complete Docker Compose configuration:** -> You can add new users from the Admin Panel. +```yaml +name: spelling-practice-app +services: + spelling-app: + image: git.necloud.us/nmemmert/spelling:latest + container_name: spelling-practice + ports: + - "3000:3000" + volumes: + - /DATA/AppData/spelling:/app/data + restart: unless-stopped + environment: + - NODE_ENV=production + labels: + - "casaos.name=Spelling Practice" + - "casaos.icon=๐Ÿ“" + - "casaos.category=Education" + - "casaos.description=Modern spelling and typing practice application" -## โš™๏ธ Features +x-casaos: + author: NMemmert + category: Education + description: + en_us: "A comprehensive educational application featuring spelling practice, typing exercises, and Bible verse typing with modern UI design." + developer: "NMemmert" + icon: "๐Ÿ“" + screenshot_link: "" + tagline: + en_us: "Modern Spelling & Typing Practice" + thumbnail: "" + title: + en_us: "Spelling Practice App" + tips: {} + port_map: "3000" +``` -# ๐ŸŽฎ Student-Facing Features +4. **Click Install** and wait for deployment to complete +5. **Access the app** via CasaOS Dashboard or directly at `http://your-casaos-ip:3000` -- **Word Game Session** - Timed word presentation with answer input and summary feedback +> **๐Ÿ’ก Tip**: The app will automatically appear in your CasaOS dashboard with the ๐Ÿ“ icon after installation -- **Retry Missed Words** - Quick review round for any words answered incorrectly +#### Method 2: Manual CasaOS Installation +1. **Access CasaOS Terminal**: + - Open CasaOS Dashboard + - Go to **Terminal** or **SSH** into your CasaOS system -- **Result Summary Panel** - Shows score, accuracy percentage, and answers with color-coded feedback +2. **Create application directory:** + ```bash + mkdir -p /DATA/AppData/spelling + cd /DATA/AppData/spelling + ``` -- **๐ŸŽ– Badge Display Section** - Earned badges appear after each session based on milestone triggers +3. **Create docker-compose.yml file:** + ```bash + nano docker-compose.yml + ``` + +4. **Add this configuration and save:** + ```yaml + version: "3.9" + services: + spelling-app: + image: git.necloud.us/nmemmert/spelling:latest + container_name: spelling-practice + ports: + - "3000:3000" + volumes: + - /DATA/AppData/spelling:/app/data + restart: unless-stopped + environment: + - NODE_ENV=production + ``` -- **Responsive Design** - Touch-friendly interface optimized across devices +5. **Deploy the application:** + ```bash + docker-compose up -d + ``` + +6. **Verify deployment:** + ```bash + docker ps | grep spelling-practice + ``` + +7. **Add to CasaOS Dashboard** (Optional): + - Go to CasaOS **Settings** โ†’ **Custom Apps** + - Click **Add Custom App** + - **Name**: "Spelling Practice" + - **URL**: `http://localhost:3000` + - **Icon**: ๐Ÿ“ (or upload custom icon) + - **Category**: Education + +#### CasaOS-Specific Notes: +- **Data Location**: All user data is stored in `/DATA/AppData/spelling/` +- **Automatic Restart**: Container will restart automatically with CasaOS +- **Port Access**: App will be accessible on port 3000 +- **Updates**: Use CasaOS container management to update the image +- **Backups**: Data directory can be backed up through CasaOS file manager + +#### Troubleshooting CasaOS Installation: +```bash +# Check if container is running +docker ps + +# View container logs +docker logs spelling-practice + +# Restart container if needed +docker restart spelling-practice + +# Check port availability +netstat -tlnp | grep :3000 +``` + +### Option 3: Manual Installation +```bash +# Clone repository +git clone https://git.necloud.us/nmemmert/Spelling.git +cd Spelling + +# Install dependencies +npm install + +# Start application +npm start +``` --- -# ๐Ÿ“‹ Admin Panel Features +## ๐ŸŒ Access & Default Credentials -- **User Management** - Add and remove student accounts from the system +After installation, access the application at: +- **Local**: http://localhost:3000 +- **CasaOS**: http://your-casaos-ip:3000 -- **Word List Editor** - Customize spelling lists per student +### Default Login Credentials -- **Game Preview & Play Trigger** - Admins can test gameplay directly +| Username | Password | Role | Description | +|-----------|----------|---------|-------------| +| admin1 | password | Admin | Full access to admin panel | +| student1 | 123456 | Student | Access to practice activities | -- **Analytics Tab** - Aggregate stats like average scores, most missed words, and per-student breakdown - -- **Badge Viewer Tab** - Shows every user's earned badges and lets admins inspect progress visually - -- **Reports Tab** - Print-friendly HTML summaries per student with words, scores, and badges - -- **Clipboard Copy Button** - Quick export for emailing or recordkeeping +> ๐Ÿ” **Important**: Change default passwords immediately after first login via Admin Panel โ†’ Password Management --- -# ๐Ÿ”„ Server-Side Logic +## โš™๏ธ Features Overview -- **Structured Result Saving** - Stores user sessions with score, completion status, and answer accuracy +### ๏ฟฝ Student Activities -- **Badge Awarding & Storage** - Server tracks earned achievements in `badges.json` +#### ๐Ÿ“ **Spelling Practice** +- Interactive word-by-word spelling challenges +- Real-time feedback with visual indicators +- Customizable word lists per student +- Progress tracking and accuracy scoring +- Retry system for missed words -- **Safe Data Handling** - Validates all inputs and formats before writing JSON +#### โŒจ๏ธ **Typing Practice** +- Speed and accuracy typing exercises +- WPM (Words Per Minute) calculation +- Error highlighting and correction +- Progressive difficulty levels +- Performance analytics + +#### ๐Ÿ“– **Bible Typing (ESV)** +- 15 popular Bible verses for typing practice +- Verse-by-verse comparison and accuracy analysis +- Word-level error detection and highlighting +- Spiritual growth through Scripture memorization +- Progress tracking for Bible study + +### ๐Ÿ› ๏ธ **Student Features** +- **Theme Selection**: Choose from multiple UI themes +- **Progress Dashboard**: View personal statistics and achievements +- **Badge System**: Earn badges for milestones and consistent practice +- **Responsive Design**: Optimized for desktop, tablet, and mobile +- **Clean Interface**: Modern, distraction-free learning environment --- -# ๐Ÿš€ Upcoming Features (in progress or proposed) +### ๐Ÿ‘จโ€๏ฟฝ Admin Panel Features -- **Multi-Session History Tracking** - Store multiple results per user for trends and performance graphs +#### ๐Ÿ“Š **User Management** +- Add, edit, and remove student accounts +- Role-based access control (Admin/Student) +- Password management and reset capabilities +- User activity monitoring -- **Performance Trends Viewer** - Line/bar charts to show score progression over time +#### ๐Ÿ“ **Content Management** +- **Word List Editor**: Create and customize spelling lists per student +- **Bulk Import**: Upload word lists from text/CSV files +- **Category Organization**: Organize words by topics or difficulty +- **Preview Mode**: Test activities before assigning to students -- **Practice Streak Badges** - Awarded for consistent use across days +#### ๐Ÿ“ˆ **Analytics & Reporting** +- **Performance Analytics**: Track student progress and trends +- **Detailed Reports**: Generate comprehensive progress reports +- **Export Options**: Download data for external analysis +- **Visual Charts**: Graphical representation of student performance -- **Thematic Word Lists** - Organize challenges by topic (e.g. animals, tech, holidays) +#### ๐Ÿ† **Badge Management** +- **Achievement System**: Configure milestone badges +- **Progress Tracking**: Monitor student achievements +- **Custom Badges**: Create custom rewards for specific goals +- **Badge Viewer**: Visual display of all earned achievements -- **Email Export Button** - Opens a pre-filled `mailto:` with progress summary text +#### โš™๏ธ **System Administration** +- **Password Management**: Change admin and student passwords +- **Security Controls**: Manage access permissions +- **Data Backup**: Export/import user data and settings +- **System Monitoring**: View application health and usage -- **PDF Export Option** - Convert report data into downloadable documents +--- + +## ๏ฟฝ Configuration + +### Environment Variables +```bash +# Optional environment variables +NODE_ENV=production # Set to production for deployment +PORT=3000 # Application port (default: 3000) +``` + +### Data Persistence +The application stores data in JSON files: +- `data/users.json` - User accounts and authentication +- `data/wordlists.json` - Custom word lists per student +- `data/results.json` - Student progress and results +- `data/badges.json` - Achievement and badge data + +### Volume Mapping +For Docker installations, map the data directory: +```bash +-v /host/data/path:/app/data +``` + +--- + +## ๏ฟฝ๏ธ Security Features + +- **Password Hashing**: SHA-256 encryption for all passwords +- **Role-Based Access**: Separate admin and student interfaces +- **Session Management**: Secure login/logout functionality +- **Input Validation**: Protection against common security vulnerabilities +- **Data Isolation**: Per-user data segregation + +--- + +## ๐Ÿ”„ Updates & Maintenance + +### Updating the Application +```bash +# Pull latest image +docker pull git.necloud.us/nmemmert/spelling:latest + +# Restart container +docker-compose down && docker-compose up -d +``` + +### Backup Data +```bash +# Backup user data +docker cp spelling-app:/app/data ./backup-$(date +%Y%m%d) +``` + +### Logs & Troubleshooting +```bash +# View application logs +docker logs spelling-app + +# Follow live logs +docker logs -f spelling-app +``` + +--- + +## ๐Ÿค Support & Contributing + +- **Issues**: Report bugs and feature requests +- **Documentation**: Comprehensive setup guides +- **Community**: Educational technology discussions + +### Technical Specifications +- **Backend**: Node.js 18+ with Express.js +- **Frontend**: Vanilla JavaScript with modern CSS +- **Storage**: JSON-based file system +- **Container**: Multi-stage Docker build (293MB) +- **Security**: SHA-256 password hashing, role-based access + +--- + +## ๐Ÿ“„ License + +This project is designed for educational use and community deployment. + +--- + +*Built with โค๏ธ for educators and students everywhere* diff --git a/data/results.json b/data/results.json index ec3db51..5a1f230 100644 --- a/data/results.json +++ b/data/results.json @@ -39,6 +39,33 @@ } ], "timestamp": "2025-07-07T12:14:21.058Z" + }, + { + "score": 5, + "completed": true, + "answers": [ + { + "word": "computer", + "correct": true + }, + { + "word": "keyboard", + "correct": true + }, + { + "word": "mouse", + "correct": true + }, + { + "word": "screen", + "correct": true + }, + { + "word": "printer", + "correct": true + } + ], + "timestamp": "2025-07-15T14:36:13.273Z" } ] } \ No newline at end of file diff --git a/data/wordlists.json b/data/wordlists.json index 0604ecb..fa05c1a 100644 --- a/data/wordlists.json +++ b/data/wordlists.json @@ -1,13 +1,21 @@ { - "student1": [], + "student1": [ + "apple", + "banana", + "cherry", + "date", + "elderberry" + ], "admin1": [ "boy", "bot", "snot" ], "nate": [ - "not", - "bot", - "snot" + "computer", + "keyboard", + "mouse", + "screen", + "printer" ] } \ No newline at end of file diff --git a/debug-login.js b/debug-login.js new file mode 100644 index 0000000..0e5d8b7 --- /dev/null +++ b/debug-login.js @@ -0,0 +1,17 @@ +// Debug script to check password hashes +const { createHash } = require('crypto'); + +function hashPassword(password) { + return createHash('sha256').update(password).digest('hex'); +} + +console.log('Testing password hashes:'); +console.log('password -> ', hashPassword('password')); +console.log('123456 -> ', hashPassword('123456')); +console.log('test -> ', hashPassword('test')); + +// Known hashes from users.json: +console.log('\nExpected hashes from users.json:'); +console.log('admin1 (password): 5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8'); +console.log('student1 (123456): 8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92'); +console.log('nate: 5a2a558c78d3717db731600c4f354fa1d9c84b556f108091a891f444f1bdec40'); diff --git a/migrateResults.js b/migrateResults.js deleted file mode 100644 index 62b082b..0000000 --- a/migrateResults.js +++ /dev/null @@ -1,16 +0,0 @@ -const fs = require('fs'); -const path = require('path'); - -const resultsPath = path.join(__dirname, 'data', 'results.json'); -const existingData = JSON.parse(fs.readFileSync(resultsPath)); - -for (const username in existingData) { - const singleResult = existingData[username]; - existingData[username] = [{ - ...singleResult, - timestamp: new Date().toISOString() - }]; -} - -fs.writeFileSync(resultsPath, JSON.stringify(existingData, null, 2)); -console.log("โœ… Migration complete. Results are now session arrays."); \ No newline at end of file diff --git a/package.json b/package.json index 004722c..fb5199d 100644 --- a/package.json +++ b/package.json @@ -1,19 +1,27 @@ { - "name": "spelling", - "version": "1.0.0", + "name": "modern-spelling-practice", + "version": "2.0.0", + "description": "A modern, multi-user spelling practice application with admin controls, customizable themes, and analytics", "main": "server.js", "scripts": { - "test": "echo \"Error: no test specified\" && exit 1", - "start": "node server.js" + "start": "node server.js", + "dev": "node server.js", + "test": "echo \"No tests specified\" && exit 0" }, "repository": { "type": "git", "url": "https://git.necloud.us/nmemmert/Spelling.git" }, - "keywords": [], - "author": "", + "keywords": [ + "spelling", + "education", + "practice", + "nodejs", + "express", + "learning" + ], + "author": "NateEmmert", "license": "ISC", - "description": "", "dependencies": { "express": "^5.1.0" } diff --git a/public/index.html b/public/index.html index 82e527f..8d55886 100644 --- a/public/index.html +++ b/public/index.html @@ -1,201 +1,450 @@ - - - Spelling App with Roles - - - - - - - - - - + + + โœจ Modern Spelling Practice + + + + + + + + + + + - -

Spelling Practice

- - - - - -
-

User Login

-
- - - -
-

-
- - - - - -