# jctonini/metsi architecture

> Architecture diagram of the GitHub repository jctonini/metsi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jctonini/metsi
- Repository: https://github.com/jctonini/metsi

## Overview

METSI is a browser-based multiple-choice exam corrector. A teacher configures an exam and its answer sheet, loads photos, reviews the app’s suggested readings and scores, then exports results; Drive sync and account administration are supporting branches. The README documents the user workflow, while sampled source and the SOURCE INDEX confirm several module dependencies. Some frontend wiring was not shown, so uncertain internal calls are omitted.

Main entry points: [`js/app-scan.js`](https://github.com/jctonini/metsi/blob/main/js/app-scan.js) (Photo intake), [`js/app-exam.js`](https://github.com/jctonini/metsi/blob/main/js/app-exam.js) (Exam setup), [`js/app-drive.js`](https://github.com/jctonini/metsi/blob/main/js/app-drive.js) (Drive controls), [`js/drive.js`](https://github.com/jctonini/metsi/blob/main/js/drive.js) (Drive client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_exam["Exam and sheet"]
  node_app["Browser app<br/>[app.js]"]
  node_exam_config["Exam setup<br/>[app-exam.js]"]
  node_exam_file["Exam JSON<br/>[examfile.js]"]
  node_sheet["Answer sheet<br/>[sheet.js]"]
  node_layout["Sheet geometry<br/>[layout.js]"]
end

subgraph group_correction["Photo correction"]
  node_photo_intake["Photo intake<br/>[app-scan.js]"]
  node_scanner["Bubble scanner<br/>[scanner.js]"]
  node_digit_reader["Record reader<br/>[digits.js]"]
  node_digit_model["Digit model<br/>[digit-model.js]"]
  node_identity["Identity checks<br/>[identity.js]"]
  node_similar["Duplicate detection<br/>[similar.js]"]
end

subgraph group_results["Review and results"]
  node_scoring["Score calculation<br/>[scoring.js]"]
  node_review["Review flags<br/>[review.js]"]
  node_results_ui["Results table<br/>[app-results.js]"]
  node_csv["CSV export<br/>[csv.js]"]
  node_storage[("Local storage<br/>[storage.js]")]
end

subgraph group_drive["Drive sync"]
  node_drive_ui["Drive controls<br/>[app-drive.js]"]
  node_picker["Drive picker<br/>[picker.js]"]
  node_drive_client["Drive client<br/>[drive.js]"]
  node_retry["Retry policy<br/>[retry.js]"]
end

subgraph group_access["Access and accounts"]
  node_login["Login page<br/>[login.js]"]
  node_auth_ui["Browser auth<br/>[auth.js]"]
  node_static_gate["App access gate<br/>[app.js]"]
  node_token_auth["Token validation<br/>[auth.js]"]
  node_user_admin["User administration<br/>[users.js]"]
end

node_teacher(("Teacher"))
node_supabase[("Supabase")]
node_google_drive[("Google Drive")]

node_teacher -->|"uses"| node_app
node_app -->|"opens"| node_exam_config
node_exam_config -->|"imports/exports"| node_exam_file
node_exam_config -->|"configures"| node_sheet
node_sheet -->|"uses geometry"| node_layout
node_teacher -->|"loads photos"| node_photo_intake
node_photo_intake -->|"reads bubbles"| node_scanner
node_photo_intake -->|"suggests record"| node_digit_reader
node_digit_reader -->|"classifies digits"| node_digit_model
node_photo_intake -->|"collects identity"| node_identity
node_photo_intake -->|"checks duplicates"| node_similar
node_photo_intake -->|"calculates score"| node_scoring
node_teacher -->|"reviews flags"| node_review
node_teacher -->|"views results"| node_results_ui
node_results_ui -->|"exports results"| node_csv
node_photo_intake -->|"saves locally"| node_storage
node_teacher -->|"syncs results"| node_drive_ui
node_drive_ui -->|"selects photos"| node_picker
node_drive_ui -->|"syncs files"| node_drive_client
node_drive_client -->|"retries requests"| node_retry
node_drive_client -->|"reads/writes"| node_google_drive
node_login -->|"authenticates"| node_supabase
node_auth_ui -->|"authenticates"| node_supabase
node_static_gate -->|"validates session"| node_token_auth
node_user_admin -->|"validates session"| node_token_auth
node_user_admin -->|"manages users"| node_supabase

click node_app "https://github.com/jctonini/metsi/blob/main/js/app.js"
click node_exam_config "https://github.com/jctonini/metsi/blob/main/js/app-exam.js"
click node_exam_file "https://github.com/jctonini/metsi/blob/main/js/examfile.js"
click node_sheet "https://github.com/jctonini/metsi/blob/main/js/sheet.js"
click node_layout "https://github.com/jctonini/metsi/blob/main/js/layout.js"
click node_photo_intake "https://github.com/jctonini/metsi/blob/main/js/app-scan.js"
click node_scanner "https://github.com/jctonini/metsi/blob/main/js/scanner.js"
click node_digit_reader "https://github.com/jctonini/metsi/blob/main/js/digits.js"
click node_digit_model "https://github.com/jctonini/metsi/blob/main/js/digit-model.js"
click node_identity "https://github.com/jctonini/metsi/blob/main/js/identity.js"
click node_similar "https://github.com/jctonini/metsi/blob/main/js/similar.js"
click node_scoring "https://github.com/jctonini/metsi/blob/main/js/scoring.js"
click node_review "https://github.com/jctonini/metsi/blob/main/js/review.js"
click node_results_ui "https://github.com/jctonini/metsi/blob/main/js/app-results.js"
click node_csv "https://github.com/jctonini/metsi/blob/main/js/csv.js"
click node_storage "https://github.com/jctonini/metsi/blob/main/js/storage.js"
click node_drive_ui "https://github.com/jctonini/metsi/blob/main/js/app-drive.js"
click node_picker "https://github.com/jctonini/metsi/blob/main/js/picker.js"
click node_drive_client "https://github.com/jctonini/metsi/blob/main/js/drive.js"
click node_retry "https://github.com/jctonini/metsi/blob/main/js/retry.js"
click node_login "https://github.com/jctonini/metsi/blob/main/public/login.js"
click node_auth_ui "https://github.com/jctonini/metsi/blob/main/js/auth.js"
click node_static_gate "https://github.com/jctonini/metsi/blob/main/api/app.js"
click node_token_auth "https://github.com/jctonini/metsi/blob/main/server/auth.js"
click node_user_admin "https://github.com/jctonini/metsi/blob/main/api/users.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_exam_config,node_exam_file,node_sheet,node_layout toneBlue
class node_photo_intake,node_scanner,node_digit_reader,node_digit_model,node_identity,node_similar,node_supabase,node_google_drive toneAmber
class node_scoring,node_review,node_results_ui,node_csv,node_storage toneMint
class node_drive_ui,node_picker,node_drive_client,node_retry toneRose
class node_login,node_auth_ui,node_static_gate,node_token_auth,node_user_admin,node_teacher toneIndigo
```

## Components

### Exam and sheet

- [Browser app](https://github.com/jctonini/metsi/blob/main/js/app.js): `js/app.js`
- [Exam setup](https://github.com/jctonini/metsi/blob/main/js/app-exam.js): `js/app-exam.js`
- [Exam JSON](https://github.com/jctonini/metsi/blob/main/js/examfile.js): `js/examfile.js`
- [Answer sheet](https://github.com/jctonini/metsi/blob/main/js/sheet.js): `js/sheet.js`
- [Sheet geometry](https://github.com/jctonini/metsi/blob/main/js/layout.js): `js/layout.js`

### Photo correction

- [Photo intake](https://github.com/jctonini/metsi/blob/main/js/app-scan.js): `js/app-scan.js`
- [Bubble scanner](https://github.com/jctonini/metsi/blob/main/js/scanner.js): `js/scanner.js`
- [Record reader](https://github.com/jctonini/metsi/blob/main/js/digits.js): `js/digits.js`
- [Digit model](https://github.com/jctonini/metsi/blob/main/js/digit-model.js): `js/digit-model.js`
- [Identity checks](https://github.com/jctonini/metsi/blob/main/js/identity.js): `js/identity.js`
- [Duplicate detection](https://github.com/jctonini/metsi/blob/main/js/similar.js): `js/similar.js`

### Review and results

- [Score calculation](https://github.com/jctonini/metsi/blob/main/js/scoring.js): `js/scoring.js`
- [Review flags](https://github.com/jctonini/metsi/blob/main/js/review.js): `js/review.js`
- [Results table](https://github.com/jctonini/metsi/blob/main/js/app-results.js): `js/app-results.js`
- [CSV export](https://github.com/jctonini/metsi/blob/main/js/csv.js): `js/csv.js`
- [Local storage](https://github.com/jctonini/metsi/blob/main/js/storage.js): `js/storage.js`

### Drive sync

- [Drive controls](https://github.com/jctonini/metsi/blob/main/js/app-drive.js): `js/app-drive.js`
- [Drive picker](https://github.com/jctonini/metsi/blob/main/js/picker.js): `js/picker.js`
- [Drive client](https://github.com/jctonini/metsi/blob/main/js/drive.js): `js/drive.js`
- [Retry policy](https://github.com/jctonini/metsi/blob/main/js/retry.js): `js/retry.js`

### Access and accounts

- [Login page](https://github.com/jctonini/metsi/blob/main/public/login.js): `public/login.js`
- [Browser auth](https://github.com/jctonini/metsi/blob/main/js/auth.js): `js/auth.js`
- [App access gate](https://github.com/jctonini/metsi/blob/main/api/app.js): `api/app.js`
- [Token validation](https://github.com/jctonini/metsi/blob/main/server/auth.js): `server/auth.js`
- [User administration](https://github.com/jctonini/metsi/blob/main/api/users.js): `api/users.js`

### Other components

- **Teacher**
- **Supabase**
- **Google Drive**

## Connections

- Teacher → Browser app: uses (evidence: `README.md`)
- Browser app → Exam setup: opens (evidence: `README.md`)
- Exam setup → Exam JSON: imports/exports (evidence: `README.md`)
- Exam setup → Answer sheet: configures (evidence: `README.md`)
- Answer sheet → Sheet geometry: uses geometry (evidence: `js/layout.js`)
- Teacher → Photo intake: loads photos (evidence: `README.md`)
- Photo intake → Bubble scanner: reads bubbles (evidence: `README.md`)
- Photo intake → Record reader: suggests record (evidence: `README.md`)
- Record reader → Digit model: classifies digits (evidence: `js/digits.js`)
- Photo intake → Identity checks: collects identity (evidence: `README.md`)
- Photo intake → Duplicate detection: checks duplicates (evidence: `README.md`)
- Photo intake → Score calculation: calculates score (evidence: `README.md`)
- Teacher → Review flags: reviews flags (evidence: `README.md`)
- Teacher → Results table: views results (evidence: `README.md`)
- Results table → CSV export: exports results (evidence: `README.md`)
- Photo intake → Local storage: saves locally (evidence: `README.md`)
- Teacher → Drive controls: syncs results (evidence: `README.md`)
- Drive controls → Drive picker: selects photos (evidence: `README.md`)
- Drive controls → Drive client: syncs files (evidence: `README.md`)
- Drive client → Retry policy: retries requests (evidence: `js/drive.js`)
- Drive client → Google Drive: reads/writes (evidence: `js/drive.js`)
- Login page → Supabase: authenticates (evidence: `README.md`)
- Browser auth → Supabase: authenticates (evidence: `README.md`)
- App access gate → Token validation: validates session (evidence: `api/app.js`)
- User administration → Token validation: validates session (evidence: `api/users.js`)
- User administration → Supabase: manages users (evidence: `api/users.js`)
