# noone123-qeqwe/school-attendance architecture

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

- Interactive diagram: https://gitdiagram.com/noone123-qeqwe/school-attendance
- Repository: https://github.com/noone123-qeqwe/school-attendance

## Overview

#### Purpose and entry points
A Laravel/PHP school attendance-management system for administrators, teachers, students, and parents. It manages academic structure, enrollments, attendance sessions/records, absences, excuses, warnings, messaging, calendars, and reporting. HTTP enters through `public/index.php`; route definitions separate browser and API surfaces in `routes/web.php` and `routes/api.php`. CLI/scheduled automation uses `artisan` and `routes/console.php`.

#### Application boundary and access control
Controllers render server-side Blade role dashboards and handle mutations. Role-specific middleware gates admin, teacher, student, parent, department-head, and super-admin routes; policies further authorize attendance, sessions, events, students, and subjects. Key boundaries are `app/Http/Middleware/AdminMiddleware.php`, `app/Http/Middleware/EnsureStudentDeviceIsBound.php`, and `app/Policies/AttendancePolicy.php`. Primary UI layouts are under `resources/views/layouts/mbn/`.

#### Identity and attendance verification
Authentication supports conventional login/API auth plus OTP, recovery codes, WebAuthn credentials, and student device binding. Attendance can be recorded through standard, QR, GPS/location, and live-teacher flows. The core session-to-record lifecycle is centered on `app/Http/Controllers/AttendanceController.php`, `app/Http/Controllers/QrAttendanceController.php`, `app/Models/AttendanceSession.php`, and `app/Models/Attendance.php`; QR, device, and WebAuthn rules are encapsulated in `app/Services/QrSessionService.php`, `app/Services/DeviceBindingService.php`, and `app/Services/WebauthnService.php`.

#### Academic and roster domain
The relational domain models users/students, departments, courses, sections, subjects, schedules, academic years, and enrollment. These define which students are eligible for a course/session and support role-scoped reporting. Architectural records are in `app/Models/Enrollment.php`, `app/Models/Subject.php`, and `app/Models/ClassSchedule.php`; administration is exposed through `app/Http/Controllers/Admin/EnrollmentController.php` and `app/Http/Controllers/Admin/ClassScheduleController.php`. Schema evolution and constraints live in `database/migrations/`.

#### Attendance follow-up and exception workflow
Attendance changes produce events/observer hooks and flow into absence checks, warnings, corrections, and excuse submissions. Teachers/admins can review corrections and excuses; parents can submit/link to student workflows. Principal extension points are `app/Observers/AttendanceObserver.php`, `app/Models/AttendanceCorrection.php`, `app/Models/ExcuseSubmission.php`, `app/Events/AttendanceMarked.php`, and `app/Listeners/SendParentAttendanceAlert.php`.

#### Notifications, communication, and real-time delivery
The system persists notifications and messages, delivers email alerts/digests, and has Laravel broadcasting/Reverb and a Semaphore channel/service integration. Relevant components are `app/Models/Notification.php`, `app/Models/Message.php`, `app/Notifications/AttendanceWarningNotification.php`, `app/Mail/ParentDailyDigest.php`, `app/Channels/SemaphoreChannel.php`, and `config/reverb.php`. Broadcast channel authorization is defined in `routes/channels.php`.

#### Automation, reporting, and operations
Scheduled Artisan commands close stale sessions, mark/check absences, compute attendance-rate and early warnings, process warnings, and send parent digests. The key batch orchestration points are `app/Console/Commands/AutoCloseAttendanceSessions.php`, `app/Console/Commands/CheckAbsences.php`, and `app/Console/Commands/SendParentDigests.php`; analytics and exports are handled by `app/Services/AnalyticsService.php` and `app/Exports/AttendanceExport.php`. Deployment supports container/Apache execution and Render configuration via `Dockerfile`, `docker/start.sh`, and `render.yaml`; Laravel database, cache, queue, mail, session, and filesystem adapters are configured under `config/`.

Main entry points: [`app/Models/Attendance.php`](https://github.com/noone123-qeqwe/school-attendance/blob/main/app/Models/Attendance.php) (Attendance record), [`app/Models/AttendanceSession.php`](https://github.com/noone123-qeqwe/school-attendance/blob/main/app/Models/AttendanceSession.php) (Attendance session), [`routes/web.php`](https://github.com/noone123-qeqwe/school-attendance/blob/main/routes/web.php) (Browser routes), [`app/Console/Commands/CheckAbsences.php`](https://github.com/noone123-qeqwe/school-attendance/blob/main/app/Console/Commands/CheckAbsences.php) (Scheduled commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry & Access"]
  node_http["HTTP entry<br/>Laravel bootstrap<br/>[index.php]"]
  node_web_routes["Browser routes<br/>route surface<br/>[web.php]"]
  node_api_routes["API routes<br/>route surface<br/>[api.php]"]
  node_access["Role and device access<br/>middleware"]
  node_attendance_policy["Attendance authorization<br/>policy"]
  node_dashboards["Role dashboards<br/>Blade layouts"]
end

subgraph group_attendance["Attendance Core"]
  node_attendance_controller["Attendance flows<br/>controller"]
  node_qr_controller["QR attendance<br/>controller"]
  node_verification["Verification services<br/>identity services"]
  node_session["Attendance session<br/>domain model"]
  node_attendance_record["Attendance record<br/>domain model<br/>[Attendance.php]"]
  node_academic_roster[("Academic roster<br/>relational domain<br/>[Enrollment.php]")]
  node_schema[("Database schema<br/>migrations")]
end

subgraph group_followup["Follow-up &amp; Delivery"]
  node_attendance_events["Attendance events<br/>observer and event"]
  node_exceptions["Corrections and excuses<br/>exception workflow"]
  node_notifications["Parent alerts<br/>notification delivery"]
  node_realtime["Real-time channels<br/>broadcasting<br/>[reverb.php]"]
end

subgraph group_operations["Automation &amp; Reporting"]
  node_scheduler["Scheduled commands<br/>Artisan automation<br/>[CheckAbsences.php]"]
  node_analytics["Analytics and exports<br/>reporting service"]
  node_cli["CLI scheduler<br/>Artisan entry"]
end

node_http -->|"serves"| node_web_routes
node_http -->|"serves"| node_api_routes
node_web_routes -->|"applies"| node_access
node_api_routes -->|"applies"| node_access
node_access -->|"authorizes"| node_attendance_policy
node_web_routes -->|"renders"| node_dashboards
node_web_routes -->|"dispatches"| node_attendance_controller
node_api_routes -->|"dispatches"| node_qr_controller
node_qr_controller -->|"validates via"| node_verification
node_verification -->|"verifies access to"| node_session
node_attendance_controller -->|"creates and manages"| node_session
node_attendance_controller -->|"records"| node_attendance_record
node_session -->|"contains"| node_attendance_record
node_academic_roster -->|"defines eligible class context"| node_session
node_schema -->|"persists"| node_academic_roster
node_attendance_record -->|"triggers"| node_attendance_events
node_attendance_events -->|"opens follow-up"| node_exceptions
node_attendance_events -->|"alerts"| node_notifications
node_notifications -.->|"broadcasts"| node_realtime
node_cli -->|"runs"| node_scheduler
node_scheduler -->|"closes stale"| node_session
node_scheduler -->|"checks absences"| node_attendance_record
node_scheduler -->|"sends digests"| node_notifications
node_attendance_record -->|"supplies metrics"| node_analytics

click node_http "https://github.com/noone123-qeqwe/school-attendance/blob/main/public/index.php"
click node_web_routes "https://github.com/noone123-qeqwe/school-attendance/blob/main/routes/web.php"
click node_api_routes "https://github.com/noone123-qeqwe/school-attendance/blob/main/routes/api.php"
click node_access "https://github.com/noone123-qeqwe/school-attendance/blob/main/app/Http/Middleware/AdminMiddleware.php"
click node_attendance_policy "https://github.com/noone123-qeqwe/school-attendance/blob/main/app/Policies/AttendancePolicy.php"
click node_attendance_controller "https://github.com/noone123-qeqwe/school-attendance/blob/main/app/Http/Controllers/AttendanceController.php"
click node_qr_controller "https://github.com/noone123-qeqwe/school-attendance/blob/main/app/Http/Controllers/QrAttendanceController.php"
click node_verification "https://github.com/noone123-qeqwe/school-attendance/blob/main/app/Services/QrSessionService.php"
click node_session "https://github.com/noone123-qeqwe/school-attendance/blob/main/app/Models/AttendanceSession.php"
click node_attendance_record "https://github.com/noone123-qeqwe/school-attendance/blob/main/app/Models/Attendance.php"
click node_academic_roster "https://github.com/noone123-qeqwe/school-attendance/blob/main/app/Models/Enrollment.php"
click node_attendance_events "https://github.com/noone123-qeqwe/school-attendance/blob/main/app/Observers/AttendanceObserver.php"
click node_exceptions "https://github.com/noone123-qeqwe/school-attendance/blob/main/app/Models/AttendanceCorrection.php"
click node_notifications "https://github.com/noone123-qeqwe/school-attendance/blob/main/app/Notifications/AttendanceWarningNotification.php"
click node_realtime "https://github.com/noone123-qeqwe/school-attendance/blob/main/config/reverb.php"
click node_scheduler "https://github.com/noone123-qeqwe/school-attendance/blob/main/app/Console/Commands/CheckAbsences.php"
click node_analytics "https://github.com/noone123-qeqwe/school-attendance/blob/main/app/Services/AnalyticsService.php"
click node_cli "https://github.com/noone123-qeqwe/school-attendance/blob/main/artisan"

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_http,node_web_routes,node_api_routes,node_access,node_attendance_policy,node_dashboards toneBlue
class node_attendance_controller,node_qr_controller,node_verification,node_session,node_attendance_record,node_academic_roster,node_schema toneAmber
class node_attendance_events,node_exceptions,node_notifications,node_realtime toneMint
class node_scheduler,node_analytics,node_cli toneRose
```

## Components

### Entry & Access

- [HTTP entry](https://github.com/noone123-qeqwe/school-attendance/blob/main/public/index.php): Laravel bootstrap · `public/index.php`
- [Browser routes](https://github.com/noone123-qeqwe/school-attendance/blob/main/routes/web.php): route surface · `routes/web.php`
- [API routes](https://github.com/noone123-qeqwe/school-attendance/blob/main/routes/api.php): route surface · `routes/api.php`
- [Role and device access](https://github.com/noone123-qeqwe/school-attendance/blob/main/app/Http/Middleware/AdminMiddleware.php): middleware · Gates role routes and bound student devices. · `app/Http/Middleware/AdminMiddleware.php`
- [Attendance authorization](https://github.com/noone123-qeqwe/school-attendance/blob/main/app/Policies/AttendancePolicy.php): policy · `app/Policies/AttendancePolicy.php`
- **Role dashboards**: Blade layouts

### Attendance Core

- [Attendance flows](https://github.com/noone123-qeqwe/school-attendance/blob/main/app/Http/Controllers/AttendanceController.php): controller · Creates sessions and standard or live attendance records. · `app/Http/Controllers/AttendanceController.php`
- [QR attendance](https://github.com/noone123-qeqwe/school-attendance/blob/main/app/Http/Controllers/QrAttendanceController.php): controller · `app/Http/Controllers/QrAttendanceController.php`
- [Verification services](https://github.com/noone123-qeqwe/school-attendance/blob/main/app/Services/QrSessionService.php): identity services · QR sessions, bound devices, and WebAuthn validation. · `app/Services/QrSessionService.php`
- [Attendance session](https://github.com/noone123-qeqwe/school-attendance/blob/main/app/Models/AttendanceSession.php): domain model · `app/Models/AttendanceSession.php`
- [Attendance record](https://github.com/noone123-qeqwe/school-attendance/blob/main/app/Models/Attendance.php): domain model · `app/Models/Attendance.php`
- [Academic roster](https://github.com/noone123-qeqwe/school-attendance/blob/main/app/Models/Enrollment.php): relational domain · Enrollment, subjects, schedules, and academic structure determine eligibility. · `app/Models/Enrollment.php`
- **Database schema**: migrations

### Follow-up & Delivery

- [Attendance events](https://github.com/noone123-qeqwe/school-attendance/blob/main/app/Observers/AttendanceObserver.php): observer and event · Records trigger downstream absence and alert handling. · `app/Observers/AttendanceObserver.php`
- [Corrections and excuses](https://github.com/noone123-qeqwe/school-attendance/blob/main/app/Models/AttendanceCorrection.php): exception workflow · `app/Models/AttendanceCorrection.php`
- [Parent alerts](https://github.com/noone123-qeqwe/school-attendance/blob/main/app/Notifications/AttendanceWarningNotification.php): notification delivery · Persists notifications and delivers warning and digest messages. · `app/Notifications/AttendanceWarningNotification.php`
- [Real-time channels](https://github.com/noone123-qeqwe/school-attendance/blob/main/config/reverb.php): broadcasting · Reverb broadcasting and authorized channels support live delivery. · `config/reverb.php`

### Automation & Reporting

- [Scheduled commands](https://github.com/noone123-qeqwe/school-attendance/blob/main/app/Console/Commands/CheckAbsences.php): Artisan automation · Closes sessions, checks absences, processes warnings, and sends digests. · `app/Console/Commands/CheckAbsences.php`
- [Analytics and exports](https://github.com/noone123-qeqwe/school-attendance/blob/main/app/Services/AnalyticsService.php): reporting service · `app/Services/AnalyticsService.php`
- [CLI scheduler](https://github.com/noone123-qeqwe/school-attendance/blob/main/artisan): Artisan entry · `artisan`

## Connections

- HTTP entry → Browser routes: serves
- HTTP entry → API routes: serves
- Browser routes → Role and device access: applies
- API routes → Role and device access: applies
- Role and device access → Attendance authorization: authorizes
- Browser routes → Role dashboards: renders
- Browser routes → Attendance flows: dispatches
- API routes → QR attendance: dispatches
- QR attendance → Verification services: validates via
- Verification services → Attendance session: verifies access to
- Attendance flows → Attendance session: creates and manages
- Attendance flows → Attendance record: records
- Attendance session → Attendance record: contains
- Academic roster → Attendance session: defines eligible class context
- Database schema → Academic roster: persists
- Attendance record → Attendance events: triggers
- Attendance events → Corrections and excuses: opens follow-up
- Attendance events → Parent alerts: alerts
- Parent alerts → Real-time channels: broadcasts
- CLI scheduler → Scheduled commands: runs
- Scheduled commands → Attendance session: closes stale
- Scheduled commands → Attendance record: checks absences
- Scheduled commands → Parent alerts: sends digests
- Attendance record → Analytics and exports: supplies metrics