# unseenap/auto-exam-main architecture

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

- Interactive diagram: https://gitdiagram.com/unseenap/auto-exam-main
- Repository: https://github.com/unseenap/auto-exam-main

## Overview

GBU Examination Operations Platform is a role-governed web application for university exam administration. Staff manage academic records and import master data, configure exam cycles and calendars, validate and generate date sheets, then review, approve, and publish them. Published schedules support room-aware seating, attendance, invigilation, replacements, and operational reports. The graph highlights the documented workflow and major capabilities; some operational subsystems are documented in the README but their implementation details were not sampled.

Main entry points: [`app/Foundation/Application.php`](https://github.com/unseenap/auto-exam-main/blob/main/app/Foundation/Application.php) (Request routing), [`app/Auth/Auth.php`](https://github.com/unseenap/auto-exam-main/blob/main/app/Auth/Auth.php) (Authentication), [`app/Import/StudentImportService.php`](https://github.com/unseenap/auto-exam-main/blob/main/app/Import/StudentImportService.php) (Validated imports), [`app/Exams/SchedulingValidator.php`](https://github.com/unseenap/auto-exam-main/blob/main/app/Exams/SchedulingValidator.php) (Schedule validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_governance["Access &amp; Core"]
  node_application["Request routing<br/>[Application.php]"]
  node_auth["Authentication<br/>[Auth.php]"]
  node_roles["Role permissions<br/>[RolePolicy.php]"]
  node_database[("MariaDB / MySQL<br/>[Database.php]")]
end

subgraph group_academics["Academic Records"]
  node_academic_masters["Academic masters<br/>[Application.php]"]
  node_student_records["Student records"]
  node_roll_parser["Roll parsing"]
  node_batch_progression["Batch progression"]
  node_imports["Validated imports"]
  node_tabular_reader["CSV / XLSX reader<br/>[TabularReader.php]"]
  node_course_import["Course imports"]
end

subgraph group_scheduling["Exam Scheduling"]
  node_exam_cycles["Cycles &amp; calendars<br/>[ExamService.php]"]
  node_manual_scheduling["Manual date sheets<br/>[ExamService.php]"]
  node_date_import["Date-sheet imports"]
  node_scheduler["Automatic scheduler"]
  node_validator["Schedule validation"]
  node_paper_policy["Written-paper rules"]
  node_review["Draft review"]
  node_publication["Approval &amp; publication"]
end

subgraph group_operations["Exam Operations"]
  node_room_layout["Room layouts"]
  node_seating["Seating allocation"]
  node_attendance["Attendance<br/>[index.php]"]
  node_invigilation["Invigilation duties<br/>[index.php]"]
  node_replacements["Duty replacements<br/>[replacements.php]"]
end

subgraph group_outputs["Exports &amp; Reports"]
  node_reporting["Operational reports<br/>[index.php]"]
  node_xlsx["Branded XLSX export<br/>[XlsxExporter.php]"]
end

node_staff(("University staff"))

node_staff -->|"uses"| node_application
node_application -->|"authenticates"| node_auth
node_auth -->|"checks permissions"| node_roles
node_auth -->|"reads user records"| node_database
node_application -->|"manages"| node_academic_masters
node_application -->|"uses"| node_student_records
node_application -->|"routes imports"| node_imports
node_imports -->|"reads files"| node_tabular_reader
node_imports -->|"parses roll numbers"| node_roll_parser
node_course_import -->|"reads files"| node_tabular_reader
node_application -->|"stages and commits"| node_course_import
node_application -->|"configures cycles"| node_exam_cycles
node_application -->|"manages papers"| node_manual_scheduling
node_application -->|"imports date sheets"| node_date_import
node_application -->|"validates scope"| node_validator
node_validator -->|"derives semesters"| node_batch_progression
node_validator -->|"applies paper rules"| node_paper_policy
node_scheduler -->|"filters written papers"| node_paper_policy
node_application -->|"generates schedules"| node_scheduler
node_application -->|"locks and moves papers"| node_review
node_application -->|"approves and publishes"| node_publication
node_publication -->|"exports date sheets"| node_xlsx
node_application -->|"manages room layouts"| node_room_layout
node_application -->|"generates seating"| node_seating
node_application -->|"supports attendance"| node_attendance
node_application -->|"allocates duties"| node_invigilation
node_application -->|"tracks replacements"| node_replacements
node_application -->|"provides reports"| node_reporting
node_application -->|"exports workbooks"| node_xlsx

click node_application "https://github.com/unseenap/auto-exam-main/blob/main/app/Foundation/Application.php"
click node_auth "https://github.com/unseenap/auto-exam-main/blob/main/app/Auth/Auth.php"
click node_roles "https://github.com/unseenap/auto-exam-main/blob/main/app/Auth/RolePolicy.php"
click node_database "https://github.com/unseenap/auto-exam-main/blob/main/app/Foundation/Database.php"
click node_academic_masters "https://github.com/unseenap/auto-exam-main/blob/main/app/Foundation/Application.php"
click node_student_records "https://github.com/unseenap/auto-exam-main/blob/main/app/Academic/StudentRepository.php"
click node_roll_parser "https://github.com/unseenap/auto-exam-main/blob/main/app/Academic/RollNumberParser.php"
click node_batch_progression "https://github.com/unseenap/auto-exam-main/blob/main/app/Academic/BatchProgression.php"
click node_imports "https://github.com/unseenap/auto-exam-main/blob/main/app/Import/StudentImportService.php"
click node_tabular_reader "https://github.com/unseenap/auto-exam-main/blob/main/app/Import/TabularReader.php"
click node_course_import "https://github.com/unseenap/auto-exam-main/blob/main/app/Import/CourseImportService.php"
click node_exam_cycles "https://github.com/unseenap/auto-exam-main/blob/main/app/Exams/ExamService.php"
click node_manual_scheduling "https://github.com/unseenap/auto-exam-main/blob/main/app/Exams/ExamService.php"
click node_date_import "https://github.com/unseenap/auto-exam-main/blob/main/app/Import/DateSheetImportService.php"
click node_scheduler "https://github.com/unseenap/auto-exam-main/blob/main/app/Exams/AutomaticScheduler.php"
click node_validator "https://github.com/unseenap/auto-exam-main/blob/main/app/Exams/SchedulingValidator.php"
click node_paper_policy "https://github.com/unseenap/auto-exam-main/blob/main/app/Exams/WrittenPaperPolicy.php"
click node_review "https://github.com/unseenap/auto-exam-main/blob/main/app/Exams/ScheduleReviewService.php"
click node_publication "https://github.com/unseenap/auto-exam-main/blob/main/app/Exams/SchedulePublicationService.php"
click node_room_layout "https://github.com/unseenap/auto-exam-main/blob/main/app/Rooms/RoomSeatGenerator.php"
click node_seating "https://github.com/unseenap/auto-exam-main/blob/main/app/Seating/SeatingAllocator.php"
click node_attendance "https://github.com/unseenap/auto-exam-main/blob/main/resources/views/attendance/index.php"
click node_invigilation "https://github.com/unseenap/auto-exam-main/blob/main/resources/views/invigilation/index.php"
click node_replacements "https://github.com/unseenap/auto-exam-main/blob/main/resources/views/invigilation/replacements.php"
click node_reporting "https://github.com/unseenap/auto-exam-main/blob/main/resources/views/reports/index.php"
click node_xlsx "https://github.com/unseenap/auto-exam-main/blob/main/app/Export/XlsxExporter.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_application,node_auth,node_roles,node_database toneBlue
class node_academic_masters,node_student_records,node_roll_parser,node_batch_progression,node_imports,node_tabular_reader,node_course_import toneAmber
class node_exam_cycles,node_manual_scheduling,node_date_import,node_scheduler,node_validator,node_paper_policy,node_review,node_publication toneMint
class node_room_layout,node_seating,node_attendance,node_invigilation,node_replacements toneRose
class node_reporting,node_xlsx,node_staff toneIndigo
```

## Components

### Access & Core

- [Request routing](https://github.com/unseenap/auto-exam-main/blob/main/app/Foundation/Application.php): `app/Foundation/Application.php`
- [Authentication](https://github.com/unseenap/auto-exam-main/blob/main/app/Auth/Auth.php): `app/Auth/Auth.php`
- [Role permissions](https://github.com/unseenap/auto-exam-main/blob/main/app/Auth/RolePolicy.php): `app/Auth/RolePolicy.php`
- [MariaDB / MySQL](https://github.com/unseenap/auto-exam-main/blob/main/app/Foundation/Database.php): `app/Foundation/Database.php`

### Academic Records

- [Academic masters](https://github.com/unseenap/auto-exam-main/blob/main/app/Foundation/Application.php): `app/Foundation/Application.php`
- [Student records](https://github.com/unseenap/auto-exam-main/blob/main/app/Academic/StudentRepository.php): `app/Academic/StudentRepository.php`
- [Roll parsing](https://github.com/unseenap/auto-exam-main/blob/main/app/Academic/RollNumberParser.php): `app/Academic/RollNumberParser.php`
- [Batch progression](https://github.com/unseenap/auto-exam-main/blob/main/app/Academic/BatchProgression.php): `app/Academic/BatchProgression.php`
- [Validated imports](https://github.com/unseenap/auto-exam-main/blob/main/app/Import/StudentImportService.php): `app/Import/StudentImportService.php`
- [CSV / XLSX reader](https://github.com/unseenap/auto-exam-main/blob/main/app/Import/TabularReader.php): `app/Import/TabularReader.php`
- [Course imports](https://github.com/unseenap/auto-exam-main/blob/main/app/Import/CourseImportService.php): `app/Import/CourseImportService.php`

### Exam Scheduling

- [Cycles & calendars](https://github.com/unseenap/auto-exam-main/blob/main/app/Exams/ExamService.php): `app/Exams/ExamService.php`
- [Manual date sheets](https://github.com/unseenap/auto-exam-main/blob/main/app/Exams/ExamService.php): `app/Exams/ExamService.php`
- [Date-sheet imports](https://github.com/unseenap/auto-exam-main/blob/main/app/Import/DateSheetImportService.php): `app/Import/DateSheetImportService.php`
- [Automatic scheduler](https://github.com/unseenap/auto-exam-main/blob/main/app/Exams/AutomaticScheduler.php): `app/Exams/AutomaticScheduler.php`
- [Schedule validation](https://github.com/unseenap/auto-exam-main/blob/main/app/Exams/SchedulingValidator.php): `app/Exams/SchedulingValidator.php`
- [Written-paper rules](https://github.com/unseenap/auto-exam-main/blob/main/app/Exams/WrittenPaperPolicy.php): `app/Exams/WrittenPaperPolicy.php`
- [Draft review](https://github.com/unseenap/auto-exam-main/blob/main/app/Exams/ScheduleReviewService.php): `app/Exams/ScheduleReviewService.php`
- [Approval & publication](https://github.com/unseenap/auto-exam-main/blob/main/app/Exams/SchedulePublicationService.php): `app/Exams/SchedulePublicationService.php`

### Exam Operations

- [Room layouts](https://github.com/unseenap/auto-exam-main/blob/main/app/Rooms/RoomSeatGenerator.php): `app/Rooms/RoomSeatGenerator.php`
- [Seating allocation](https://github.com/unseenap/auto-exam-main/blob/main/app/Seating/SeatingAllocator.php): `app/Seating/SeatingAllocator.php`
- [Attendance](https://github.com/unseenap/auto-exam-main/blob/main/resources/views/attendance/index.php): `resources/views/attendance/index.php`
- [Invigilation duties](https://github.com/unseenap/auto-exam-main/blob/main/resources/views/invigilation/index.php): `resources/views/invigilation/index.php`
- [Duty replacements](https://github.com/unseenap/auto-exam-main/blob/main/resources/views/invigilation/replacements.php): `resources/views/invigilation/replacements.php`

### Exports & Reports

- [Operational reports](https://github.com/unseenap/auto-exam-main/blob/main/resources/views/reports/index.php): `resources/views/reports/index.php`
- [Branded XLSX export](https://github.com/unseenap/auto-exam-main/blob/main/app/Export/XlsxExporter.php): `app/Export/XlsxExporter.php`

### Other components

- **University staff**

## Connections

- University staff → Request routing: uses
- Request routing → Authentication: authenticates (evidence: `app/Foundation/Application.php`)
- Authentication → Role permissions: checks permissions (evidence: `app/Auth/Auth.php`)
- Authentication → MariaDB / MySQL: reads user records (evidence: `app/Auth/Auth.php`)
- Request routing → Academic masters: manages (evidence: `app/Foundation/Application.php`)
- Request routing → Student records: uses (evidence: `app/Foundation/Application.php`)
- Request routing → Validated imports: routes imports (evidence: `app/Foundation/Application.php`)
- Validated imports → CSV / XLSX reader: reads files (evidence: `app/Import/StudentImportService.php`)
- Validated imports → Roll parsing: parses roll numbers (evidence: `app/Import/StudentImportService.php`)
- Course imports → CSV / XLSX reader: reads files (evidence: `app/Import/CourseImportService.php`)
- Request routing → Course imports: stages and commits (evidence: `app/Foundation/Application.php`)
- Request routing → Cycles & calendars: configures cycles (evidence: `app/Foundation/Application.php`)
- Request routing → Manual date sheets: manages papers (evidence: `app/Foundation/Application.php`)
- Request routing → Date-sheet imports: imports date sheets (evidence: `app/Foundation/Application.php`)
- Request routing → Schedule validation: validates scope (evidence: `app/Foundation/Application.php`)
- Schedule validation → Batch progression: derives semesters (evidence: `app/Exams/SchedulingValidator.php`)
- Schedule validation → Written-paper rules: applies paper rules (evidence: `app/Exams/SchedulingValidator.php`)
- Automatic scheduler → Written-paper rules: filters written papers (evidence: `app/Exams/AutomaticScheduler.php`)
- Request routing → Automatic scheduler: generates schedules (evidence: `app/Foundation/Application.php`)
- Request routing → Draft review: locks and moves papers (evidence: `app/Foundation/Application.php`)
- Request routing → Approval & publication: approves and publishes (evidence: `app/Foundation/Application.php`)
- Approval & publication → Branded XLSX export: exports date sheets
- Request routing → Room layouts: manages room layouts (evidence: `app/Foundation/Application.php`)
- Request routing → Seating allocation: generates seating (evidence: `app/Foundation/Application.php`)
- Request routing → Attendance: supports attendance
- Request routing → Invigilation duties: allocates duties
- Request routing → Duty replacements: tracks replacements
- Request routing → Operational reports: provides reports
- Request routing → Branded XLSX export: exports workbooks (evidence: `app/Foundation/Application.php`)
