# pkp/ojs architecture

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

- Interactive diagram: https://gitdiagram.com/pkp/ojs
- Repository: https://github.com/pkp/ojs

## Overview

##### Main Components
a. Frontend / Presentation Layer:
- “public”, “templates”, “pages”, and “styles” directories as elements of the UI layer.
- Entry point (index.php) and template rendering (located under templates/controllers, templates/frontend, etc.) to show how the application renders content.
b. Business Logic and Core Modules:
- Benchmark the “classes” directory (with subdirectories such as core, article, issue, submission, payment, etc.) as the central business logic and data models.
- “classes/core” (containing Application, Request, Services, and PageRouter) as the central orchestration engine.
c. Controllers and Routing:
- “controllers” and “pages” directories, which route HTTP requests to the proper handler.
- How web requests go from the public entry point to controllers and then hand off to pages or core services.
d. API Layer:
- “api” directory (with a versioned structure such as api/v1) as providing RESTful endpoints for external clients.
e. Plugin and Extension System:
- “plugins” directory that houses numerous submodules (blocks, generic, pubIds, themes, paymethods, importexport, etc.), supporting extensibility.
f. Background Jobs and Schedulers:
- “jobs” directory (and related classes in “classes/scheduler”, “classes/tasks”) to represent the asynchronous processing engine.
- That these jobs handle notifications, statistics compilation, notifications to external services (like ORCID), etc.
g. Localization, Configuration, and Other Assets:
- Acknowledge directories for “locale”, “docs”, “configs”, “schemas”, and “registry”. These form the ancillary but essential parts of the system.
- Use small iconography or annotations to denote configuration, documentation, and schema management.

##### Relationships and Data Flow
a. A typical HTTP client (web browser) making requests to the front controller (index.php) in “public” which routes to “controllers” and then “pages”.
c. API calls (from clients or third-party integrations) interacting with the “api” endpoints that, in turn, delegate to core business logic.

##### Architectural Patterns and Design Principles
a. MVC Pattern:
- The structure suggests an MVC-like separation, with “pages” and “controllers” handling the request and view logic, “classes” managing business logic and data access, and “templates” rendering output.
b. Modular / Plugin-oriented Architecture:
- That many OJS functions are implemented via plugins for flexibility. Use a separate “Plugin” block that links into the core system.
c. Layered Architecture:
- A layered approach where presentation, application logic, data access, and integration modules interact through well-defined interfaces.
d. Versioning and API Abstraction:
- Point out how the “api/v1” directory ensures that the API is versioned and decoupled from the underlying business logic.

##### Technologies and Frameworks
a. That while OJS is built in PHP, it makes extensive use of PHP classes and DAO patterns (distributed in “classes/” directories).
b. Frontend technologies – LESS files under “styles” and “plugins/themes/default/styles” indicate client-side styling.
c. External integrations are handled via gateway and importexport plugins, so mention formats like XML, JSON, and possible external API endpoints (ORCID, Crossref, etc.).

a. A high-level view that shows how the web client interacts with the application.
b. Break down into subsystems: UI, API, core business logic, persistence (which, while not explicitly shown in the file tree, is assumed), plugin architecture, and job scheduling.
c. A section for configuration & localization that integrates with the overall system.
d. Annotations where necessary to explain the purpose of specific modules (for example, noting that “classes/migration” handles database upgrades).

## Diagram (Mermaid)

```mermaid
graph TD
    Client["Web Client"]:::client

    subgraph "Presentation Layer"
        pub["public (index.php)"]:::frontend
        temp["templates"]:::frontend
        stl["styles"]:::frontend
    end

    subgraph "Controllers & Routing"
        ctrl["controllers"]:::controllers
        pgs["pages"]:::controllers
    end

    subgraph "Business Logic & Core Modules"
        cls["classes"]:::business
        app["Application.php"]:::business
        router["PageRouter.php"]:::business
    end

    subgraph "API Layer"
        api["api/v1"]:::api
        backendDoi["BackendDoiController.php"]:::api
    end

    subgraph "Plugin System"
        plugins["plugins"]:::plugins
        developedBy["DevelopedByBlockPlugin.php"]:::plugins
    end

    subgraph "Job Scheduling"
        jobs["jobs"]:::jobs
        scheduler["classes/scheduler"]:::jobs
        tasks["classes/tasks"]:::jobs
    end

    subgraph "Assets & Configuration"
        locale["locale"]:::assets
        docs["docs"]:::assets
        schemas["schemas"]:::assets
        registry["registry"]:::assets
        emailTemplates["emailTemplates.xml"]:::assets
    end

    %% Data Flow Connections
    Client --> pub
    pub --> ctrl
    ctrl --> pgs
    pgs --> temp

    %% Controllers interacting with Business Logic
    ctrl -->|"calls"| cls
    pgs -->|"calls"| cls

    %% Core modules within Business Logic (internal orchestration)
    cls --- app
    cls --- router

    %% API delegation to Business Logic
    backendDoi -->|"delegates"| cls

    %% Plugins hooking into Business Logic
    developedBy -->|"hooks"| cls

    %% Background Jobs interacting with Business Logic
    jobs -->|"triggers"| cls
    scheduler -->|"schedules"| cls
    tasks -->|"executes"| cls

    %% Configuration and Assets input to Business Logic
    registry -->|"configures"| cls
    schemas -->|"defines"| cls
    docs -->|"documents"| cls
    locale -->|"localizes"| cls

    %% API module as part of API Layer
    api --> backendDoi

    %% Plugin System as part of Plugin Layer
    plugins --> developedBy

    %% Click Events for Component Mapping
    click pub "https://github.com/pkp/ojs/blob/main/public/index.html"
    click pgs "https://github.com/pkp/ojs/blob/main/pages/index/index.php"
    click app "https://github.com/pkp/ojs/blob/main/classes/core/Application.php"
    click router "https://github.com/pkp/ojs/blob/main/classes/core/PageRouter.php"
    click ctrl "https://github.com/pkp/ojs/blob/main/controllers/api/file/ManageFileApiHandler.php"
    click backendDoi "https://github.com/pkp/ojs/blob/main/api/v1/_dois/BackendDoiController.php"
    click developedBy "https://github.com/pkp/ojs/blob/main/plugins/blocks/developedBy/DevelopedByBlockPlugin.php"
    click jobs "https://github.com/pkp/ojs/blob/main/jobs/notifications/IssuePublishedNotifyUsers.php"
    click scheduler "https://github.com/pkp/ojs/blob/main/classes/scheduler/Scheduler.php"
    click emailTemplates "https://github.com/pkp/ojs/blob/main/registry/emailTemplates.xml"
    click schemas "https://github.com/pkp/ojs/blob/main/schemas/issue.json"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef controllers fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef business fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef api fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef plugins fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef jobs fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef assets fill:#fdfd96,stroke:#f1c232,stroke-width:2px;
    classDef client fill:#cfe2f3,stroke:#3c78d8,stroke-width:2px;
```
