# gibbonedu/core architecture

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

- Interactive diagram: https://gitdiagram.com/gibbonedu/core
- Repository: https://github.com/gibbonedu/core

## Overview

1. **What this repository is**
   Gibbon Core is a large PHP school management monolith. It serves the main application, installer, update routines, background jobs, and most shared infrastructure. Feature areas are split into modules, but they all run inside the same codebase and database.

2. **Top-level request entry points**
   The primary web entry points are the root PHP files such as `index.php`, `login.php`, `logout.php`, `report.php`, `preferences.php`, `installer/install.php`, and a set of AJAX/process endpoints like `index_notification_ajax.php` and `index_tt_ajax.php`. These act as front controllers or action handlers rather than a single centralized API layer.

3. **Core application layer**
   The `src/` tree contains the reusable application framework: authentication, sessions, database access, service providers, view rendering, forms, tables, UI components, and domain gateways. This is the architectural center of the repo and is what modules build on.

4. **Data access pattern**
   Most business logic accesses the database through `src/Domain/*Gateway.php` classes. The gateways are grouped by business area such as Students, Staff, Timetable, Finance, Reports, etc. This gives the repo a consistent domain-to-database boundary even though the application is not organized as a modern API service.

5. **Module system**
   The `modules/` directory is where almost all end-user features live. Each module is a self-contained mini-application with its own page controllers, `Process` scripts, optional `src/` helpers, Twig templates, and module-specific JS/CSS. Examples include Attendance, Finance, Messenger, Planner, Reports, Staff, Students, Timetable, and many admin modules.

6. **Page/process split inside modules**
   A common pattern is “view page” + “process page” + “AJAX endpoint”. For example, many actions have `*_add.php`, `*_edit.php`, `*_delete.php`, and corresponding `*Process.php` files. This makes the control flow very explicit: render a form or view, then submit to a dedicated action handler that mutates state and redirects or returns JSON.

7. **Presentation layer**
   UI rendering is handled through Twig templates and reusable UI building blocks in `resources/templates/`, `src/View/`, `src/UI/`, `src/Tables/`, and module-specific `templates/` folders. Themes in `themes/Default` and `themes/Legacy` provide the visual skin and top-level page templates, while shared CSS/JS live in `resources/assets/`.

8. **Forms, tables, and rich widgets**
   The app has substantial internal UI tooling: a form builder (`src/Forms`), table/rendering abstractions (`src/Tables`), and specialized widgets for charts, timetables, and dashboards (`src/UI`). This is important architecturally because many modules compose these primitives rather than hand-rolling HTML.

9. **Background jobs and scheduled work**
   The `cli/` directory contains cron-style scripts for notifications, summaries, reminders, and system maintenance. These jobs typically read from the database, apply business rules, and send email/SMS or update system state. This is a separate execution path from interactive HTTP requests.

10. **Comms and external services**
   Communication is centralized in `src/Comms` and related contracts/services. The app supports email, SMS, notifications, and some OAuth-style authentication adapters. Payment integration is abstracted behind service contracts, and third-party settings are managed from admin modules.

11. **Installer, updates, and migrations**
   Installation and upgrades are first-class parts of the architecture. `installer/`, `src/Install`, `src/Database/Migrations`, `update.php`, and `src/Database/Updater.php` manage schema evolution and initial setup. This suggests the app is expected to be deployed and maintained over long-lived school installations.

12. **Configuration and operational environment**
   Runtime setup is PHP/MySQL/Apache-oriented, with Docker support in `ops/` and a development bootstrap script `up.sh`. Environment-specific concerns include session handling, caching, file uploads, localization, and system settings stored in the database.

13. **Testing and quality gates**
   The repo includes broad automated tests: unit tests under `tests/unit`, installer tests, and extensive acceptance tests under `tests/acceptance`. This indicates that module workflows and UI flows are part of the contract, not just low-level classes.

14. **How to diagram it**
   A good architecture diagram should show: browser or cron job entering the app; shared core services and auth/session; module controllers/processors; domain gateways; the central MySQL database; Twig/theme/UI rendering; and outbound channels like email/SMS/notifications. The key boundary is between shared framework code in `src/` and feature-specific logic in `modules/`.

Main entry points: [`src/Services`](https://github.com/gibbonedu/core/tree/v31.0.00/src/Services) (Services), [`src/Domain`](https://github.com/gibbonedu/core/tree/v31.0.00/src/Domain) (Domain gateways), [`modules`](https://github.com/gibbonedu/core/tree/v31.0.00/modules) (Modules), [`src/View`](https://github.com/gibbonedu/core/tree/v31.0.00/src/View) (View layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entrypoints["Entry points"]
  node_index_php["Home<br/>web front controller<br/>[index.php]"]
  node_auth_pages["Auth pages<br/>web actions<br/>[login.php]"]
  node_ajax_endpoints["Ajax handlers<br/>async endpoints"]
  node_installer_php["Installer<br/>setup entry point<br/>[install.php]"]
end

subgraph group_core["Core framework"]
  node_core_services["Services<br/>service layer"]
  node_auth_session["Auth & session<br/>security/session"]
  node_db_layer[("Database<br/>persistence")]
  node_domain_gateways["Domain gateways<br/>data access boundary"]
  node_forms_builder["Forms<br/>form system"]
  node_tables_ui["Tables<br/>table system"]
  node_ui_components["UI toolkit<br/>ui primitives"]
  node_view_layer["View layer<br/>rendering"]
  node_module_runtime["Module loader<br/>module runtime<br/>[ModuleLoader.php]"]
end

subgraph group_modules["Feature modules"]
  node_modules_root["Modules"]
  node_reports_module["Reports<br/>module subsystem"]
  node_planner_module["Planner<br/>module subsystem"]
  node_staff_module["Staff<br/>module subsystem"]
  node_student_module["Students<br/>module subsystem"]
end

subgraph group_presentation["Presentation"]
  node_default_theme["Themes<br/>presentation skin"]
  node_shared_assets["Assets"]
end

subgraph group_operations["Operations"]
  node_background_jobs["CLI jobs<br/>scheduled jobs"]
  node_installer_update["Install/update<br/>maintenance<br/>[update.php]"]
  node_ops_support["Ops support<br/>deployment/runtime"]
end

subgraph group_quality["Quality"]
  node_tests_root["Tests<br/>verification"]
end

node_index_php -->|"boot via"| node_core_services
node_auth_pages -->|"authenticate"| node_auth_session
node_ajax_endpoints -->|"dispatch via"| node_core_services
node_installer_php -->|"sets up"| node_installer_update
node_core_services -->|"uses"| node_auth_session
node_core_services -->|"renders"| node_view_layer
node_core_services -->|"loads"| node_module_runtime
node_module_runtime -->|"activates"| node_modules_root
node_modules_root -->|"reads/writes"| node_domain_gateways
node_domain_gateways -->|"queries"| node_db_layer
node_forms_builder -->|"submits to"| node_domain_gateways
node_tables_ui -->|"renders in"| node_view_layer
node_ui_components -->|"compose"| node_view_layer
node_modules_root -->|"builds forms"| node_forms_builder
node_modules_root -->|"builds tables"| node_tables_ui
node_modules_root -->|"uses widgets"| node_ui_components
node_reports_module -->|"aggregates from"| node_domain_gateways
node_reports_module -->|"renders"| node_view_layer
node_planner_module -->|"depends on"| node_domain_gateways
node_staff_module -->|"depends on"| node_domain_gateways
node_student_module -->|"depends on"| node_domain_gateways
node_background_jobs -->|"boot via"| node_core_services
node_background_jobs -->|"processes"| node_domain_gateways
node_installer_update -->|"migrates"| node_db_layer
node_ops_support -->|"supports"| node_core_services
node_tests_root -->|"covers"| node_modules_root
node_tests_root -->|"covers"| node_core_services

click node_index_php "https://github.com/gibbonedu/core/blob/v31.0.00/index.php"
click node_auth_pages "https://github.com/gibbonedu/core/blob/v31.0.00/login.php"
click node_ajax_endpoints "https://github.com/gibbonedu/core/blob/v31.0.00/index_notification_ajax.php"
click node_installer_php "https://github.com/gibbonedu/core/blob/v31.0.00/installer/install.php"
click node_core_services "https://github.com/gibbonedu/core/tree/v31.0.00/src/Services"
click node_auth_session "https://github.com/gibbonedu/core/tree/v31.0.00/src/Auth"
click node_db_layer "https://github.com/gibbonedu/core/tree/v31.0.00/src/Database"
click node_domain_gateways "https://github.com/gibbonedu/core/tree/v31.0.00/src/Domain"
click node_forms_builder "https://github.com/gibbonedu/core/tree/v31.0.00/src/Forms"
click node_tables_ui "https://github.com/gibbonedu/core/tree/v31.0.00/src/Tables"
click node_ui_components "https://github.com/gibbonedu/core/tree/v31.0.00/src/UI"
click node_view_layer "https://github.com/gibbonedu/core/tree/v31.0.00/src/View"
click node_module_runtime "https://github.com/gibbonedu/core/blob/v31.0.00/src/Services/ModuleLoader.php"
click node_default_theme "https://github.com/gibbonedu/core/tree/v31.0.00/themes/Default"
click node_shared_assets "https://github.com/gibbonedu/core/tree/v31.0.00/resources/assets"
click node_modules_root "https://github.com/gibbonedu/core/tree/v31.0.00/modules"
click node_reports_module "https://github.com/gibbonedu/core/tree/v31.0.00/modules/Reports"
click node_planner_module "https://github.com/gibbonedu/core/tree/v31.0.00/modules/Planner"
click node_staff_module "https://github.com/gibbonedu/core/tree/v31.0.00/modules/Staff"
click node_student_module "https://github.com/gibbonedu/core/tree/v31.0.00/modules/Students"
click node_background_jobs "https://github.com/gibbonedu/core/tree/v31.0.00/cli"
click node_installer_update "https://github.com/gibbonedu/core/blob/v31.0.00/update.php"
click node_ops_support "https://github.com/gibbonedu/core/tree/v31.0.00/ops"
click node_tests_root "https://github.com/gibbonedu/core/tree/v31.0.00/tests"

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_index_php,node_auth_pages,node_ajax_endpoints,node_installer_php toneBlue
class node_core_services,node_auth_session,node_db_layer,node_domain_gateways,node_forms_builder,node_tables_ui,node_ui_components,node_view_layer,node_module_runtime toneAmber
class node_modules_root,node_reports_module,node_planner_module,node_staff_module,node_student_module toneMint
class node_default_theme,node_shared_assets toneRose
class node_background_jobs,node_installer_update,node_ops_support toneIndigo
class node_tests_root toneTeal
```

## Components

### Entry points

HTTP front controllers and action handlers

- [Home](https://github.com/gibbonedu/core/blob/v31.0.00/index.php): web front controller · Main application entry point · `index.php`
- [Auth pages](https://github.com/gibbonedu/core/blob/v31.0.00/login.php): web actions · Login, logout, preferences, password reset, notifications, and report access flows · `login.php`
- [Ajax handlers](https://github.com/gibbonedu/core/blob/v31.0.00/index_notification_ajax.php): async endpoints · Notification, timetable, and other request handlers · `index_notification_ajax.php`
- [Installer](https://github.com/gibbonedu/core/blob/v31.0.00/installer/install.php): setup entry point · Initial installation flow · `installer/install.php`

### Core framework

Shared runtime, auth, database, forms, tables, and UI

- [Services](https://github.com/gibbonedu/core/tree/v31.0.00/src/Services): service layer · Bootstrapping, auth, module loading, view services, background processing · `src/Services`
- [Auth & session](https://github.com/gibbonedu/core/tree/v31.0.00/src/Auth): security/session · Authentication adapters, session handling, and access control · `src/Auth`
- [Database](https://github.com/gibbonedu/core/tree/v31.0.00/src/Database): persistence · Connection, result handling, updater, and migrations · `src/Database`
- [Domain gateways](https://github.com/gibbonedu/core/tree/v31.0.00/src/Domain): data access boundary · Repository-wide gateway layer for business data · `src/Domain`
- [Forms](https://github.com/gibbonedu/core/tree/v31.0.00/src/Forms): form system · Form construction, storage, processors, and custom field handling · `src/Forms`
- [Tables](https://github.com/gibbonedu/core/tree/v31.0.00/src/Tables): table system · Data table rendering, views, and export renderers · `src/Tables`
- [UI toolkit](https://github.com/gibbonedu/core/tree/v31.0.00/src/UI): ui primitives · Charts, dashboard widgets, timetable UI, icons, and reusable components · `src/UI`
- [View layer](https://github.com/gibbonedu/core/tree/v31.0.00/src/View): rendering · Page, view, component, and asset abstractions · `src/View`
- [Module loader](https://github.com/gibbonedu/core/blob/v31.0.00/src/Services/ModuleLoader.php): module runtime · Shared module discovery and lifecycle support · `src/Services/ModuleLoader.php`

### Feature modules

Self-contained application modules

- [Modules](https://github.com/gibbonedu/core/tree/v31.0.00/modules): feature modules · Feature-specific controllers, processes, templates, and helpers · `modules`
- [Reports](https://github.com/gibbonedu/core/tree/v31.0.00/modules/Reports): module subsystem · Reporting workflows, templates, renderers, and data sources · `modules/Reports`
- [Planner](https://github.com/gibbonedu/core/tree/v31.0.00/modules/Planner): module subsystem · Planning, units, resources, and homework workflows · `modules/Planner`
- [Staff](https://github.com/gibbonedu/core/tree/v31.0.00/modules/Staff): module subsystem · Staff absences, coverage, duty, recruitment, and messaging flows · `modules/Staff`
- [Students](https://github.com/gibbonedu/core/tree/v31.0.00/modules/Students): module subsystem · Student profiles, medical forms, applications, and records · `modules/Students`

### Presentation

Themes, templates, and shared assets

- [Themes](https://github.com/gibbonedu/core/tree/v31.0.00/themes/Default): presentation skin · Default and legacy themes with top-level page templates · `themes/Default`
- [Assets](https://github.com/gibbonedu/core/tree/v31.0.00/resources/assets): static assets · Shared CSS, JS, fonts, and media · `resources/assets`

### Operations

CLI jobs, installer, updates, and deployment support

- [CLI jobs](https://github.com/gibbonedu/core/tree/v31.0.00/cli): scheduled jobs · Cron-style notifications, summaries, and maintenance scripts · `cli`
- [Install/update](https://github.com/gibbonedu/core/blob/v31.0.00/update.php): maintenance · Install, update, and schema evolution routines · `update.php`
- [Ops support](https://github.com/gibbonedu/core/tree/v31.0.00/ops): deployment/runtime · Docker and environment setup for local and deployed runtimes · `ops`

### Quality

Automated tests and verification

- [Tests](https://github.com/gibbonedu/core/tree/v31.0.00/tests): verification · Acceptance, install, and unit test suites · `tests`

## Connections

- Home → Services: boot via · Front controller initializes shared runtime
- Auth pages → Auth & session: authenticate · Login, logout, password reset, and access checks
- Ajax handlers → Services: dispatch via · Async handlers reuse shared bootstrapping
- Installer → Install/update: sets up · Installation flow creates the application baseline
- Services → Auth & session: uses · Service provider wires auth and session support
- Services → View layer: renders · Services provide the page/view pipeline
- Services → Module loader: loads · Module loader discovers enabled modules
- Module loader → Modules: activates · Modules are loaded into the shared runtime
- Modules → Domain gateways: reads/writes · Module controllers use gateway classes for business data
- Domain gateways → Database: queries · Gateways are the main database boundary
- Forms → Domain gateways: submits to · Form flows persist through gateways
- Tables → View layer: renders in · Tabular views are part of page rendering
- UI toolkit → View layer: compose · Charts, dashboards, and widgets feed the view layer
- Modules → Forms: builds forms · Many module pages use shared form primitives
- Modules → Tables: builds tables · Many module pages use shared table primitives
- Modules → UI toolkit: uses widgets · Modules compose dashboards, timelines, and charts
- Reports → Domain gateways: aggregates from · Report generation pulls from multiple domain gateways
- Reports → View layer: renders · Report preview and output use shared views and templates
- Planner → Domain gateways: depends on · Planner persists units, resources, and homework through gateways
- Staff → Domain gateways: depends on · Staff workflows coordinate absences, coverage, and messages
- Students → Domain gateways: depends on · Student workflows manage enrolment, records, and notes
- CLI jobs → Services: boot via · Scheduled scripts use the same service/runtime stack
- CLI jobs → Domain gateways: processes · Jobs read and update school data
- Install/update → Database: migrates · Updates manage schema and long-lived deployments
- Ops support → Services: supports · Container and PHP runtime settings support the app
- Tests → Modules: covers · Acceptance tests exercise major module workflows
- Tests → Services: covers · Unit and integration tests verify shared framework code