# libuna2005/cusg-system architecture

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

- Interactive diagram: https://gitdiagram.com/libuna2005/cusg-system
- Repository: https://github.com/libuna2005/cusg-system

## Overview

CUSG Attendance Portal is a PHP/MySQL campus attendance application. Officers scan student QR codes at events; attendance is recorded for the event, while students can view their attendance and administrators manage events, targeting, attendance controls, and reporting. The graph preserves the README’s major capabilities, including batch scanning, population summaries, and photo caching. Several feature paths are represented from the tree and README; their internal wiring is not asserted where source excerpts do not show it.

Main entry points: [`api/student/attendance.php`](https://github.com/libuna2005/cusg-system/blob/main/api/student/attendance.php) (Attendance View), [`database/cusg_mysql_schema.sql`](https://github.com/libuna2005/cusg-system/blob/main/database/cusg_mysql_schema.sql) (MySQL Data), [`api/config.php`](https://github.com/libuna2005/cusg-system/blob/main/api/config.php) (Database Connection), [`api/auth/register.php`](https://github.com/libuna2005/cusg-system/blob/main/api/auth/register.php) (Student Registration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_event_ops["Event Operations"]
  node_events["Event Management<br/>[events.php]"]
  node_event_groups["Event Groups<br/>[event_groups.php]"]
  node_excuses["Excuse Management<br/>[excuse.php]"]
  node_attendance_export["Attendance Export"]
  node_population["Population Summary<br/>[students.php]"]
end

subgraph group_accounts["Accounts"]
  node_registration["Student Registration<br/>[register.php]"]
  node_student_profile["Student Profile<br/>[profile.php]"]
  node_student_photo["Photo Uploads<br/>[uploads.php]"]
  node_photo_cache["Photo Cache<br/>[admin.html]"]
  node_auth["Authentication<br/>[login.php]"]
end

subgraph group_attendance["Attendance"]
  node_scan_ui["Scan Panel<br/>[admin.html]"]
  node_live_scan["Live QR Scan<br/>[scan.php]"]
  node_batch_scan["Batch Upload<br/>[scan_batch.php]"]
  node_student_attendance["Attendance View<br/>[attendance.php]"]
  node_attendance_lock["Attendance Lock"]
  node_session_completion["Session Completion"]
  node_unresolved["Unresolved Scans"]
  node_audit_log["Upload Audit"]
end

subgraph group_shared["Shared Backend"]
  node_scan_helpers["Scan Helpers<br/>[scan_common.php]"]
  node_shared_helpers["Common Helpers<br/>[common.php]"]
  node_schema_helpers["Schema Helpers<br/>[schema.php]"]
  node_database_config["Database Connection<br/>[config.php]"]
  node_database[("MySQL Data")]
end

node_officer(("Student Officer"))
node_student(("Student"))
node_admin_user(("Administrator"))

node_officer -->|"scans QR"| node_scan_ui
node_scan_ui -.->|"submits scans"| node_live_scan
node_officer -->|"uploads batch"| node_batch_scan
node_live_scan -->|"records attendance"| node_database
node_batch_scan -->|"records attendance"| node_database
node_batch_scan -->|"uses helpers"| node_scan_helpers
node_live_scan -->|"uses helpers"| node_scan_helpers
node_student -.->|"views attendance"| node_student_attendance
node_student_attendance -->|"reads attendance"| node_database
node_admin_user -.->|"sets lock"| node_attendance_lock
node_admin_user -.->|"manages events"| node_events
node_admin_user -.->|"manages groups"| node_event_groups
node_admin_user -.->|"manages excuses"| node_excuses
node_admin_user -.->|"exports attendance"| node_attendance_export
node_admin_user -.->|"views population"| node_population
node_admin_user -.->|"reviews scans"| node_unresolved
node_admin_user -.->|"reviews uploads"| node_audit_log
node_student -.->|"registers"| node_registration
node_student -.->|"updates profile"| node_student_profile
node_registration -->|"saves photo"| node_student_photo
node_student_profile -->|"updates profile"| node_database
node_database_config -->|"connects to"| node_database
node_registration -->|"loads connection"| node_database_config
node_student_profile -->|"loads connection"| node_database_config
node_student_attendance -->|"loads connection"| node_database_config
node_student_attendance -->|"uses helpers"| node_shared_helpers
node_student_attendance -->|"uses helpers"| node_schema_helpers
node_photo_cache -.->|"caches photos"| node_student_photo

click node_scan_ui "https://github.com/libuna2005/cusg-system/blob/main/views/admin.html"
click node_live_scan "https://github.com/libuna2005/cusg-system/blob/main/api/admin/scan.php"
click node_batch_scan "https://github.com/libuna2005/cusg-system/blob/main/api/admin/scan_batch.php"
click node_scan_helpers "https://github.com/libuna2005/cusg-system/blob/main/api/lib/scan_common.php"
click node_student_attendance "https://github.com/libuna2005/cusg-system/blob/main/api/student/attendance.php"
click node_attendance_lock "https://github.com/libuna2005/cusg-system/blob/main/api/admin/attendance_lock.php"
click node_session_completion "https://github.com/libuna2005/cusg-system/blob/main/api/admin/session_completion.php"
click node_unresolved "https://github.com/libuna2005/cusg-system/blob/main/api/admin/unresolved_scans.php"
click node_audit_log "https://github.com/libuna2005/cusg-system/blob/main/api/admin/upload_audit_log.php"
click node_events "https://github.com/libuna2005/cusg-system/blob/main/api/admin/events.php"
click node_event_groups "https://github.com/libuna2005/cusg-system/blob/main/api/admin/event_groups.php"
click node_excuses "https://github.com/libuna2005/cusg-system/blob/main/api/admin/excuse.php"
click node_attendance_export "https://github.com/libuna2005/cusg-system/blob/main/api/admin/export_attendance.php"
click node_population "https://github.com/libuna2005/cusg-system/blob/main/api/admin/students.php"
click node_registration "https://github.com/libuna2005/cusg-system/blob/main/api/auth/register.php"
click node_student_profile "https://github.com/libuna2005/cusg-system/blob/main/api/student/profile.php"
click node_student_photo "https://github.com/libuna2005/cusg-system/blob/main/api/lib/uploads.php"
click node_photo_cache "https://github.com/libuna2005/cusg-system/blob/main/views/admin.html"
click node_auth "https://github.com/libuna2005/cusg-system/blob/main/api/auth/login.php"
click node_shared_helpers "https://github.com/libuna2005/cusg-system/blob/main/api/lib/common.php"
click node_schema_helpers "https://github.com/libuna2005/cusg-system/blob/main/api/lib/schema.php"
click node_database_config "https://github.com/libuna2005/cusg-system/blob/main/api/config.php"
click node_database "https://github.com/libuna2005/cusg-system/blob/main/database/cusg_mysql_schema.sql"

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_events,node_event_groups,node_excuses,node_attendance_export,node_population toneBlue
class node_registration,node_student_profile,node_student_photo,node_photo_cache,node_auth toneAmber
class node_scan_ui,node_live_scan,node_batch_scan,node_student_attendance,node_attendance_lock,node_session_completion,node_unresolved,node_audit_log toneMint
class node_scan_helpers,node_shared_helpers,node_schema_helpers,node_database_config,node_database toneRose
class node_officer,node_student,node_admin_user toneIndigo
```

## Components

### Event Operations

- [Event Management](https://github.com/libuna2005/cusg-system/blob/main/api/admin/events.php): `api/admin/events.php`
- [Event Groups](https://github.com/libuna2005/cusg-system/blob/main/api/admin/event_groups.php): `api/admin/event_groups.php`
- [Excuse Management](https://github.com/libuna2005/cusg-system/blob/main/api/admin/excuse.php): `api/admin/excuse.php`
- [Attendance Export](https://github.com/libuna2005/cusg-system/blob/main/api/admin/export_attendance.php): `api/admin/export_attendance.php`
- [Population Summary](https://github.com/libuna2005/cusg-system/blob/main/api/admin/students.php): `api/admin/students.php`

### Accounts

- [Student Registration](https://github.com/libuna2005/cusg-system/blob/main/api/auth/register.php): `api/auth/register.php`
- [Student Profile](https://github.com/libuna2005/cusg-system/blob/main/api/student/profile.php): `api/student/profile.php`
- [Photo Uploads](https://github.com/libuna2005/cusg-system/blob/main/api/lib/uploads.php): `api/lib/uploads.php`
- [Photo Cache](https://github.com/libuna2005/cusg-system/blob/main/views/admin.html): `views/admin.html`
- [Authentication](https://github.com/libuna2005/cusg-system/blob/main/api/auth/login.php): `api/auth/login.php`

### Attendance

- [Scan Panel](https://github.com/libuna2005/cusg-system/blob/main/views/admin.html): `views/admin.html`
- [Live QR Scan](https://github.com/libuna2005/cusg-system/blob/main/api/admin/scan.php): `api/admin/scan.php`
- [Batch Upload](https://github.com/libuna2005/cusg-system/blob/main/api/admin/scan_batch.php): `api/admin/scan_batch.php`
- [Attendance View](https://github.com/libuna2005/cusg-system/blob/main/api/student/attendance.php): `api/student/attendance.php`
- [Attendance Lock](https://github.com/libuna2005/cusg-system/blob/main/api/admin/attendance_lock.php): `api/admin/attendance_lock.php`
- [Session Completion](https://github.com/libuna2005/cusg-system/blob/main/api/admin/session_completion.php): `api/admin/session_completion.php`
- [Unresolved Scans](https://github.com/libuna2005/cusg-system/blob/main/api/admin/unresolved_scans.php): `api/admin/unresolved_scans.php`
- [Upload Audit](https://github.com/libuna2005/cusg-system/blob/main/api/admin/upload_audit_log.php): `api/admin/upload_audit_log.php`

### Shared Backend

- [Scan Helpers](https://github.com/libuna2005/cusg-system/blob/main/api/lib/scan_common.php): `api/lib/scan_common.php`
- [Common Helpers](https://github.com/libuna2005/cusg-system/blob/main/api/lib/common.php): `api/lib/common.php`
- [Schema Helpers](https://github.com/libuna2005/cusg-system/blob/main/api/lib/schema.php): `api/lib/schema.php`
- [Database Connection](https://github.com/libuna2005/cusg-system/blob/main/api/config.php): `api/config.php`
- [MySQL Data](https://github.com/libuna2005/cusg-system/blob/main/database/cusg_mysql_schema.sql): `database/cusg_mysql_schema.sql`

### Other components

- **Student Officer**
- **Student**
- **Administrator**

## Connections

- Student Officer → Scan Panel: scans QR (evidence: `readme.md`)
- Scan Panel → Live QR Scan: submits scans
- Student Officer → Batch Upload: uploads batch (evidence: `readme.md`)
- Live QR Scan → MySQL Data: records attendance (evidence: `readme.md`)
- Batch Upload → MySQL Data: records attendance (evidence: `api/admin/scan_batch.php`)
- Batch Upload → Scan Helpers: uses helpers (evidence: `api/admin/scan_batch.php`)
- Live QR Scan → Scan Helpers: uses helpers (evidence: `api/admin/scan.php`)
- Student → Attendance View: views attendance
- Attendance View → MySQL Data: reads attendance (evidence: `api/student/attendance.php`)
- Administrator → Attendance Lock: sets lock
- Administrator → Event Management: manages events
- Administrator → Event Groups: manages groups
- Administrator → Excuse Management: manages excuses
- Administrator → Attendance Export: exports attendance
- Administrator → Population Summary: views population (evidence: `readme.md`)
- Administrator → Unresolved Scans: reviews scans
- Administrator → Upload Audit: reviews uploads
- Student → Student Registration: registers
- Student → Student Profile: updates profile
- Student Registration → Photo Uploads: saves photo (evidence: `api/auth/register.php`)
- Student Profile → MySQL Data: updates profile (evidence: `api/student/profile.php`)
- Database Connection → MySQL Data: connects to (evidence: `api/config.php`)
- Student Registration → Database Connection: loads connection (evidence: `api/auth/register.php`)
- Student Profile → Database Connection: loads connection (evidence: `api/student/profile.php`)
- Attendance View → Database Connection: loads connection (evidence: `api/student/attendance.php`)
- Attendance View → Common Helpers: uses helpers (evidence: `api/student/attendance.php`)
- Attendance View → Schema Helpers: uses helpers (evidence: `api/student/attendance.php`)
- Photo Cache → Photo Uploads: caches photos (evidence: `readme.md`)