nate/homeschool
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

major update

Browse Source
This commit is contained in:
nate@necloud.us committed 2025-07-15 11:43:31 -04:00
1 parent 6029d6f244
commit 474235f94d
8 files changed
+895 -184
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

Readme.md
+315 -65
View File
@@ -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*