lnet_tutor/exam_system/FINAL_GUIDE.md

Exam System - Complete User Guide

✅ System is Fully Operational!

Your exam system now has complete user management and is ready to use.

🚀 Quick Start

1. Access the Application

Open your browser to: http://localhost

2. Register or Login

Option A: Use Test Account

• Username: testuser
• Password: test123

Option B: Register New Account

1. Go to: http://localhost/login
2. Click "Register here"
3. Fill in:
   • Username (unique)
   • Email (unique)
   • Password (min 6 chars)
   • Confirm password
4. Click "Register"
5. Auto-login after registration

3. Take an Exam

1. You'll see "Python Basics Exam" with status "available"
2. Click "Start Exam"
3. Answer questions (MCQ, True/False, Essay, Code)
4. System autosaves every 10 seconds
5. Watch the timer count down
6. Click "Submit Exam" when done
7. See success page

4. View Your History

1. Click "My History" in the header
2. See all your exam attempts
3. Click "View Results" to review answers
4. Click "Take Again" to retake any exam

📋 Features

User Management

• ✅ User registration with email verification
• ✅ Secure login/logout
• ✅ Session persistence
• ✅ Password hashing

Exam Taking

• ✅ List all published exams
• ✅ Exam status per user (available, in progress, finished)
• ✅ Start new attempts
• ✅ Resume in-progress attempts
• ✅ Timer with auto-submit
• ✅ Autosave every 10 seconds
• ✅ 5 question types supported

Exam History

• ✅ View all your attempts per exam
• ✅ See submission timestamps
• ✅ View detailed results
• ✅ Compare answers with correct ones
• ✅ Retake any exam unlimited times

Data Persistence

• ✅ User database (SQLite with persistent volume)
• ✅ Exam attempts in JSON files
• ✅ Output bundles for each submission
• ✅ Progress tracking per user

🎯 Complete Workflow

As a New User

Register → Login → See Exams → Start Exam → 
Answer Questions → Submit → View Results → 
Check History → Retake if desired

Navigation

Header Menu:

• "Exam System" - Go home
• "Login" - Login/register (if not logged in)
• "[Username]" - Shows your username
• "My History" - View exam history
• "Logout" - Logout

Routes:

• / - Exam list
• /login - Login/register
• /history - Your exam history
• /exam/:id - Take exam
• /result/:id - View results
• /done/:id - Submission confirmation

🧪 Testing the System

Test Full Flow

# 1. Check system is running
docker-compose ps

# Should show 3 containers: exam_server, exam_web, exam_nginx

# 2. Open browser
open http://localhost

# 3. Register/Login
# Use testuser/test123 or create new account

# 4. Take exam
# Click "Start Exam" on Python Basics

# 5. Check data folders while taking exam
ls -la data/attempts/1/python-basics-v1/

# 6. Submit and check output
ls -la data/output/

# 7. View history
# Click "My History" in header

# 8. Retake
# Click "Take Again" on Python Basics

API Testing

# Login
curl -c cookies.txt -X POST -H "Content-Type: application/json" \
  -d '{"username":"testuser","password":"test123"}' \
  http://localhost/api/auth/login/

# List exams
curl -b cookies.txt http://localhost/api/exams/

# View history
curl -b cookies.txt http://localhost/api/history/me/

📊 Data Structure

Database (Persistent)

• Location: Docker volume exam_system_db_data
• Contains: Users, sessions
• Persists across restarts

File System

data/
├── input/                    # Source exam JSON files
│   └── python-basics-v1.json
├── attempts/{userId}/{examId}/
│   └── {attemptId}.json     # Active attempts
├── output/
│   └── {examId}_{attemptId}.json  # Final bundles
├── progress/
│   └── {userId}.json        # Progress snapshots
└── manifest.json            # Exam registry

User IDs

• Authenticated users: numeric IDs (1, 2, 3...)
• Guest users: guest_ prefix (for backward compatibility)

🔧 Administration

Create Admin User

docker-compose exec exam_server python manage.py createsuperuser

Access admin at: http://localhost/admin

List All Users

docker-compose exec exam_server python manage.py shell
>>> from django.contrib.auth import get_user_model
>>> User = get_user_model()
>>> for u in User.objects.all():
>>>     print(f"{u.id}: {u.username} - {u.email}")

Reset User's Exam

# Via API (when logged in)
curl -b cookies.txt -X POST http://localhost/api/exams/python-basics-v1/reset/

# Or manually delete files
rm -rf data/attempts/1/python-basics-v1/*

🎨 Customization

Add New Exam

1. Create exam JSON in data/input/your-exam.json
2. Follow format in /docs/exam-format.md
3. Update data/manifest.json:

   {
     "exams": [
       ...,
       {
         "examId": "your-exam",
         "path": "input/your-exam.json",
         "published": true,
         "version": "1.0.0"
       }
     ]
   }
   

4. Refresh browser - new exam appears!

Modify Exam Settings

Edit exam JSON in data/input/:

• Change duration
• Add/remove questions
• Adjust difficulty
• Update metadata

Changes take effect immediately (refresh browser).

🐛 Troubleshooting

"Failed to load exams"

Fix:

# Restart backend
docker-compose restart exam_server

# Check logs
docker-compose logs exam_server

# Verify manifest exists
cat data/manifest.json

"Can't login"

Fix:

# Verify user exists
docker-compose exec exam_server python manage.py shell
>>> from django.contrib.auth import get_user_model
>>> User = get_user_model()
>>> User.objects.all()

# Create new user if needed
>>> User.objects.create_user(username='user', email='user@example.com', password='pass123')

"History is empty"

Cause: You haven't submitted any exams yet

Solution: Take and submit an exam first

"Can't retake"

Fix:

1. Go to My History
2. Find the exam
3. Click "Take Again"
4. System resets and redirects to exam

Database issues

Complete reset:

# Stop containers
docker-compose down -v

# This deletes the database volume
# Then start fresh
docker-compose up --build -d

# Run migrations
docker-compose exec exam_server python manage.py migrate

# Create test user
docker-compose exec exam_server python manage.py shell
>>> from django.contrib.auth import get_user_model
>>> User = get_user_model()
>>> User.objects.create_user(username='testuser', email='test@example.com', password='test123')

📈 What's Different from Before

Before (Guest Mode)

• No user accounts
• Session-based with user_default
• Can't track individual users
• Can't distinguish attempts

Now (User System)

• ✅ Individual user accounts
• ✅ Secure authentication
• ✅ Per-user exam history
• ✅ Unlimited retakes
• ✅ View all previous attempts
• ✅ Compare results across attempts

🎯 Use Cases

Student

1. Register account
2. Take assigned exams
3. View results
4. Retake to improve score
5. Track progress over time

Instructor (Future)

• View all student attempts
• Grade essay questions
• Export results
• Analyze performance

Self-Learner

• Create own exams
• Test knowledge repeatedly
• Track improvement
• Review past performance

💾 Backup

Backup User Database

# Export database
docker-compose exec exam_server python manage.py dumpdata > backup_users.json

# Or backup the volume
docker run --rm -v exam_system_db_data:/data -v $(pwd):/backup \
  alpine tar czf /backup/db_backup.tar.gz -C /data .

Backup Exam Data

tar -czf backup_data_$(date +%Y%m%d).tar.gz data/

🔐 Security

• Passwords hashed with Django's PBKDF2
• Session cookies with CSRF protection
• User ownership verification on all endpoints
• Input validation on all forms

📱 Mobile Support

The UI is responsive and works on mobile browsers.

✨ Tips

1. Use incognito window to test multiple users simultaneously
2. Check data folders to see real-time file creation
3. View browser console (F12) to see API calls
4. Check logs if something doesn't work
5. Restart containers if behavior seems odd

🎉 You're All Set!

The system is complete and ready to use:

• ✅ User registration/login
• ✅ Exam taking with autosave
• ✅ Submit functionality working
• ✅ Exam history
• ✅ View results
• ✅ Unlimited retakes
• ✅ All data persisted

Go to http://localhost and start learning! 🚀

---

Need Help? Check:

• SETUP.md - Setup instructions
• TESTING.md - Testing guide
• USER_SYSTEM_GUIDE.md - User system details
• TROUBLESHOOTING.md - Common issues
• /docs/ - Technical specifications