ClassMG/README.md

# ClassMG - Interactive Classroom Management System

[English (Current)](README.md) | [中文版](README_CN.md)

## Overview

ClassMG is a comprehensive classroom management application designed for interactive teaching and learning. The system enables real-time communication between teachers and students, interactive question sessions, and immediate feedback mechanisms, all within a unified digital classroom environment.

## System Architecture

ClassMG is built on a client-server architecture:

- **Client Application**: Developed using HarmonyOS ArkTS for cross-device compatibility
- **Communication Server**: Node.js based server that enables real-time message passing and state synchronization
- **Local Data Storage**: Secure local storage for user credentials and session data

## Core Features

### 1. Classroom Management
- **Create Classroom**: Teachers can create virtual classrooms with unique access codes
- **Join Classroom**: Students can join using classroom codes
- ~~**Classroom Status**: Real-time monitoring of active participants~~
- **End Classroom**: Teachers can terminate sessions with proper notification to all participants

### ~~2. Real-time Communication~~
- **Instant Messaging**: Bi-directional communication between teachers and students
- **Message Synchronization**: Robust message delivery with automatic retry mechanisms
- **Connection Status**: Visual indicators for connection status with troubleshooting options

### 3. Interactive Questions
- **Question Publishing**: Teachers can create and publish multiple-choice questions
- **Timed Responses**: Configurable time limits for answering questions
- **Answer Submission**: Students can submit answers with immediate confirmation
- **Result Analysis**: Visual presentation of response statistics and correctness rates

### 4. User Experience
- **Adaptive Layout**: Responsive interface that works across different screen sizes
- **Visual Feedback**: Clear status indicators for all operations
- **Error Handling**: Comprehensive error notifications with recovery options
- **Theme Customization**: Personalized visual appearance settings

## Operation Logic

### Authentication Flow
1. Users register with username and password (stored securely)
2. Login verification against local credentials
3. Role assignment (teacher or student) determines available features

### Classroom Session Flow
1. Teacher creates a classroom with a unique code
2. Students join using the provided code
3. Real-time synchronization establishes the classroom environment
4. Teacher and students can exchange messages and participate in question sessions
5. Teacher can end the classroom session, which notifies all participants

### Messaging System
1. Messages are composed and sent from the input area
2. Local preview appears immediately for responsive UX
3. Messages are transmitted to the server
4. Server broadcasts messages to all connected devices
5. Polling mechanism ensures message delivery, even after temporary disconnections

### Question Management
1. Teacher creates questions with multiple-choice options
2. Students receive questions with configurable countdown timers
3. Responses are collected and synchronized across devices
4. Results are computed and displayed after the question ends
5. Teachers can view detailed statistics while students see personal results

## Technical Implementation

### Communication Protocol
- HTTP-based API for classroom operations
- Polling mechanism for state synchronization
- JSON message format for data exchange

### Data Security
- Local credential storage with encryption
- Classroom access controlled via unique codes
- Session validation for all operations

### Synchronization Mechanism
- Server maintains the source of truth for classroom state
- Client polling ensures data consistency
- Conflict resolution strategies for concurrent operations

### Error Handling
- Connection status monitoring
- Automatic reconnection attempts
- User-friendly error messages with recovery options

## Server Setup

### Prerequisites
- Node.js (v12 or higher)
- NPM (Node Package Manager)

### Installation
1. Install Node.js and NPM
2. Clone or download the repository
3. Install dependencies with `npm install`

### Running the Server
1. Start with `npm start` or `node server.js`
2. Server will run on port 5243 by default
3. Note your computer's IP address for client configuration

## Client Configuration

### Development Environment
- DevEco Studio (recommended)
- HarmonyOS SDK

### Connection Setup
1. Ensure all devices are on the same network
2. Configure the server address in the client application
3. Compile and deploy to testing devices

## Troubleshooting

### Connection Issues
- Verify all devices are on the same network
- Check server IP address and port configuration
- Use the built-in connection status checker in the application

### Message Synchronization
- If messages aren't appearing across devices, check connection status
- Verify server is running properly
- Try reconnecting using the in-app troubleshooting button

### Layout Problems
- If UI elements are misaligned or appear off-screen, restart the application
- Different device screen sizes may require application restart after significant layout changes

## Notes for Developers

- The system uses a polling mechanism rather than WebSockets for compatibility reasons
- Message deduplication is implemented to handle potential duplicate delivery
- UI layouts are optimized for both tablet and smartphone form factors
- Debug logging can be enabled for troubleshooting purposes

---

**Note**: This document provides an overview of the ClassMG system. For detailed API documentation and developer guides, please refer to the technical documentation.