Digital Signage Platform

1. Executive Summary

This document defines the requirements, architecture, and implementation strategy for a reliable digital signage platform designed around low-cost Raspberry Pi player devices.

The platform consists of two independent systems:

2. Design Goals

3. System Architecture

The system uses a separated CMS and Player architecture.

4. Deployment Models

Option 1 - Cloud CMS

Administrator
      |
 Internet
      |
 Cloud CMS
      |
 Raspberry Pi Player

Best for multiple locations and remote management.

Option 2 - Local CMS

Laptop
   |
Private WiFi Router
   |
CMS Server
   |
Raspberry Pi Player

Useful when devices cannot access external networks.

Option 3 - Offline Export

CMS

↓

Export Package

↓

USB / Local Transfer

↓

Player

Suitable for isolated installations without network access.

5. Content Management System (CMS)

The CMS is the central administration platform for managing digital signage content, devices, schedules, and publications. It should be designed as a web application accessible from desktop computers, laptops, and tablets.

5.1 CMS Design Principles

5.2 Recommended CMS Technology Stack

Laravel is recommended because it provides a strong balance between performance, hosting availability, security, and long-term maintainability.

5.3 CMS Modules

6. Media Library

The Media Library stores all content assets before they are assigned to playlists or layouts.

6.1 Supported Content Types

6.2 Media Upload Pipeline

6.3 Asset Validation

The CMS should validate uploaded files before publication.

• Allowed file extensions
• Maximum file size
• Image dimensions
• Video codec compatibility
• Audio compatibility
• Checksum generation

7. Publishing Workflow

Digital signage should use a controlled publishing workflow. Directly modifying live screens creates reliability problems.

7.1 Publication States

7.2 Immutable Publications

A published package should never be modified. Any change creates a new version.

Package v100

    manifest.json
    media/
    layouts/

Package v101

    manifest.json
    media/
    layouts/

The player can safely switch between versions without risking corrupted content.

8. Content Package Architecture

The publishing system should generate complete, immutable content packages. Players should never download individual files without knowing exactly which version they belong to.

8.1 Package Structure

package-v105/

    manifest.json

    checksum.json

    media/

        welcome.jpg

        company-video.mp4

        qr-code.png


    layouts/

        lobby-layout.json


    thumbnails/

        welcome-thumb.jpg

8.2 Package Lifecycle

8.3 Rollback Protection

The active package should never be overwritten directly.

storage/

    active/

        package-v105/


    downloads/

        package-v106/

If package-v106 fails validation, the player continues using package-v105.

8.4 Package Manifest Example

{
  "version": 105,

  "hash":
  "7fc8b2f1d8a9",

  "deviceGroup":
  "main-lobby",

  "timezone":
  "America/New_York",

  "defaultPlaylist":
  "lobby-default",

  "files":
  [
    {
      "path":
      "media/welcome.jpg",

      "size":
      245120,

      "hash":
      "ab3345"
    }
  ]
}

9. Device Synchronization

The player should use a pull-based synchronization model. The device periodically contacts the server and checks for updates.

9.1 Pull Architecture

9.2 Synchronization Process

START

 |

Connect to API

 |

Authenticate Device

 |

Send heartbeat

 |

Check latest package version

 |

Package newer?

        |

        +---- No ----> Continue Playback


        |

        Yes


        v


Download Package

        |

Verify Hash

        |

Activate

        |

Resume Playback

9.3 Why Pull Instead of Push?

9.4 Delta Downloads

The synchronization system should avoid downloading files that already exist locally.

Current Package

    image-a.jpg
    video-a.mp4


New Package

    image-a.jpg
    video-a.mp4
    image-b.jpg


Download:

    image-b.jpg only

10. Player Runtime

The Player Runtime is responsible for displaying content, maintaining local storage, synchronizing packages, and recovering automatically from failures.

10.1 Player Components

10.2 Recommended Raspberry Pi Architecture

10.3 Recommended Software Stack

• Operating System: Raspberry Pi OS Lite or lightweight desktop installation
• Renderer: Chromium kiosk mode
• Player Interface: HTML/CSS/JavaScript
• Synchronization: Python service
• Local Storage: SQLite
• Process Management: systemd

11. Player State Machine

The player should use explicit states to simplify debugging and recovery.

11.1 State Definitions

12. Raspberry Pi Player Hardware Profile

The initial target hardware is the Raspberry Pi Zero 2 W. The architecture should remain lightweight while allowing future migration to more powerful devices.

12.1 Recommended Hardware

12.2 Supported Media Limits

13. Offline Playback Requirements

Offline operation is a primary design requirement. Loss of network connectivity should not affect the display.

13.1 Offline Behavior

• All required files are stored locally.
• Schedules execute using local time.
• Previously published content remains available.
• Synchronization retries automatically.
• Default fallback content is always available.

13.2 Failure Scenarios

13.3 Update Safety Process

14. Database Architecture

The CMS should use a relational database. The player should use a lightweight local SQLite database.

14.1 CMS Database Entities

14.2 Core Database Relationship

14.3 Player SQLite Database

device_config

----------------

device_id

server_url

auth_token

timezone



packages

----------------

version

hash

status

activated_at



playback_state

----------------

playlist

item

position



events

----------------

timestamp

level

message

15. Device Management

The CMS should provide complete visibility into every registered player.

15.1 Device Registration

New devices should be registered using a temporary pairing process.

15.2 Device Information

16. Device API Architecture

The Device API provides secure communication between the CMS and deployed players. The player initiates all communication using outbound HTTPS requests.

16.1 API Responsibilities

16.2 Example API Endpoints

POST

/api/v1/device/register


POST

/api/v1/device/heartbeat


GET

/api/v1/device/manifest/latest


GET

/api/v1/package/{version}/download


POST

/api/v1/device/events


GET

/api/v1/device/commands


POST

/api/v1/device/commands/{id}/complete

16.3 Heartbeat Example

{
 "device_id":
 "pi-zero-001",

 "software_version":
 "1.0.5",

 "package":
 "105",

 "playlist":
 "lobby-default",

 "temperature":
 47,

 "storage_free":
 "18GB",

 "uptime":
 "14 days"
}

16.4 Authentication

Each device receives a unique authentication token during pairing.

Device ID

+

Secret Token

+

HTTPS

=

Authenticated Communication

• Tokens should be unique per device.
• Tokens should be revocable.
• Pairing codes should expire quickly.
• Devices should never share credentials.

17. Layout Engine

The layout system controls how content is positioned on the display.

17.1 Layout Types

17.2 Zone Model

Layout

 |

 +-- Zone A

 |      position

 |      size

 |      content source

 |

 +-- Zone B

        position

        size

        content source

17.3 Zone Properties

• X and Y position
• Width and height
• Background color
• Opacity
• Layer order
• Content assignment
• Transition settings

18. Playlist Engine

A playlist defines the order and playback behavior of content.

18.1 Playlist Structure

Playlist

    Name

    Items

        Item 1

            Media

            Duration

            Transition


        Item 2

            Media

            Duration

            Transition


    Loop Mode

18.2 Playlist Options

18.3 Example Playlist

Lobby Information


1.

Welcome Screen

10 seconds


2.

Company Video

45 seconds


3.

Safety Announcement

20 seconds


4.

QR Information

15 seconds

19. Scheduling Engine

Scheduling determines which content should be displayed at any given time.

19.1 Schedule Properties

• Start date
• End date
• Start time
• End time
• Days of week
• Timezone
• Device group
• Priority

19.2 Schedule Conflict Resolution

The scheduler should always select the highest priority active schedule.

19.3 Example Schedule

Weekdays

08:00 - 12:00

Morning Information


12:00 - 14:00

Lunch Menu


14:00 - 17:00

Afternoon Promotion


December 1-25

Holiday Campaign

20. Security Architecture

Security is required for both cloud and local deployments. Digital signage devices should be treated as managed network appliances.

20.1 Security Principles

20.2 User Roles

20.3 File Upload Security

• Validate file extension.
• Validate MIME type.
• Reject executable files.
• Limit upload size.
• Generate safe filenames.
• Store files outside executable directories.
• Scan files where required.

20.4 HTML and Web Content Security

External websites and custom HTML content can introduce security and reliability problems.

The CMS should provide:

• Approved domain allowlists.
• Sandboxed browser execution.
• Disabled external navigation.
• Content sanitization.

21. Performance Requirements

21.1 Player Performance

21.2 CMS Performance

• Normal pages should load within three seconds.
• Media processing should run asynchronously.
• Large uploads should not block the interface.
• Database queries should be indexed.

22. Reliability Requirements

Digital signage systems often operate continuously for months or years. Reliability is therefore a primary design objective.

22.1 Watchdog Design

23. Deployment Architecture

23.1 Small Deployment

Shared Hosting

    |

Laravel CMS

    |

MariaDB

    |

Raspberry Pi Players

23.2 Production Deployment

NGINX

  |

Laravel Application

  |

PostgreSQL

  |

Redis Queue

  |

Object Storage

  |

Device API

23.3 Player Deployment

Raspberry Pi OS

        |

        +-- Chromium Kiosk

        |

        +-- Python Sync Service

        |

        +-- SQLite

        |

        +-- systemd

24. Testing Strategy

24.1 CMS Testing

• Authentication tests.
• Permission tests.
• Upload validation tests.
• Publishing workflow tests.
• Scheduling tests.
• API integration tests.

24.2 Player Testing

• Power loss recovery.
• Network disconnect testing.
• Failed download testing.
• Storage full testing.
• Video playback testing.
• Long-running stability testing.

24.3 Field Testing

Before production deployment, test devices should operate continuously for several weeks under realistic conditions.

25. Development Roadmap

Phase 1 - MVP

Phase 2 - Advanced Management

• Scheduling.
• Layouts.
• Text widgets.
• Clock/date.
• QR codes.
• Device groups.
• Rollback.

Phase 3 - Enterprise Features

• Emergency alerts.
• Weather widgets.
• RSS feeds.
• Screenshots.
• Remote reboot.
• Approval workflows.
• Multiple organizations.

26. Final Architecture Recommendation

The recommended implementation combines a lightweight, reliable player with a flexible web-based CMS.

This architecture provides a practical path from a small single-screen installation to a scalable digital signage platform supporting hundreds of managed devices.

Appendix A - Example Project Structure

A recommended implementation separates the CMS, API, and player components.

CMS Project

digital-signage-cms/

├── app/

│   ├── Models/

│   ├── Controllers/

│   ├── Services/

│   └── Jobs/


├── database/

│   ├── migrations/

│   └── seeders/


├── storage/

│   ├── media/

│   ├── packages/

│   └── thumbnails/


├── routes/

│   ├── web.php

│   └── api.php


└── resources/

    ├── views/

    └── js/

Player Project

digital-signage-player/


├── player/

│   ├── index.html

│   ├── css/

│   └── js/


├── sync/

│   ├── sync.py

│   └── package_manager.py


├── database/

│   └── player.sqlite


├── storage/

│   ├── active/

│   └── downloads/


├── logs/


└── systemd/

    ├── player.service

    └── sync.service

Appendix B - API Examples

Device Heartbeat

POST /api/v1/device/heartbeat


{
 "device_id":
 "lobby-screen-01",

 "version":
 "1.0.5",

 "package":
 "105",

 "status":
 "playing",

 "temperature":
 46,

 "storage":
 {
   "total":"32GB",
   "free":"18GB"
 },

 "timestamp":
 "2026-08-02T15:00:00Z"
}

Manifest Response

GET /api/v1/device/manifest/latest


{
 "package":
 "106",

 "hash":
 "a83bc91",

 "download":
 "/packages/106.zip",

 "size":
 52428800
}

Device Event

POST /api/v1/device/events


{
 "type":
 "VIDEO_ERROR",

 "severity":
 "warning",

 "message":
 "Unable to decode media file",

 "timestamp":
 "2026-08-02T15:10:00Z"
}

Appendix C - Operational Recommendations

Appendix D - Glossary