eTMA Handler

Table of Contents

• 1. Overview
  • 1.1. Key Features
• 2. Quick Start
  • 2.1. Prerequisites
  • 2.2. Installation
  • 2.3. Running
• 3. Usage
  • 3.1. Marking Workflow
  • 3.2. CLI Commands
• 4. Architecture
  • 4.1. Technology Stack
  • 4.2. Module Structure
• 5. Configuration
  • 5.1. Environment Variables
• 6. Development
  • 6.1. Building
  • 6.2. Testing
  • 6.3. Documentation
• 7. Deployment
  • 7.1. Binary Distribution
  • 7.2. Container
• 8. Contributing
• 9. License
• 10. Security
• 11. Acknowledgements

1. Overview

eTMA Handler is the BEAM edition of the Open University’s electronic Tutor Marked Assignment (eTMA) marking tool. Originally written in Java, this project migrates the marking workflow to Elixir/Phoenix for improved reliability, cross-platform distribution, and modern web capabilities.

The application processes student assignment submissions in .fhi format, provides a marking interface for tutors, and generates graded .docx files with feedback annotations.

1.1. Key Features

• Phoenix LiveView UI: Real-time, reactive marking interface

• CubDB Storage: Crash-proof, pure-Elixir embedded database

• Burrito Packaging: Single binary distribution for all platforms

• File Watching: Automatic ingestion from Downloads folder

• WASM Plugins: Sandboxed extension support

• Post-Quantum Ready: Kyber key exchange (optional)

• Offline First: Works without network connectivity

2. Quick Start

2.1. Prerequisites

• Elixir 1.14+ with OTP 25+

• Node.js 18+ (for assets)

• Or: Nix with flakes enabled

2.2. Installation

# Using Nix (recommended)
nix develop
mix setup

# Or manually
mix deps.get
mix assets.setup
mix assets.build

2.3. Running

# Development server
mix phx.server

# Or with Just
just dev

# Production release
just release

Then open http://localhost:4000 in your browser.

3. Usage

3.1. Marking Workflow

1. Drop Files: Place .fhi files in your Downloads folder (or configured watch directory)

2. Review: Files appear automatically in the eTMA Handler interface

3. Mark: Use the marking grid to assign grades and feedback

4. Export: Generate graded .docx files for return to students

3.2. CLI Commands

# Process a single file
./etma_handler mark assignment.fhi

# Batch process directory
./etma_handler batch ~/assignments/

# Export grades
./etma_handler export --format csv

4. Architecture

4.1. Technology Stack

Component	Technology
Language	Elixir 1.14+ / OTP 25+
Web Framework	Phoenix 1.7 + LiveView
HTTP Server	Bandit
Database	CubDB (embedded)
Frontend	Tailwind CSS + Alpine.js
Packaging	Burrito (cross-platform binaries)
File Parsing	SweetXml
Security	Argon2id, XChaCha20-Poly1305

4.2. Module Structure

lib/
├── etma_handler/           # Core business logic
│   ├── application.ex      # OTP Application
│   ├── assignments/        # Assignment CRUD
│   ├── marking/            # Marking logic
│   ├── parser/             # .fhi and .docx parsing
│   └── watcher/            # File system watcher
├── etma_handler_web/       # Phoenix web layer
│   ├── controllers/        # HTTP controllers
│   ├── live/               # LiveView modules
│   ├── components/         # UI components
│   └── router.ex           # Routes
└── etma_handler.ex         # Public API

5. Configuration

Configuration is managed through config/:

# config/config.exs
config :etma_handler,
  watch_directory: System.get_env("ETMA_WATCH_DIR", "~/Downloads"),
  storage_path: System.get_env("ETMA_DATA_DIR", "~/.local/share/etma_handler"),
  auto_backup: true

5.1. Environment Variables

Variable	Description	Default
ETMA_WATCH_DIR	Directory to watch for new files	~/Downloads
ETMA_DATA_DIR	Data storage directory	~/.local/share/etma_handler
ETMA_PORT	HTTP server port	4000
ETMA_HOST	HTTP server host	localhost

6. Development

6.1. Building

# Development build
just build

# Release build
just release

# Cross-platform binaries (via Burrito)
just release-all

6.2. Testing

# Run all tests
just test

# With coverage
just test-coverage

# Specific test
mix test test/etma_handler/parser_test.exs

6.3. Documentation

# Generate ExDoc
just docs

# Open in browser
just docs-open

7. Deployment

7.1. Binary Distribution

Burrito creates self-contained binaries:

# Build for current platform
just release

# Build for all platforms
just release-all

# Output in _build/burrito/

7.2. Container

# Build container
podman build -t etma-handler:latest .

# Run
podman run -p 4000:4000 -v ~/assignments:/data etma-handler:latest

8. Contributing

See CONTRIBUTING.adoc for guidelines.

9. License

MIT License - see LICENSE.txt for details.

10. Security

See SECURITY.md for security policies and vulnerability reporting.

11. Acknowledgements

• The Open University for the original Java implementation

• The Elixir and Phoenix communities

• CubDB for the excellent embedded database

• Burrito for cross-platform packaging