# lapl56/moodle-attendance_tool architecture

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

- Interactive diagram: https://gitdiagram.com/lapl56/moodle-attendance_tool
- Repository: https://github.com/lapl56/moodle-attendance_tool

## Overview

This repository is a **Moodle local plugin** named `local_attendance`. It is not a standalone app; it extends Moodle with attendance scheduling, daily check-in, reporting, and student schedule views, all backed by Moodle’s plugin/runtime model and the site database.

1. **Overall shape**
   - The plugin is centered around **attendance data organized by semester, period, schedule, session, and attendance record**.
   - The architecture is mostly **server-rendered PHP + AJAX-driven UI**, with a thin client-side layer in JavaScript for interactive editors and dashboards.

2. **Primary user-facing entry points**
   - `index.php` is the plugin landing page.
   - `myschedule.php` provides the **student schedule** read-only view.
   - `report.php` provides the **report/export** interface.
   - These pages likely render Moodle pages and load the appropriate JS modules for interaction.

3. **Client-side interaction layer**
   - `amd/src/myschedule.js` and `amd/src/attendance.js` are the main interactive modules; `amd/build/*.js` are the compiled artifacts used at runtime.
   - These scripts handle dynamic UI behavior such as schedule editing, day/session selection, attendance marking, dashboard filtering, and asynchronous calls to backend endpoints.
   - The JS layer is the main boundary between the browser and the plugin’s server-side data services.

4. **Service/API layer**
   - `classes/external/*` contains a large set of Moodle external/AJAX callable classes.
   - These functions expose the plugin’s main operations:
     - schedule CRUD: save/get/delete schedule, slot, period, semester
     - attendance operations: save attendance, backfill attendance, session attendance, today sessions, history sessions
     - dashboards and reports: KPIs, top 5, filters, course roster, search users
     - utility lookups: accessible courses, groups, semesters, schedule courses, substitute teachers, extra sessions
   - This is the main read/write API boundary used by the frontend.

5. **Core domain model**
   - The feature set implies a domain built around:
     - **semesters and periods** to define the academic calendar
     - **schedules and slots** to define weekly structure
     - **sessions** as actual dated occurrences of scheduled items
     - **attendance rows** for present/absent/late per session
     - **extra sessions** for ad hoc or extraordinary activities
   - The data model is organized to support both **planned weekly schedules** and **historical session records**.

6. **Persistence and schema management**
   - `db/install.xml` defines the plugin’s database tables.
   - `db/upgrade.php` handles schema/data migrations across versions.
   - `db/access.php` defines Moodle capabilities for controlling access.
   - `db/services.php` registers external services/endpoints, and `db/hooks.php` integrates the plugin into Moodle’s event/hook system.

7. **Server-side business logic**
   - `lib.php` and `classes/helper.php` likely contain shared business rules, permission checks, date/semester logic, and data assembly used by both pages and external services.
   - The plugin appears to centralize logic here rather than duplicating it in UI code, which is important because the same rules drive scheduling, attendance capture, retroactive edits, and reporting.

8. **UI integration with Moodle**
   - `settings.php` exposes plugin configuration in Moodle admin, including the **access code** mentioned in the README for entering the editor.
   - `classes/hook/extend_user_menu.php` adds a link into the Moodle user menu, making the plugin discoverable from the standard UI.
   - `styles.css` provides the plugin’s visual layer, likely shared across pages.

9. **Functional subsystems**
   - **Schedule editor:** create and maintain weekly schedules by group or subject, including sessions, recesses, and extra activities.
   - **Daily attendance:** show the day’s active sessions and record attendance per session.
   - **Historical editor:** navigate past weeks within semester limits and generate records retroactively.
   - **Academic calendar:** define semesters/periods per campus/site and constrain history navigation.
   - **Dashboard/reporting:** aggregate KPIs and filtered exports across students, teachers, groups, and date ranges.
   - **Student schedule:** read-only weekly timetable derived from active enrollments.

10. **Data flow pattern**
   - Users interact with a Moodle page (`index.php`, `myschedule.php`, or `report.php`).
   - The page loads AMD JavaScript for interactivity.
   - JS calls `classes/external/*` endpoints via Moodle’s AJAX/external function mechanism.
   - Backend methods use helper logic and Moodle permissions to read/write DB tables defined in `install.xml`.
   - Results are returned to the browser for rendering tables, calendars, dashboards, and confirmation states.

11. **Security and access control**
   - Access is gated by Moodle capabilities (`db/access.php`) and plugin configuration (`settings.php`), plus the access-code workflow noted in the README.
   - This indicates the plugin is designed for controlled administrative use, not open self-service access.
   - Many endpoints likely perform contextual checks against user roles, accessible courses, and the selected campus/semester.

12. **What matters for an architecture diagram**
   - Draw Moodle as the host platform, with `local_attendance` as a local plugin inside it.
   - Split the plugin into:
     - **UI pages** (`index.php`, `myschedule.php`, `report.php`)
     - **client-side modules** (`amd/src/*.js`)
     - **external service layer** (`classes/external/*`)
     - **shared backend logic** (`lib.php`, `classes/helper.php`)
     - **database schema/config** (`db/*`)
   - Show the data backbone as semester/period/schedule/session/attendance tables feeding attendance capture, history editing, dashboards, and reports.

Main entry points: [`amd/src/attendance.js`](https://github.com/lapl56/moodle-attendance_tool/blob/main/amd/src/attendance.js) (Attendance JS), [`db/services.php`](https://github.com/lapl56/moodle-attendance_tool/blob/main/db/services.php) (Services), [`index.php`](https://github.com/lapl56/moodle-attendance_tool/blob/main/index.php) (Home), [`amd/src/myschedule.js`](https://github.com/lapl56/moodle-attendance_tool/blob/main/amd/src/myschedule.js) (Schedule JS)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_moodle["Moodle host"]
  node_moodle_core["Moodle<br/>host platform"]
end

subgraph group_ui["UI pages"]
  node_index_page["Home<br/>page<br/>[index.php]"]
  node_myschedule_page["My schedule<br/>page<br/>[myschedule.php]"]
  node_report_page["Report<br/>page<br/>[report.php]"]
end

subgraph group_client["Client scripts"]
  node_attendance_js{{"Attendance JS<br/>browser module<br/>[attendance.js]"}}
  node_myschedule_js{{"Schedule JS<br/>browser module<br/>[myschedule.js]"}}
end

subgraph group_api["External services"]
  node_attendance_api["Attendance API<br/>external services"]
  node_schedule_api["Schedule API<br/>external services<br/>[save_schedule.php]"]
  node_report_api["Report API<br/>external services"]
  node_lookup_api["Lookup API<br/>external services<br/>[get_semesters.php]"]
end

subgraph group_backend["Shared backend"]
  node_plugin_lib["Lib<br/>shared logic<br/>[lib.php]"]
  node_helper_cls["Helper<br/>shared logic<br/>[helper.php]"]
end

subgraph group_schema["Database and config"]
  node_db_schema[("Schema<br/>[install.xml]")]
  node_db_access["Capabilities<br/>access config<br/>[access.php]"]
  node_db_services["Services<br/>service config<br/>[services.php]"]
  node_db_hooks["Hooks<br/>integration config<br/>[hooks.php]"]
  node_settings_page["Settings<br/>admin config<br/>[settings.php]"]
  node_extend_menu["User menu<br/>hook"]
end

node_moodle_core -->|"hosts"| node_index_page
node_moodle_core -->|"hosts"| node_myschedule_page
node_moodle_core -->|"hosts"| node_report_page
node_index_page -->|"loads"| node_attendance_js
node_index_page -.->|"loads"| node_myschedule_js
node_myschedule_page -->|"loads"| node_myschedule_js
node_report_page -.->|"loads"| node_attendance_js
node_attendance_js -->|"calls"| node_attendance_api
node_attendance_js -->|"calls"| node_schedule_api
node_attendance_js -->|"calls"| node_report_api
node_myschedule_js -->|"calls"| node_lookup_api
node_attendance_api -->|"uses"| node_plugin_lib
node_schedule_api -->|"uses"| node_plugin_lib
node_report_api -->|"uses"| node_helper_cls
node_lookup_api -->|"uses"| node_helper_cls
node_plugin_lib -->|"reads/writes"| node_db_schema
node_helper_cls -->|"reads"| node_db_schema
node_db_services -->|"registers"| node_attendance_api
node_db_services -->|"registers"| node_schedule_api
node_db_services -->|"registers"| node_report_api
node_db_services -->|"registers"| node_lookup_api
node_db_access -->|"gates"| node_moodle_core
node_settings_page -->|"configures"| node_moodle_core
node_db_hooks -->|"contains"| node_extend_menu
node_extend_menu -->|"integrates"| node_moodle_core
node_db_hooks -->|"integrates"| node_moodle_core

click node_index_page "https://github.com/lapl56/moodle-attendance_tool/blob/main/index.php"
click node_myschedule_page "https://github.com/lapl56/moodle-attendance_tool/blob/main/myschedule.php"
click node_report_page "https://github.com/lapl56/moodle-attendance_tool/blob/main/report.php"
click node_attendance_js "https://github.com/lapl56/moodle-attendance_tool/blob/main/amd/src/attendance.js"
click node_myschedule_js "https://github.com/lapl56/moodle-attendance_tool/blob/main/amd/src/myschedule.js"
click node_attendance_api "https://github.com/lapl56/moodle-attendance_tool/blob/main/classes/external/save_attendance.php"
click node_schedule_api "https://github.com/lapl56/moodle-attendance_tool/blob/main/classes/external/save_schedule.php"
click node_report_api "https://github.com/lapl56/moodle-attendance_tool/blob/main/classes/external/get_dashboard_kpis.php"
click node_lookup_api "https://github.com/lapl56/moodle-attendance_tool/blob/main/classes/external/get_semesters.php"
click node_plugin_lib "https://github.com/lapl56/moodle-attendance_tool/blob/main/lib.php"
click node_helper_cls "https://github.com/lapl56/moodle-attendance_tool/blob/main/classes/helper.php"
click node_db_schema "https://github.com/lapl56/moodle-attendance_tool/blob/main/db/install.xml"
click node_db_access "https://github.com/lapl56/moodle-attendance_tool/blob/main/db/access.php"
click node_db_services "https://github.com/lapl56/moodle-attendance_tool/blob/main/db/services.php"
click node_db_hooks "https://github.com/lapl56/moodle-attendance_tool/blob/main/db/hooks.php"
click node_settings_page "https://github.com/lapl56/moodle-attendance_tool/blob/main/settings.php"
click node_extend_menu "https://github.com/lapl56/moodle-attendance_tool/blob/main/classes/hook/extend_user_menu.php"

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_moodle_core toneBlue
class node_index_page,node_myschedule_page,node_report_page toneAmber
class node_attendance_js,node_myschedule_js toneMint
class node_attendance_api,node_schedule_api,node_report_api,node_lookup_api toneRose
class node_plugin_lib,node_helper_cls toneIndigo
class node_db_schema,node_db_access,node_db_services,node_db_hooks,node_settings_page,node_extend_menu toneTeal
```

## Components

### Moodle host

The plugin runs inside Moodle and uses its page, AJAX, capability, and hook model.

- **Moodle**: host platform · The Moodle runtime that hosts the local plugin.

### UI pages

Server-rendered entry points for the plugin's main workflows.

- [Home](https://github.com/lapl56/moodle-attendance_tool/blob/main/index.php): page · Plugin landing page. · `index.php`
- [My schedule](https://github.com/lapl56/moodle-attendance_tool/blob/main/myschedule.php): page · Student read-only timetable view. · `myschedule.php`
- [Report](https://github.com/lapl56/moodle-attendance_tool/blob/main/report.php): page · Reporting and export interface. · `report.php`

### Client scripts

Thin browser-side interaction layer for editing, filtering, and AJAX calls.

- [Attendance JS](https://github.com/lapl56/moodle-attendance_tool/blob/main/amd/src/attendance.js): browser module · Primary interactive module for attendance and dashboard behavior. · `amd/src/attendance.js`
- [Schedule JS](https://github.com/lapl56/moodle-attendance_tool/blob/main/amd/src/myschedule.js): browser module · Interactive module for the student schedule view. · `amd/src/myschedule.js`

### External services

Moodle external/AJAX-callable endpoints exposing the plugin's read/write operations.

- [Attendance API](https://github.com/lapl56/moodle-attendance_tool/blob/main/classes/external/save_attendance.php): external services · Attendance capture, backfill, and session-attendance endpoints. · `classes/external/save_attendance.php`
- [Schedule API](https://github.com/lapl56/moodle-attendance_tool/blob/main/classes/external/save_schedule.php): external services · Schedule, semester, period, slot, and extra-session CRUD endpoints. · `classes/external/save_schedule.php`
- [Report API](https://github.com/lapl56/moodle-attendance_tool/blob/main/classes/external/get_dashboard_kpis.php): external services · Dashboard, roster, search, and report-filter endpoints. · `classes/external/get_dashboard_kpis.php`
- [Lookup API](https://github.com/lapl56/moodle-attendance_tool/blob/main/classes/external/get_semesters.php): external services · Reference lookups for courses, groups, semesters, sessions, and teachers. · `classes/external/get_semesters.php`

### Shared backend

Common business logic used by pages and service endpoints.

- [Lib](https://github.com/lapl56/moodle-attendance_tool/blob/main/lib.php): shared logic · Common plugin helpers and business rules. · `lib.php`
- [Helper](https://github.com/lapl56/moodle-attendance_tool/blob/main/classes/helper.php): shared logic · Central helper class for date, permission, and data assembly logic. · `classes/helper.php`

### Database and config

Plugin schema, access control, service registration, and upgrade hooks.

- [Schema](https://github.com/lapl56/moodle-attendance_tool/blob/main/db/install.xml): db schema · Table definitions for semesters, schedules, sessions, and attendance. · `db/install.xml`
- [Capabilities](https://github.com/lapl56/moodle-attendance_tool/blob/main/db/access.php): access config · Moodle capability rules for controlling plugin access. · `db/access.php`
- [Services](https://github.com/lapl56/moodle-attendance_tool/blob/main/db/services.php): service config · Registers external service endpoints for AJAX/API use. · `db/services.php`
- [Hooks](https://github.com/lapl56/moodle-attendance_tool/blob/main/db/hooks.php): integration config · Hooks into Moodle events and user-menu integration. · `db/hooks.php`
- [Settings](https://github.com/lapl56/moodle-attendance_tool/blob/main/settings.php): admin config · Plugin settings in Moodle administration. · `settings.php`
- [User menu](https://github.com/lapl56/moodle-attendance_tool/blob/main/classes/hook/extend_user_menu.php): hook · Adds plugin entry into the Moodle user menu. · `classes/hook/extend_user_menu.php`

## Connections

- Moodle → Home: hosts · Moodle serves the plugin landing page.
- Moodle → My schedule: hosts · Moodle serves the student schedule view.
- Moodle → Report: hosts · Moodle serves the reporting interface.
- Home → Attendance JS: loads · Landing page loads the main attendance UI module.
- Home → Schedule JS: loads · Landing page may reuse the schedule interaction module.
- My schedule → Schedule JS: loads · Schedule page loads its dedicated browser module.
- Report → Attendance JS: loads · Reporting UI reuses shared interactive behaviors.
- Attendance JS → Attendance API: calls · Browser actions invoke attendance endpoints via AJAX.
- Attendance JS → Schedule API: calls · Browser editor actions invoke schedule CRUD endpoints.
- Attendance JS → Report API: calls · Dashboard filters and report queries use reporting endpoints.
- Schedule JS → Lookup API: calls · Schedule view fetches schedules, semesters, and related lookups.
- Attendance API → Lib: uses · Attendance endpoints delegate shared business logic.
- Schedule API → Lib: uses · Schedule endpoints delegate shared business logic.
- Report API → Helper: uses · Reporting endpoints assemble filtered summaries through helpers.
- Lookup API → Helper: uses · Lookup endpoints rely on helper routines for scoped data.
- Lib → Schema: reads/writes · Shared logic persists and queries attendance domain tables.
- Helper → Schema: reads · Helper routines assemble domain data from plugin tables.
- Services → Attendance API: registers · Service definitions expose attendance endpoints to Moodle.
- Services → Schedule API: registers · Service definitions expose schedule endpoints to Moodle.
- Services → Report API: registers · Service definitions expose reporting endpoints to Moodle.
- Services → Lookup API: registers · Service definitions expose lookup endpoints to Moodle.
- Capabilities → Moodle: gates · Capabilities control who can access plugin operations.
- Settings → Moodle: configures · Admin settings control plugin behavior and access code workflow.
- Hooks → User menu: contains · Hook configuration wires user-menu integration.
- User menu → Moodle: integrates · The hook adds plugin navigation into Moodle's user menu.
- Hooks → Moodle: integrates · Plugin hooks connect into Moodle event and navigation systems.
