lnet_tutor/exam_system/SETUP.md

Exam System - Complete Setup Guide

✅ System Overview

A complete exam system with:

• exam_server: Django REST API backend
• exam_web: Angular SPA frontend
• nginx: Reverse proxy
• data: File-based storage for exams, attempts, and results

📁 Project Structure

exam_system/
├── exam_server/              # Django backend
│   ├── manage.py
│   ├── exam_server/          # Django project
│   │   ├── settings.py
│   │   ├── urls.py
│   │   └── wsgi.py
│   ├── api/                  # API app
│   │   ├── views.py
│   │   ├── urls.py
│   │   └── storage.py
│   ├── Dockerfile
│   └── requirements.txt
│
├── exam_web/                 # Angular frontend
│   ├── src/
│   │   ├── app/
│   │   │   ├── components/
│   │   │   │   ├── exam-list/
│   │   │   │   ├── exam-player/
│   │   │   │   └── exam-done/
│   │   │   ├── services/
│   │   │   │   └── api.service.ts
│   │   │   ├── app.module.ts
│   │   │   └── app-routing.module.ts
│   │   ├── index.html
│   │   └── main.ts
│   ├── angular.json
│   ├── package.json
│   └── Dockerfile
│
├── data/                     # File-based storage
│   ├── input/                # Exam JSON files
│   │   └── python-basics-v1.json
│   ├── attempts/             # Active attempts
│   ├── output/               # Final bundles
│   ├── progress/             # Progress snapshots
│   └── manifest.json         # Exam registry
│
├── nginx.conf                # Nginx config
├── Dockerfile.nginx          # Nginx Dockerfile
├── docker-compose.yml        # Docker orchestration
└── README.md

🚀 Quick Start

1. Start the System

cd exam_system
docker-compose up --build

This starts three services:

• exam_server: Django API on port 8000 (internal)
• exam_web: Angular app on port 4200 (internal)
• nginx: Reverse proxy on port 80 (external)

2. Access the Application

Open your browser to: http://localhost

You should see the exam list with "Python Basics Exam" available.

3. Test the Flow

1. Click "Start Exam" on the Python Basics exam
2. Answer the questions (multiple choice, true/false, essay, code)
3. The system autosaves every 10 seconds
4. Submit when done
5. Check data/output/ for the bundled result JSON

🔧 Development

Backend (Django)

# Shell access
docker-compose exec exam_server bash

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

# Create superuser for admin
docker-compose exec exam_server python manage.py createsuperuser

# Access admin
http://localhost/admin

Frontend (Angular)

# Shell access
docker-compose exec exam_web sh

# Install new packages
docker-compose exec exam_web npm install <package>

# View logs
docker-compose logs -f exam_web

Add a New Exam

1. Create exam JSON in data/input/your-exam.json following the format in docs/exam-format.md

2. Update data/manifest.json:

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

3. Refresh the browser - the new exam will appear

📊 Data Flow

1. Exam Load: Angular calls /api/exams/ → Django reads data/input/ and manifest.json
2. Start Exam: POST /api/exams/{id}/attempt/ → Creates attempt in data/attempts/{userId}/{examId}/
3. Autosave: PUT /api/attempts/{id}/autosave/ → Updates attempt JSON every 10 seconds
4. Submit: POST /api/attempts/{id}/submit/ → Creates bundle in data/output/{examId}_{attemptId}.json

🧪 Testing

Test with Sample Exam

The system comes with a sample Python exam. To test:

1. Start the system: docker-compose up
2. Go to http://localhost
3. Click "Start Exam" on "Python Basics Exam"
4. Answer a few questions
5. Wait for autosave (watch for "Saved" status)
6. Submit the exam
7. Check data/attempts/ and data/output/ for saved files

Verify API Endpoints

# List exams
curl http://localhost/api/exams/

# Health check
curl http://localhost/api/health/

🐛 Troubleshooting

Port 80 Already in Use

Edit docker-compose.yml:

nginx:
  ports:
    - "8080:80"  # Change from 80:80

Then access via http://localhost:8080

Container Won't Start

# Check logs
docker-compose logs exam_server
docker-compose logs exam_web
docker-compose logs nginx

# Rebuild from scratch
docker-compose down -v
docker-compose up --build

Permission Errors on Data Folder

chmod -R 755 data/

Angular Build Issues

# Clear node_modules and rebuild
docker-compose down
rm -rf exam_web/node_modules
docker-compose up --build

📝 Question Types Supported

1. single_choice: Multiple choice with one correct answer
2. true_false: Boolean questions
3. essay: Open-ended text responses
4. code_simple: Simple coding problems
5. code_exercise: Complex coding exercises with test cases

See docs/exam-format.md for complete format specification.

🔐 Security Notes

• This is a development setup. For production:
  • Change SECRET_KEY in exam_server/env.example
  • Set DEBUG=False
  • Use HTTPS with proper SSL certificates
  • Add authentication/authorization
  • Secure file permissions on data folder

📚 Documentation

• docs/exam-format.md - Exam JSON format specification
• docs/stack-architecture.md - System architecture
• docs/django-backend-spec.md - Backend API details
• docs/angular-frontend-spec.md - Frontend behavior
• docs/json-io-and-state.md - State machine and file structure

🎯 Next Steps

1. Create your own exam JSON files
2. Customize the Angular UI styling
3. Add grading/scoring logic
4. Implement user authentication
5. Deploy to production

💡 Tips

• Use the sample exam as a template for creating new exams
• The system autosaves every 10 seconds, so progress is never lost
• Check data/output/ for submitted exam bundles
• All data is stored as JSON files for easy inspection and backup