---
title: Lesson Evaluation
order: 4
category: evaluation
---
# 04. Lesson Evaluation

The LMS determines the type of lesson and how to evaluate it based on specific markers found in the Markdown content.

## Markdown Markers

| Mode | Marker | Evaluation Logic |
|------|--------|------------------|
| **C / Python** | `---INITIAL_CODE---` / `---INITIAL_PYTHON---` | Standard stdout matching against `---EXPECTED_OUTPUT---` and presence of `---KEY_TEXT---`. |
| **Circuit** | `---INITIAL_CIRCUIT---` | Node voltage matching against `---EXPECTED_CIRCUIT_OUTPUT---` and `---KEY_TEXT_CIRCUIT---`. |
| **Arduino (Velxio)** | `---INITIAL_CODE_ARDUINO---` | Serial output sequence matching, lenient graph wiring comparison, and `---KEY_TEXT---`. |
| **Quiz** | `---QUIZ_MCQ---` / `---QUIZ_WEIGHTED---` / `---FLASHCARD---` | Skor resmi = rata-rata persentase per jenis quiz (weighted pakai poin bobot); lulus bila ≥ 75. |
| **Slide** | `---slide-start---` | Tidak ada (hanya presentasi konten). |

## Evaluators (`lib/services/`)

The evaluation logic is isolated into specific service files:

### General & C/Python (`evaluators.ts`, `exercise.ts`)
- `export function checkKeyText(code: string, keyText: string): boolean`
  Checks if all lines in the `keyText` are present in the provided `code`.
- `export function processLanguageEvaluation(...)`
  Coordinates the compilation request and output verification for C and Python.

### Circuit Evaluation (`evaluators.ts`, `exercise.ts`)
- `export function evaluateCircuitSubmission(...)`
  Handles the flow of extracting the circuit state.
- `export function validateNodes(actualVoltages: Record<string, number>, expectedNodes: Record<string, NodeResult>): boolean`
  Validates if the actual node voltages match the expected voltages within a specified tolerance.

### Arduino/Velxio Evaluation (`velxio-evaluator.ts`, `velxio-bridge.ts`)
- `class VelxioBridge` (`velxio-bridge.ts`)
  Manages the `window.postMessage` protocol between the LMS and the Velxio iframe.
  - Commands: `elemes:load_code`, `elemes:load_circuit`, `elemes:get_source_code`, `elemes:get_serial_log`, `elemes:get_wires`.
  - Events: `velxio:ready`, `velxio:compile_result`.
- `export function evaluateVelxioSubmission(...)`
  Orchestrates the 3-part Arduino evaluation:
  1. **Key Text**: Checks the retrieved source code.
  2. **Serial Output**: Uses `matchSerialSubsequence(actual, expected)` to ensure expected log lines appear in the correct order.
  3. **Wiring**: Performs a lenient graph comparison (expected edges must exist; extra edges are allowed; ground pins are normalized).

### Flowchart Evaluation (`flowchart-evaluator.ts`)
- `export function evaluateFlowchartSubmission(...)`
  Parses flowchart JSON data and verifies structural correctness against the expected model.

## Sinkronisasi Evaluasi → Progress (tanpa restart)

Jenis evaluasi lesson ditentukan oleh marker di file `.md` (lihat tabel di atas).
Saat guru mem-publish perubahan di `/teacher/content`:

1. `POST /content/drafts/<id>/publish` membandingkan **signature evaluasi**
   sebelum vs sesudah (`has_exercise`, `has_quiz`, jenis kuis, jumlah soal).
2. **Registry lesson** (`lessons`) langsung disinkronkan dari `home.md` +
   `sub-home.md` — lesson baru/hapus/rename tidak perlu restart.
3. Bila signature berubah, `repositories.recompute_lesson_progress()`
   menghitung ulang `composite_percent` + `state` **semua siswa** untuk lesson
   itu memakai komponen baru ("recompute jujur"):
   - Menambah quiz ke lesson exercise-only → siswa `done` turun ke
     `in_progress` sampai quiz dikerjakan.
   - Skor historis (`quiz_score_earned/total`, attempt kuis) **tidak dihapus**;
     guru tetap bisa reset per siswa lewat halaman progress.
4. Respons publish memuat `evaluation_changed` + `progress_recomputed`, yang
   ditampilkan sebagai notifikasi di editor.

Perubahan konten di luar webapp (git pull/edit manual) ditangani oleh tombol
**Sinkronisasi** di `/teacher/progress` (`POST /content/sync-registry`) dan
safety-net saat startup (`recompute_all_lessons`). Tidak ada lagi kebutuhan
restart server agar progress guru konsisten.