# subjectsplus/subjectsplus architecture

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

- Interactive diagram: https://gitdiagram.com/subjectsplus/subjectsplus
- Repository: https://github.com/subjectsplus/subjectsplus

## Overview

##### Project type and purpose
- Full-stack, monolithic PHP web application (LAMP/WAMP)
- Two main “faces”: an administrative backend (“control” directory) and a public site (“subjects” directory)

##### File structure
- Top-level web entry points
– index.php (root) → routes to control (admin) or public modules based on URL
– healthcheck.php
- Directories
– control/ → PHP scripts and helpers for admin UI (user management, guide‐building, stats, LTI)
– subjects/ → public site scripts, theming, view templates
– api/ → lightweight endpoints (e.g., adddisciplinedescription.php)
– addons/ → LTI integrations (Blackboard LTI 1.x & 1.3)
– lib/ → third-party libraries and core business logic (“SubjectsPlus/Control”, “SubjectsPlus/API”)
– assets/ → CSS, JS, images, localization files
– oai/ → OAI-PMH XML feeds and XSLT transforms
- Configuration & build files
– composer.json / composer.lock
– .htaccess-default in api/
– control/includes/config-default.php

##### README
- Tech stack requirements: PHP 5.3–5.6, MySQL 4–5.6, Apache (or IIS)
- PHP extensions: cURL, mbstring, simplexml, json, gettext, gd
- Links out to API documentation, installation wiki

##### Main components & interactions
A. Web Server Layer
– Apache (or IIS)
– Virtual hosts pointing at document root
B. PHP Application Layer
1. Front Controllers
- root/index.php → dispatch to control/ or subjects/ modules
- api/index.php → handles REST-like calls
2. Admin UI (control/)
- PHP pages + includes → call into lib/SubjectsPlus/Control classes
- LTI controller (control/lti_controller/)
3. Public Site (subjects/)
- Themed scripts + view includes → call into lib/SubjectsPlus/Control and API classes
4. Core Business Logic (lib/SubjectsPlus/Control & lib/SubjectsPlus/API)
- Controllers orchestrate operations, data validation, templating
- API layer (DatabaseWebService, GuidesWebService, etc.) provides JSON/XML endpoints
C. Data Layer
– MySQL database
– Tables for guides, disciplines, staff, FAQs, videos, logs, LTI credentials
D. Static Asset Pipeline
– Assetic (lib/Assetic) compiles & caches CSS/JS/images
– CKEditor (ckeditor/) integrated for rich text editing in admin
– Select2, jQuery, FontAwesome under assets/
E. External Services
– SMTP server via PHPMailer (lib/PHPMailer) for email notifications
– Google reCAPTCHA (lib/ReCaptcha) for spam prevention
– Blackboard LTI tool providers (api, addons/bb-lti)
– OAI-PMH consumers (oai/)
– Optional: external resource APIs via pluslets (e.g., Google Books)

##### Architectural patterns & design principles
- Layered architecture (Presentation → Business Logic → Data)
- Modular separation: Admin (“control”) vs. Public (“subjects”) vs. API vs. LTI vs. OAI
- Dependency management via Composer (third-party libs under lib/)
- CSRF protection via CSRF-Protector (lib/CSRF-Protector-PHP-nojs)
- Internationalization via gettext (assets/locale)

##### Essential elements
- Component labels (e.g., “control/index.php”, “SubjectsPlus/Control/Guide”, “MySQL DB”)
– Blue for application modules
– Green for infrastructure (web server, DB)
– Orange for external integrations

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client to Server
    Client["Client Browser"]:::ext -->|HTTP GET/POST| WebServer[(Apache/IIS)]:::infra

    %% Web Server Entry Points
    WebServer -->|routes| Index["index.php"]:::app
    click Index "https://github.com/subjectsplus/subjectsplus/blob/master/index.php"
    WebServer -->|healthcheck| Health["healthcheck.php"]:::app
    click Health "https://github.com/subjectsplus/subjectsplus/blob/master/healthcheck.php"
    WebServer -->|API calls| APIFront["api/index.php"]:::app
    click APIFront "https://github.com/subjectsplus/subjectsplus/blob/master/api/index.php"

    %% Admin UI Layer
    subgraph "Admin UI (control)" 
        ControlIndex["control/index.php"]:::app
        click ControlIndex "https://github.com/subjectsplus/subjectsplus/tree/master/control/"
        subgraph "Configuration & Helpers"
            ControlIncludes["control/includes/"]:::app
            click ControlIncludes "https://github.com/subjectsplus/subjectsplus/tree/master/control/includes/"
        end
        subgraph "Admin Pages"
            AdminPages["control/admin/"]:::app
            click AdminPages "https://github.com/subjectsplus/subjectsplus/tree/master/control/admin/"
        end
        subgraph "LTI Controller"
            LTIController["control/lti_controller/"]:::app
            click LTIController "https://github.com/subjectsplus/subjectsplus/tree/master/control/lti_controller/"
        end
        subgraph "Talkback Admin"
            TalkbackAdmin["control/talkback/"]:::app
            click TalkbackAdmin "https://github.com/subjectsplus/subjectsplus/tree/master/control/talkback/"
        end
    end
    Index -->|dispatch| ControlIndex

    %% Public Site Layer
    subgraph "Public Site (subjects)"
        SubjectsRoot["subjects/"]:::app
        click SubjectsRoot "https://github.com/subjectsplus/subjectsplus/tree/master/subjects/"
        subgraph "Shared Includes"
            SubjectsIncludes["subjects/includes/"]:::app
            click SubjectsIncludes "https://github.com/subjectsplus/subjectsplus/tree/master/subjects/includes/"
        end
        subgraph "Theming"
            SubjectsThemes["subjects/themes/"]:::app
            click SubjectsThemes "https://github.com/subjectsplus/subjectsplus/tree/master/subjects/themes/"
        end
        subgraph "Talkback Public"
            TalkbackPublic["subjects/views/talkback/"]:::app
            click TalkbackPublic "https://github.com/subjectsplus/subjectsplus/tree/master/subjects/views/talkback/"
        end
    end
    Index -->|dispatch| SubjectsRoot

    %% Core Business Logic
    subgraph "Core Business Logic"
        ControlLogic["lib/SubjectsPlus/Control/"]:::app
        click ControlLogic "https://github.com/subjectsplus/subjectsplus/tree/master/lib/SubjectsPlus/Control/"
        APILogic["lib/SubjectsPlus/API/"]:::app
        click APILogic "https://github.com/subjectsplus/subjectsplus/tree/master/lib/SubjectsPlus/API/"
    end
    ControlIndex -->|calls| ControlLogic
    SubjectsRoot -->|calls| ControlLogic
    APIFront -->|calls| APILogic
    SubjectsRoot -->|calls| APILogic

    %% Data Layer
    DB[(MySQL Database)]:::infra
    ControlLogic -->|SQL| DB
    APILogic -->|SQL| DB

    %% Static Asset Pipeline
    subgraph "Static Assets"
        Assetic["lib/Assetic/"]:::app
        click Assetic "https://github.com/subjectsplus/subjectsplus/tree/master/lib/Assetic/"
        CKEditor["ckeditor/"]:::app
        click CKEditor "https://github.com/subjectsplus/subjectsplus/tree/master/ckeditor/"
        Select2["assets/js/select2/"]:::app
        click Select2 "https://github.com/subjectsplus/subjectsplus/tree/master/assets/js/select2/"
        jQuery["assets/jquery/"]:::app
        click jQuery "https://github.com/subjectsplus/subjectsplus/tree/master/assets/jquery/"
        FontAwesome["assets/css/font-awesome/"]:::app
        click FontAwesome "https://github.com/subjectsplus/subjectsplus/tree/master/assets/css/font-awesome/"
    end
    SubjectsRoot -->|serves assets| Assetic
    ControlIndex -->|serves assets| Assetic

    %% External Integrations
    subgraph "External Services"
        SMTP["PHPMailer (SMTP)"]:::ext
        click SMTP "https://github.com/subjectsplus/subjectsplus/tree/master/lib/PHPMailer/"
        ReCAPTCHA["Google reCAPTCHA"]:::ext
        click ReCAPTCHA "https://github.com/subjectsplus/subjectsplus/tree/master/lib/ReCaptcha/"
        LTIAddOn["Blackboard LTI Addon"]:::ext
        click LTIAddOn "https://github.com/subjectsplus/subjectsplus/tree/master/addons/bb-lti/"
        OAI["OAI-PMH Feeds & Transforms"]:::ext
        click OAI "https://github.com/subjectsplus/subjectsplus/tree/master/oai/"
    end
    ControlLogic -->|email via SMTP| SMTP
    TalkbackAdmin -->|verify spam| ReCAPTCHA
    SubjectsRoot -->|verify spam| ReCAPTCHA
    LTIController -->|LTI interactions| LTIAddOn
    OAI -->|provide feeds| SubjectsRoot

    %% Legend and Styles
    classDef app fill:#D0E8FF,stroke:#000;
    classDef infra fill:#DFFFD0,stroke:#000;
    classDef ext fill:#FFE4B5,stroke:#000;
```
