eTMA Handler

1. Status

This is an early-stage scaffold, not a working application. A Phoenix shell, the Rust crypto/NLP NIFs, and the marking calculator are real. The data plane (CubDB Repo, FHI parser, file watcher, .docx generator) is unimplemented. Marking-analytics modules are docstring stubs. See TOPOLOGY.md for an honest component-by-component status, and ROADMAP.adoc for the path to v1.

2. Overview

eTMA Handler is intended to be a BEAM-edition replacement for the Open University’s electronic Tutor Marked Assignment (eTMA) marking tool, originally written in Java. The goal is to migrate the marking workflow to Elixir/Phoenix for improved reliability, cross-platform distribution, and modern web capabilities.

When complete, the application will process student assignment submissions in .fhi format, provide a marking interface for tutors, and generate graded .docx files with feedback annotations. None of that end-to-end flow works today; see Status above.

2.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

3. Quick Start

3.1. Prerequisites

• Elixir 1.17+ with OTP 26+ (via asdf; see .tool-versions)

• Rust + Cargo (for the native NIFs)

• Node.js 18+ (for assets)

• Or: Guix with guix.scm

3.2. Installation

# Using asdf (recommended)
asdf install
mix deps.get
mix assets.setup
mix assets.build

# Or using Guix
guix shell -m guix.scm
mix deps.get

3.3. Running

# Development server
mix phx.server

# Or with Just
just dev

# Production release
just release

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

4. Usage

4.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

4.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

5. Architecture

5.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

5.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

6. 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

6.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

7. Development

7.1. Building

# Development build
just build

# Release build
just release

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

7.2. Testing

# Run all tests
just test

# With coverage
just test-coverage

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

7.3. Documentation

# Generate ExDoc
just docs

# Open in browser
just docs-open

8. Deployment

8.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/

8.2. Container

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

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

9. Contributing

See CONTRIBUTING.adoc for guidelines.

10. License

Palimpsest-MPL-1.0 License - see LICENSE.txt for details.

11. Security

See SECURITY.md for security policies and vulnerability reporting.

12. 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

13. Architecture

See TOPOLOGY.md for a visual architecture map and completion dashboard.