# xibosignage/xibo-cms architecture

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

- Interactive diagram: https://gitdiagram.com/xibosignage/xibo-cms
- Repository: https://github.com/xibosignage/xibo-cms

## Overview

#### Purpose and entry points
Xibo CMS manages a digital-signage network: content, layouts/playlists/campaigns, scheduling, displays, player communication, administration, and reporting. HTTP entry points are `web/index.php`, `web/api/index.php`, `web/xmds.php`, and preview/PWA endpoints under `web/preview/index.php` and `web/pwa/index.php`. Route partitions are defined in `lib/routes.php`, `lib/routes-react.php`, `lib/routes-spa.php`, and `lib/routes-web.php`.

#### Web application boundary
The PHP application exposes browser/API controllers and applies cross-cutting middleware for authentication, authorization, state, storage, logging, CSP/CSRF, and feature gating. Controllers map domain operations such as displays, layouts, media, schedules, and reports to factories/entities/services. Key paths: `lib/Controller/Base.php`, `lib/Middleware/ApiAuthentication.php`, `lib/Middleware/ApiAuthorization.php`, `lib/Entity/EntityTrait.php`, `lib/Factory/BaseFactory.php`.

#### React management UI
The primary modern UI is a TypeScript React SPA, bootstrapped by `frontend/src/main.tsx`, rooted at `frontend/src/app/App.tsx`, and routed through `frontend/src/routes/index.tsx`. It has a separate login bundle at `frontend/src/login/main.tsx`. Pages call typed service clients, which form the frontend/backend contract; session and permission state gate routes and navigation. Key paths: `frontend/src/lib/api.ts`, `frontend/src/services/displaysApi.ts`, `frontend/src/components/layout/ProtectedRoute.tsx`.

#### Content design and library pipeline
Media, datasets, playlists, layouts/templates, and campaigns are the content model used to construct playback material. Layout design includes an editor host; legacy/editor-specific JavaScript remains separately bundled under `ui/`. Widget/module definitions are declarative XML plus rendering assets, with PHP providers/renderers supplying data and HTML. Key paths: `frontend/src/pages/Design/Layouts/LayoutEditorHost.tsx`, `frontend/src/pages/Library/Media/Media.tsx`, `modules/canvas.xml`, `lib/Widget/Render/WidgetHtmlRenderer.php`.

#### Scheduling and display control
Scheduling binds content/campaigns/layouts to displays or display groups, with dayparts, recurrence, criteria, and sync groups. The React calendar/event UI persists schedule entities through backend APIs. Display-management actions—including commands, screenshots, collection, layouts, and webhooks—are converted into XMR player actions/notifications. Key paths: `frontend/src/pages/Schedule/Schedule/Events.tsx`, `lib/Controller/Schedule.php`, `lib/XMR/PlayerAction.php`, `lib/Service/PlayerActionService.php`.

#### Player synchronization and external integrations
Players communicate with CMS through the XMDS SOAP endpoint and versioned SOAP implementations; this transfers registration/status, schedules, dependencies, logs, and statistics. Connectors integrate external content/data sources (weather, finance, dashboard, exchange, SSP), and HTTP safety includes SSRF protection. OAuth application entities/repositories support external application authorization. Key paths: `lib/Xmds/Soap.php`, `lib/Xmds/Soap7.php`, `lib/Connector/ConnectorInterface.php`, `lib/Helper/Guzzle/SsrfProtectionMiddleware.php`, `lib/OAuth/AccessTokenRepository.php`.

#### Persistence, asynchronous work, and reporting
The system uses database migrations for its large relational domain and supports MySQL plus optional MongoDB time-series storage for statistics. Configured tasks execute maintenance, media/image processing, remote dataset fetches, scheduler work, report delivery, and statistics archival. Reports read operational/statistical data and render report definitions/templates. Key paths: `db/migrations/20180130073838_install_migration.php`, `lib/Storage/MySqlTimeSeriesStore.php`, `lib/Storage/MongoDbTimeSeriesStore.php`, `lib/XTR/TaskInterface.php`, `lib/Report/ProofOfPlay.php`.

#### Runtime and deployment
The supported development/deployment model is Docker Compose with Apache/PHP web containers, Composer PHP dependencies, and Node-based frontend builds. Docker initialization generates API RSA/encryption material in library storage; persistent upload/cache/library locations are operational boundaries. CI builds containers and validates PRs. Key paths: `docker-compose.yml`, `Dockerfile`, `docker/entrypoint.sh`, `docker/etc/apache2/sites-available/000-default.conf`, `.github/workflows/build-container.yaml`.

Main entry points: [`lib/Factory/BaseFactory.php`](https://github.com/xibosignage/xibo-cms/blob/develop/lib/Factory/BaseFactory.php) (Content and scheduling domain), [`frontend/src/app/App.tsx`](https://github.com/xibosignage/xibo-cms/blob/develop/frontend/src/app/App.tsx) (React management SPA), [`lib/Controller/Base.php`](https://github.com/xibosignage/xibo-cms/blob/develop/lib/Controller/Base.php) (Domain controllers), [`lib/Xmds/Soap.php`](https://github.com/xibosignage/xibo-cms/blob/develop/lib/Xmds/Soap.php) (XMDS SOAP service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Management UI"]
  node_browser(("Administrators<br/>browser users"))
  node_react["React management SPA<br/>TypeScript React<br/>[App.tsx]"]
  node_frontend_routes["SPA routes<br/>route layer<br/>[index.tsx]"]
  node_api_clients["Typed API clients<br/>frontend services<br/>[displaysApi.ts]"]
  node_layout_editor["Layout editor<br/>design UI"]
end

subgraph group_app["CMS Application"]
  node_web_entrypoints{{"HTTP entry points<br/>PHP web/API/XMDS<br/>[index.php]"}}
  node_routes["Route partitions<br/>PHP routes<br/>[routes.php]"]
  node_middleware["Security middleware<br/>auth and policy"]
  node_controllers["Domain controllers<br/>PHP controllers<br/>[Base.php]"]
  node_domain["Content and scheduling domain<br/>entities, factories, services<br/>[BaseFactory.php]"]
  node_widgets["Widget rendering<br/>module renderer"]
end

subgraph group_integration["Players &amp; Integrations"]
  node_xmds{{"XMDS SOAP service<br/>player synchronization<br/>[Soap.php]"}}
  node_player_actions["Player actions<br/>XMR notifications"]
  node_connectors["External connectors<br/>content/data integrations"]
  node_oauth["OAuth authorization<br/>token repository"]
end

subgraph group_data["Data &amp; Operations"]
  node_relational_db[("Relational domain database<br/>MySQL")]
  node_timeseries[("Statistics time series<br/>MySQL or MongoDB store")]
  node_tasks["Background tasks<br/>XTR task runtime<br/>[TaskInterface.php]"]
  node_reports["Reporting<br/>report definitions<br/>[ProofOfPlay.php]"]
  node_runtime["Docker runtime<br/>Apache/PHP and build environment<br/>[docker-compose.yml]"]
end

node_browser -->|"uses"| node_react
node_react -->|"routes through"| node_frontend_routes
node_frontend_routes -->|"opens"| node_layout_editor
node_react -->|"calls"| node_api_clients
node_api_clients -->|"HTTP API"| node_web_entrypoints
node_web_entrypoints -->|"dispatches"| node_routes
node_routes -->|"applies"| node_middleware
node_middleware -->|"guards"| node_controllers
node_controllers -->|"operates on"| node_domain
node_layout_editor -->|"edits layouts"| node_domain
node_domain -->|"renders modules"| node_widgets
node_domain -->|"persists"| node_relational_db
node_controllers -->|"issues commands"| node_player_actions
node_player_actions -->|"notifies players"| node_xmds
node_xmds -->|"syncs schedules and status"| node_domain
node_xmds -->|"writes telemetry"| node_timeseries
node_domain -->|"uses external data"| node_connectors
node_oauth -->|"stores tokens"| node_relational_db
node_tasks -->|"maintains and processes"| node_domain
node_tasks -->|"archives statistics"| node_timeseries
node_reports -->|"reads operational data"| node_relational_db
node_reports -->|"reads statistics"| node_timeseries
node_runtime -->|"hosts"| node_web_entrypoints
node_runtime -->|"runs"| node_tasks

click node_react "https://github.com/xibosignage/xibo-cms/blob/develop/frontend/src/app/App.tsx"
click node_frontend_routes "https://github.com/xibosignage/xibo-cms/blob/develop/frontend/src/routes/index.tsx"
click node_api_clients "https://github.com/xibosignage/xibo-cms/blob/develop/frontend/src/services/displaysApi.ts"
click node_layout_editor "https://github.com/xibosignage/xibo-cms/blob/develop/frontend/src/pages/Design/Layouts/LayoutEditorHost.tsx"
click node_web_entrypoints "https://github.com/xibosignage/xibo-cms/blob/develop/web/index.php"
click node_routes "https://github.com/xibosignage/xibo-cms/blob/develop/lib/routes.php"
click node_middleware "https://github.com/xibosignage/xibo-cms/blob/develop/lib/Middleware/ApiAuthentication.php"
click node_controllers "https://github.com/xibosignage/xibo-cms/blob/develop/lib/Controller/Base.php"
click node_domain "https://github.com/xibosignage/xibo-cms/blob/develop/lib/Factory/BaseFactory.php"
click node_widgets "https://github.com/xibosignage/xibo-cms/blob/develop/lib/Widget/Render/WidgetHtmlRenderer.php"
click node_xmds "https://github.com/xibosignage/xibo-cms/blob/develop/lib/Xmds/Soap.php"
click node_player_actions "https://github.com/xibosignage/xibo-cms/blob/develop/lib/Service/PlayerActionService.php"
click node_connectors "https://github.com/xibosignage/xibo-cms/blob/develop/lib/Connector/ConnectorInterface.php"
click node_oauth "https://github.com/xibosignage/xibo-cms/blob/develop/lib/OAuth/AccessTokenRepository.php"
click node_relational_db "https://github.com/xibosignage/xibo-cms/blob/develop/db/migrations/20180130073838_install_migration.php"
click node_timeseries "https://github.com/xibosignage/xibo-cms/blob/develop/lib/Storage/MySqlTimeSeriesStore.php"
click node_tasks "https://github.com/xibosignage/xibo-cms/blob/develop/lib/XTR/TaskInterface.php"
click node_reports "https://github.com/xibosignage/xibo-cms/blob/develop/lib/Report/ProofOfPlay.php"
click node_runtime "https://github.com/xibosignage/xibo-cms/blob/develop/docker-compose.yml"

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_browser,node_react,node_frontend_routes,node_api_clients,node_layout_editor toneBlue
class node_web_entrypoints,node_routes,node_middleware,node_controllers,node_domain,node_widgets toneAmber
class node_xmds,node_player_actions,node_connectors,node_oauth toneMint
class node_relational_db,node_timeseries,node_tasks,node_reports,node_runtime toneRose
```

## Components

### Management UI

- **Administrators**: browser users
- [React management SPA](https://github.com/xibosignage/xibo-cms/blob/develop/frontend/src/app/App.tsx): TypeScript React · Protected routes use session and permission state. · `frontend/src/app/App.tsx`
- [SPA routes](https://github.com/xibosignage/xibo-cms/blob/develop/frontend/src/routes/index.tsx): route layer · `frontend/src/routes/index.tsx`
- [Typed API clients](https://github.com/xibosignage/xibo-cms/blob/develop/frontend/src/services/displaysApi.ts): frontend services · `frontend/src/services/displaysApi.ts`
- [Layout editor](https://github.com/xibosignage/xibo-cms/blob/develop/frontend/src/pages/Design/Layouts/LayoutEditorHost.tsx): design UI · `frontend/src/pages/Design/Layouts/LayoutEditorHost.tsx`

### CMS Application

- [HTTP entry points](https://github.com/xibosignage/xibo-cms/blob/develop/web/index.php): PHP web/API/XMDS · Serves browser, API, player, preview, and PWA endpoints. · `web/index.php`
- [Route partitions](https://github.com/xibosignage/xibo-cms/blob/develop/lib/routes.php): PHP routes · `lib/routes.php`
- [Security middleware](https://github.com/xibosignage/xibo-cms/blob/develop/lib/Middleware/ApiAuthentication.php): auth and policy · Applies authentication, authorization, CSRF/CSP, storage, logging, and feature gates. · `lib/Middleware/ApiAuthentication.php`
- [Domain controllers](https://github.com/xibosignage/xibo-cms/blob/develop/lib/Controller/Base.php): PHP controllers · `lib/Controller/Base.php`
- [Content and scheduling domain](https://github.com/xibosignage/xibo-cms/blob/develop/lib/Factory/BaseFactory.php): entities, factories, services · Manages media, datasets, playlists, layouts, campaigns, schedules, and displays. · `lib/Factory/BaseFactory.php`
- [Widget rendering](https://github.com/xibosignage/xibo-cms/blob/develop/lib/Widget/Render/WidgetHtmlRenderer.php): module renderer · Declarative modules are rendered through PHP providers and HTML renderers. · `lib/Widget/Render/WidgetHtmlRenderer.php`

### Players & Integrations

- [XMDS SOAP service](https://github.com/xibosignage/xibo-cms/blob/develop/lib/Xmds/Soap.php): player synchronization · Versioned SOAP transfers registration, status, schedules, dependencies, logs, and statistics. · `lib/Xmds/Soap.php`
- [Player actions](https://github.com/xibosignage/xibo-cms/blob/develop/lib/Service/PlayerActionService.php): XMR notifications · Converts display commands and events into player actions. · `lib/Service/PlayerActionService.php`
- [External connectors](https://github.com/xibosignage/xibo-cms/blob/develop/lib/Connector/ConnectorInterface.php): content/data integrations · Connects weather, finance, dashboards, exchange, SSP, and other sources. · `lib/Connector/ConnectorInterface.php`
- [OAuth authorization](https://github.com/xibosignage/xibo-cms/blob/develop/lib/OAuth/AccessTokenRepository.php): token repository · `lib/OAuth/AccessTokenRepository.php`

### Data & Operations

- [Relational domain database](https://github.com/xibosignage/xibo-cms/blob/develop/db/migrations/20180130073838_install_migration.php): MySQL · Schema is established and evolved through migrations. · `db/migrations/20180130073838_install_migration.php`
- [Statistics time series](https://github.com/xibosignage/xibo-cms/blob/develop/lib/Storage/MySqlTimeSeriesStore.php): MySQL or MongoDB store · MongoDB is an optional statistics backend. · `lib/Storage/MySqlTimeSeriesStore.php`
- [Background tasks](https://github.com/xibosignage/xibo-cms/blob/develop/lib/XTR/TaskInterface.php): XTR task runtime · Runs maintenance, processing, fetch, scheduler, delivery, and archival work. · `lib/XTR/TaskInterface.php`
- [Reporting](https://github.com/xibosignage/xibo-cms/blob/develop/lib/Report/ProofOfPlay.php): report definitions · Reads operational and statistical data for rendered reports. · `lib/Report/ProofOfPlay.php`
- [Docker runtime](https://github.com/xibosignage/xibo-cms/blob/develop/docker-compose.yml): Apache/PHP and build environment · Compose deployment initializes keys and persistent library, upload, and cache storage. · `docker-compose.yml`

## Connections

- Administrators → React management SPA: uses
- React management SPA → SPA routes: routes through
- SPA routes → Layout editor: opens
- React management SPA → Typed API clients: calls
- Typed API clients → HTTP entry points: HTTP API
- HTTP entry points → Route partitions: dispatches
- Route partitions → Security middleware: applies
- Security middleware → Domain controllers: guards
- Domain controllers → Content and scheduling domain: operates on
- Layout editor → Content and scheduling domain: edits layouts
- Content and scheduling domain → Widget rendering: renders modules
- Content and scheduling domain → Relational domain database: persists
- Domain controllers → Player actions: issues commands
- Player actions → XMDS SOAP service: notifies players
- XMDS SOAP service → Content and scheduling domain: syncs schedules and status
- XMDS SOAP service → Statistics time series: writes telemetry
- Content and scheduling domain → External connectors: uses external data
- OAuth authorization → Relational domain database: stores tokens
- Background tasks → Content and scheduling domain: maintains and processes
- Background tasks → Statistics time series: archives statistics
- Reporting → Relational domain database: reads operational data
- Reporting → Statistics time series: reads statistics
- Docker runtime → HTTP entry points: hosts
- Docker runtime → Background tasks: runs