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

```bash
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)

```bash
# 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)

```bash
# 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`:

```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

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

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

## 🐛 Troubleshooting

### Port 80 Already in Use

Edit `docker-compose.yml`:
```yaml
nginx:
  ports:
    - "8080:80"  # Change from 80:80
```

Then access via http://localhost:8080

### Container Won't Start

```bash
# 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

```bash
chmod -R 755 data/
```

### Angular Build Issues

```bash
# 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