# werdani/italy-listening-exam architecture

> Architecture diagram of the GitHub repository werdani/italy-listening-exam, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/werdani/italy-listening-exam
- Repository: https://github.com/werdani/italy-listening-exam

## Overview

AscoltoIT is a browser-based Italian listening exam with a local admin dashboard and additional course, book-library, and podcast features. Learners choose a level, take a timed audio-and-question exam, and receive a scored review; exam progress can resume after refresh. The shared content store supports admin editing and several optional publishing or media integrations. The README documents the product workflow and persistence model; sampled source confirms key exam, content, podcast, and admin responsibilities, but not every runtime connection.

Main entry points: [`js/app.js`](https://github.com/werdani/italy-listening-exam/blob/main/js/app.js) (Exam engine), [`admin/index.html`](https://github.com/werdani/italy-listening-exam/blob/main/admin/index.html) (Admin dashboard), [`js/content.js`](https://github.com/werdani/italy-listening-exam/blob/main/js/content.js) (Shared content), [`index.html`](https://github.com/werdani/italy-listening-exam/blob/main/index.html) (Exam interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learner["Learner experience"]
  node_exam_shell["Exam interface<br/>[index.html]"]
  node_exam_engine["Exam engine<br/>[app.js]"]
  node_exam_results["Score and review<br/>[app.js]"]
end

subgraph group_content["Content management"]
  node_admin_shell["Admin dashboard<br/>[index.html]"]
  node_admin_auth["Admin sign-in<br/>[auth.js]"]
  node_exam_admin["Exam content admin<br/>[admin.js]"]
  node_courses_admin["Course admin<br/>[courses-admin.js]"]
  node_library_admin["Library admin<br/>[library-admin.js]"]
  node_podcast_admin["Podcast admin<br/>[podcast-admin.js]"]
end

subgraph group_extras["Learning extras"]
  node_courses_model["Video courses<br/>[courses.js]"]
  node_courses_view["Course interface<br/>[courses-ui.js]"]
  node_library_model["Book library<br/>[library.js]"]
  node_library_view["Library interface<br/>[library-ui.js]"]
  node_podcast_model["Podcast data<br/>[podcast.js]"]
  node_podcast_view["Podcast player<br/>[podcast-ui.js]"]
end

subgraph group_runtime["Runtime services"]
  node_content_store["Shared content<br/>[content.js]"]
  node_question_data[("Exam content<br/>[questions.json]")]
  node_audio_assets[("Audio clips")]
  node_local_server["Local content server<br/>[server.py]"]
  node_visitor_data[("Visitor records<br/>[visitors.json]")]
end

node_learner_actor(("Learner"))
node_admin_actor(("Administrator"))

node_learner_actor -->|"opens"| node_exam_shell
node_exam_shell -->|"runs"| node_exam_engine
node_exam_engine -->|"loads content"| node_content_store
node_content_store -->|"loads and saves"| node_question_data
node_exam_engine -->|"plays clips"| node_audio_assets
node_exam_engine -->|"scores answers"| node_exam_results
node_exam_results -->|"shows review"| node_learner_actor
node_admin_actor -->|"opens"| node_admin_shell
node_admin_shell -->|"signs in"| node_admin_auth
node_admin_shell -->|"manages questions"| node_exam_admin
node_exam_admin -->|"edits content"| node_content_store
node_admin_shell -.->|"manages courses"| node_courses_admin
node_admin_shell -.->|"manages books"| node_library_admin
node_admin_shell -.->|"manages podcasts"| node_podcast_admin
node_courses_admin -->|"edits courses"| node_courses_model
node_library_admin -->|"edits books"| node_library_model
node_podcast_admin -->|"edits shows"| node_podcast_model
node_exam_engine -->|"sets content"| node_courses_view
node_exam_engine -->|"sets content"| node_library_view
node_podcast_view -.->|"formats episodes"| node_podcast_model
node_admin_actor -->|"runs locally"| node_local_server
node_local_server -->|"saves changes"| node_question_data

click node_exam_shell "https://github.com/werdani/italy-listening-exam/blob/main/index.html"
click node_exam_engine "https://github.com/werdani/italy-listening-exam/blob/main/js/app.js"
click node_content_store "https://github.com/werdani/italy-listening-exam/blob/main/js/content.js"
click node_question_data "https://github.com/werdani/italy-listening-exam/blob/main/data/questions.json"
click node_audio_assets "https://github.com/werdani/italy-listening-exam/tree/main/assets/audio"
click node_exam_results "https://github.com/werdani/italy-listening-exam/blob/main/js/app.js"
click node_admin_shell "https://github.com/werdani/italy-listening-exam/blob/main/admin/index.html"
click node_admin_auth "https://github.com/werdani/italy-listening-exam/blob/main/admin/js/auth.js"
click node_exam_admin "https://github.com/werdani/italy-listening-exam/blob/main/admin/js/admin.js"
click node_courses_admin "https://github.com/werdani/italy-listening-exam/blob/main/admin/js/courses-admin.js"
click node_library_admin "https://github.com/werdani/italy-listening-exam/blob/main/admin/js/library-admin.js"
click node_podcast_admin "https://github.com/werdani/italy-listening-exam/blob/main/admin/js/podcast-admin.js"
click node_courses_model "https://github.com/werdani/italy-listening-exam/blob/main/js/courses.js"
click node_courses_view "https://github.com/werdani/italy-listening-exam/blob/main/js/courses-ui.js"
click node_library_model "https://github.com/werdani/italy-listening-exam/blob/main/js/library.js"
click node_library_view "https://github.com/werdani/italy-listening-exam/blob/main/js/library-ui.js"
click node_podcast_model "https://github.com/werdani/italy-listening-exam/blob/main/js/podcast.js"
click node_podcast_view "https://github.com/werdani/italy-listening-exam/blob/main/js/podcast-ui.js"
click node_local_server "https://github.com/werdani/italy-listening-exam/blob/main/server.py"
click node_visitor_data "https://github.com/werdani/italy-listening-exam/blob/main/data/visitors.json"

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_exam_shell,node_exam_engine,node_exam_results toneBlue
class node_admin_shell,node_admin_auth,node_exam_admin,node_courses_admin,node_library_admin,node_podcast_admin toneAmber
class node_courses_model,node_courses_view,node_library_model,node_library_view,node_podcast_model,node_podcast_view toneMint
class node_content_store,node_question_data,node_audio_assets,node_local_server,node_visitor_data toneRose
class node_learner_actor,node_admin_actor toneIndigo
```

## Components

### Learner experience

- [Exam interface](https://github.com/werdani/italy-listening-exam/blob/main/index.html): `index.html`
- [Exam engine](https://github.com/werdani/italy-listening-exam/blob/main/js/app.js): `js/app.js`
- [Score and review](https://github.com/werdani/italy-listening-exam/blob/main/js/app.js): `js/app.js`

### Content management

- [Admin dashboard](https://github.com/werdani/italy-listening-exam/blob/main/admin/index.html): `admin/index.html`
- [Admin sign-in](https://github.com/werdani/italy-listening-exam/blob/main/admin/js/auth.js): `admin/js/auth.js`
- [Exam content admin](https://github.com/werdani/italy-listening-exam/blob/main/admin/js/admin.js): `admin/js/admin.js`
- [Course admin](https://github.com/werdani/italy-listening-exam/blob/main/admin/js/courses-admin.js): `admin/js/courses-admin.js`
- [Library admin](https://github.com/werdani/italy-listening-exam/blob/main/admin/js/library-admin.js): `admin/js/library-admin.js`
- [Podcast admin](https://github.com/werdani/italy-listening-exam/blob/main/admin/js/podcast-admin.js): `admin/js/podcast-admin.js`

### Learning extras

- [Video courses](https://github.com/werdani/italy-listening-exam/blob/main/js/courses.js): `js/courses.js`
- [Course interface](https://github.com/werdani/italy-listening-exam/blob/main/js/courses-ui.js): `js/courses-ui.js`
- [Book library](https://github.com/werdani/italy-listening-exam/blob/main/js/library.js): `js/library.js`
- [Library interface](https://github.com/werdani/italy-listening-exam/blob/main/js/library-ui.js): `js/library-ui.js`
- [Podcast data](https://github.com/werdani/italy-listening-exam/blob/main/js/podcast.js): `js/podcast.js`
- [Podcast player](https://github.com/werdani/italy-listening-exam/blob/main/js/podcast-ui.js): `js/podcast-ui.js`

### Runtime services

- [Shared content](https://github.com/werdani/italy-listening-exam/blob/main/js/content.js): `js/content.js`
- [Exam content](https://github.com/werdani/italy-listening-exam/blob/main/data/questions.json): `data/questions.json`
- [Audio clips](https://github.com/werdani/italy-listening-exam/tree/main/assets/audio): `assets/audio`
- [Local content server](https://github.com/werdani/italy-listening-exam/blob/main/server.py): `server.py`
- [Visitor records](https://github.com/werdani/italy-listening-exam/blob/main/data/visitors.json): `data/visitors.json`

### Other components

- **Learner**
- **Administrator**

## Connections

- Learner → Exam interface: opens (evidence: `README.md`)
- Exam interface → Exam engine: runs (evidence: `README.md`)
- Exam engine → Shared content: loads content (evidence: `js/app.js`)
- Shared content → Exam content: loads and saves (evidence: `README.md`)
- Exam engine → Audio clips: plays clips (evidence: `README.md`)
- Exam engine → Score and review: scores answers (evidence: `README.md`)
- Score and review → Learner: shows review (evidence: `README.md`)
- Administrator → Admin dashboard: opens (evidence: `README.md`)
- Admin dashboard → Admin sign-in: signs in (evidence: `README.md`)
- Admin dashboard → Exam content admin: manages questions (evidence: `README.md`)
- Exam content admin → Shared content: edits content (evidence: `admin/js/admin.js`)
- Admin dashboard → Course admin: manages courses
- Admin dashboard → Library admin: manages books
- Admin dashboard → Podcast admin: manages podcasts
- Course admin → Video courses: edits courses (evidence: `admin/js/courses-admin.js`)
- Library admin → Book library: edits books (evidence: `admin/js/library-admin.js`)
- Podcast admin → Podcast data: edits shows (evidence: `admin/js/podcast-admin.js`)
- Exam engine → Course interface: sets content (evidence: `js/app.js`)
- Exam engine → Library interface: sets content (evidence: `js/app.js`)
- Podcast player → Podcast data: formats episodes
- Administrator → Local content server: runs locally (evidence: `README.md`)
- Local content server → Exam content: saves changes (evidence: `README.md`)
