pulse-signage/docs/technical/schema.md

Database Schema

This app creates and maintains its schema at startup through src/db/index.js. The sections below summarize the current tables and their purpose.

Tables generally use a numeric auto-increment id primary key. The relationship table d_announcement_screens intentionally uses the composite (announcement_id, screen_id) primary key instead. Natural and relationship keys remain as unique constraints where needed. Timestamps are stored as created_at and modified_at when a table supports auditing.

Admin

• a_users - admin user profiles and app-specific account controls.
• a_roles - named role definitions.
• a_permissions - permission catalog seeded from the application constants.
• a_role_permissions - many-to-many mapping between roles and permissions.
• a_user_roles - many-to-many mapping between users and roles.
• a_sessions - Better Auth session tokens with application View-as metadata.
• a_accounts - Better Auth credentials and linked identity-provider accounts.
• a_verifications - Better Auth email OTP verification and reset challenges.
• a_user_two_factors - Better Auth authenticator secrets, backup codes, and per-user verification lock state.
• a_user_passkeys - Better Auth passkey credentials and authenticator metadata.
• a_login_attempts - Better Auth database-backed rate-limit counters.

a_users

• id, name, username, email, email_verified, image, pending_email, must_change_password, account_locked, created_at, created_by, modified_at, modified_by
• username is unique.
• email is Better Auth's unique, non-null email identity; synthetic addresses are used when the app email is absent.

a_accounts

• id, account_id, provider_id, user_id, access_token, refresh_token, id_token, access_token_expires_at, refresh_token_expires_at, scope, password, created_at, updated_at
• (provider_id, account_id) is unique.
• Credential passwords are stored in password on the credential provider account using Better Auth's native scrypt format; legacy PBKDF2 hashes upgrade after successful sign-in. Password hashes are not stored on a_users.
• Foreign key: - user_id -> a_users.id with ON DELETE CASCADE

a_verifications

• id, identifier, value, expires_at, created_at, updated_at
• Indexed by identifier; Better Auth stores one-time email codes and their expiry here.

a_user_two_factors

• id, user_id, secret, backup_codes, verified, failed_verification_count, locked_until
• user_id is unique; each user has at most one authenticator record.
• Foreign key: user_id -> a_users.id with ON DELETE CASCADE.

a_user_passkeys

• id, name, public_key, user_id, credential_id, counter, device_type, backed_up, transports, created_at, aaguid
• credential_id is unique; user_id is indexed.
• Foreign key: user_id -> a_users.id with ON DELETE CASCADE.

a_login_attempts

• id, rate_key, failed_count, last_request
• rate_key is unique.

a_roles

• id, role_key, name, description, require_two_factor, created_at, created_by, modified_at, modified_by
• role_key is unique.
• name is unique.
• require_two_factor defaults to false; users must enroll when any assigned role requires two-factor authentication.

a_permissions

• id, permission_key, name, section_name, description, created_at, modified_at
• permission_key is unique.

a_role_permissions

• id, role_id, permission_id, created_at, modified_at
• Foreign keys: - role_id -> a_roles.id - permission_id -> a_permissions.id
• Unique key: (role_id, permission_id)

a_user_roles

• id, user_id, role_id, created_at, modified_at
• Foreign keys: - user_id -> a_users.id - role_id -> a_roles.id
• Unique key: (user_id, role_id)

a_sessions

• id, session_hash, user_id, ip_address, user_agent, expires_at, created_at, created_by, last_used_at, modified_by
• session_hash is unique.
• Foreign key: - user_id -> a_users.id

Content

• c_canvas_sizes - reusable canvas presets for templates.
• c_playlists - playlist definitions, playback options, and canvas assignment.
• c_templates - slide templates with canvas and background settings.
• c_template_regions - template region layout and metadata.
• c_slides - slide records with template binding, JSON content, and thumbnail path.
• c_media_assets - reusable uploaded media files referenced by slides and templates.
• c_playlist_slides - ordered playlist items and timing.
• c_playlist_slide_schedule_rules - rule rows attached to playlist slides.

c_canvas_sizes

• id, name, width, height, created_at, created_by, modified_at, modified_by
• (width, height) is unique.

c_playlists

• id, name, fade_between_slides, skip_unavailable_rtmp, canvas_id, created_at, created_by, modified_at, modified_by
• Foreign key: - canvas_id -> c_canvas_sizes.id with ON DELETE SET NULL

c_templates

• id, name, canvas_size_id, background_image_path, background_color, background_gradient, created_at, created_by, modified_at, modified_by
• background_gradient stores normalized linear gradient settings as JSON text, including angle and colour stops.
• Foreign key: - canvas_size_id -> c_canvas_sizes.id with ON DELETE SET NULL

c_template_regions

• id, template_id, region_key, region_type, label, font_family, lock_ratio, animation_json, default_content_json, read_only, x, y, width, height, z_index, created_at, created_by, modified_at, modified_by
• Foreign key: - template_id -> c_templates.id with ON DELETE CASCADE

c_slides

• id, title, template_id, content_json, thumbnail_path, created_at, created_by, modified_at, modified_by
• Foreign key: - template_id -> c_templates.id with ON DELETE SET NULL

c_media_assets

• id, media_path, original_name, media_type, mime_type, file_size, is_published, created_at, created_by, modified_at, modified_by
• media_path is unique.
• Indexed by media_type and created_at.

c_playlist_slides

• id, playlist_id, slide_id, position, duration_seconds, use_video_duration, disable_audio, created_at, created_by, modified_at, modified_by
• Foreign keys: - playlist_id -> c_playlists.id with ON DELETE CASCADE - slide_id -> c_slides.id with ON DELETE CASCADE

c_playlist_slide_schedule_rules

• id, playlist_slide_id, position, start_datetime, end_datetime, start_time, end_time, schedule_days_json, created_at, created_by, modified_at, modified_by

• Foreign key: - playlist_slide_id -> c_playlist_slides.id with ON DELETE CASCADE

• Index: - (playlist_slide_id, position)

• Each playlist slide can have zero or more schedule rules.

• Rules are evaluated with OR across rows and with AND across the fields inside a single rule.

Devices

• d_players - player registry and connection metadata.
• d_screens - screen records and playlist assignment.
• d_onboarding_devices - device-to-screen bindings and onboarded client names.

d_players

• id, identifier, public_base_url, internal_base_url, last_seen_at, created_at, modified_at
• id is the primary key.
• identifier is unique and is the stable player identity used by the app.

d_screens

• id, name, slug, playlist_id, created_at, created_by, modified_at, modified_by

• slug is unique.

• Foreign keys: - playlist_id -> c_playlists.id with ON DELETE SET NULL

• Screens are no longer tied to a player foreign key directly; player registration and live connection metadata are tracked separately in d_players.

d_onboarding_devices

• id, device_id, client_name, screen_id, created_at, created_by, modified_at, modified_by, last_seen_at
• device_id is unique.
• Foreign key: - screen_id -> d_screens.id with ON DELETE SET NULL

Onboarding

• The onboarding flow uses d_onboarding_devices to bind a device to a screen and persist the client name.

Announcements

• d_announcements - announcement content and display metadata.
• d_announcement_screens - announcement-to-screen assignments.

d_announcements

• id, message, short_label, announcement_type, color_key, icon_key, duration_seconds, expires_at, created_at, created_by, modified_at, modified_by
• announcement_type defaults to lower-third.

d_announcement_screens

• announcement_id, screen_id, created_at, created_by, modified_at, modified_by
• Foreign keys: - announcement_id -> d_announcements.id with ON DELETE CASCADE - screen_id -> d_screens.id with ON DELETE CASCADE
• Unique key: (announcement_id, screen_id)

Integrations

• i_rss_feeds - RSS feed definitions and refresh cadence.
• i_rss_feed_items - cached RSS feed items.
• i_api_source_groups - API source names and shared authentication settings.
• i_api_sources - named requests, independent refresh settings, and last response snapshots.
• i_weather_locations - configured weather locations and last response snapshot.
• i_timetable_groups - grouped timetable definitions used by the timetable region.
• i_timetable_entries - dated entries that belong to a timetable group.

i_rss_feeds

• id, name, feed_url, update_interval_value, update_interval_unit, item_limit, enabled, last_pulled_at, created_at, created_by, modified_at, modified_by

i_rss_feed_items

• id, rss_feed_id, position, item_json, created_at, created_by, modified_at, modified_by
• Foreign key: - rss_feed_id -> i_rss_feeds.id with ON DELETE CASCADE
• Unique key: - (rss_feed_id, position)

i_api_source_groups

• id, name, enabled, auth_method, auth_username, auth_password, auth_bearer_token, auth_header_name, auth_header_value, token_url, token_request_body_json, token_response_path, token_refresh_url, token_refresh_request_body_json, token_refresh_response_path, token_header_name, token_header_prefix, created_at, created_by, modified_at, modified_by
• Unique group name; authentication applies to every child request. auth_method = 'none' supports public endpoints. Token caches are keyed by group and authentication configuration.
• enabled is the source-wide refresh gate, added by migration 2.16.2 with a default of 1. Disabling a group leaves child enabled flags unchanged. Refresh lookups combine group/request flags, and queued work checks effective enabled state before making an outbound request.

i_api_sources

• id, auth_source_id, name, api_url, request_method, request_body_json, items_path, update_interval_value, update_interval_unit, enabled, last_pulled_at, last_pull_error, last_response_status, last_response_content_type, last_response_json, created_at, created_by, modified_at, modified_by
• auth_source_id references i_api_source_groups.id with restricted parent deletion. The web application requires at least one request per group and unique request names within each group.
• Request IDs remain the source_id stored in slide regions and the keys used by scheduled refreshes. Removing a request used by a slide is blocked.
• The 2.16.1 migration copies each existing source's authentication into a same-ID parent group and links the original request without changing its ID or response snapshot. Legacy authentication columns remain on request rows for schema compatibility but runtime authentication is loaded from the parent.
• Editor/player request lists exclude authentication credentials. Refreshes resolve current parent authentication at execution time.

i_weather_locations

• id, name, location_label, latitude, longitude, timezone, provider, temperature_unit, wind_unit, precipitation_unit, update_interval_value, update_interval_unit, enabled, last_pulled_at, last_pull_error, last_response_json, created_at, created_by, modified_at, modified_by
• Stores configured weather locations and the most recent provider response used for forecast previews and weather regions.

i_timetable_groups

• id, name, short_description, timezone, created_at, created_by, modified_at, modified_by
• timezone defaults to Europe/London.

i_timetable_entries

• id, schedule_group_id, title, short_description, start_datetime, end_datetime, created_at, created_by, modified_at, modified_by
• Foreign key: - schedule_group_id -> i_timetable_groups.id with ON DELETE CASCADE
• Index: - (schedule_group_id, start_datetime)

Operations

• o_background_tasks - queue and history for background jobs.
• o_app_state - generic app state and version markers stored as key/value pairs.
• o_app_settings - administrator-configurable application settings stored by key.
• o_audit_events - retained audit events for administrator activity and system changes.

o_background_tasks

• id, task_key, task_type, title, category, status, payload_json, metadata_json, attempts, created_at, created_by, started_at, finished_at, error_message
• Indexed by status, task_key, and task_type.

o_app_state

• id, state_key, state_value, created_at, modified_at
• state_key is unique.
• schema_version is stored here so startup can detect the previously recorded schema version before deciding whether migrations need to run.

o_app_settings

• id, setting_key, setting_value, created_at, created_by, modified_at, modified_by
• setting_key is unique.
• Values are stored as JSON and validated against the application setting definitions in src/data/app-settings.js.

o_audit_events

• id, occurred_at, category, event_type, actor_user_id, target_type, target_id, target_label, ip_address, user_agent, details_json
• Indexed by occurrence time, category and event type, actor, and target.

Notes

• The schema is initialized with CREATE TABLE IF NOT EXISTS, so new installs can start from an empty database.
• src/db/bootstrap.js seeds the canvas size defaults, default permissions, and the default administrator role.
• src/db/migrations.js records the current schema version in o_app_state during startup so later launches can tell whether an update is happening.
• The ER diagram shows declared foreign keys and the logical audit actor association; player registry and JSON-based references are intentionally not shown as foreign-key relationships.

erDiagram
        A_USERS {
        }
        A_ROLES {
        }
        A_PERMISSIONS {
        }
        A_ROLE_PERMISSIONS {
        }
        A_USER_ROLES {
        }
        A_SESSIONS {
        }
        A_ACCOUNTS {
        }
        A_VERIFICATIONS {
        }
        A_USER_TWO_FACTORS {
        }
        A_USER_PASSKEYS {
        }
        A_LOGIN_ATTEMPTS {
        }
        C_CANVAS_SIZES {
        }
        C_PLAYLISTS {
        }
        C_TEMPLATES {
        }
        C_TEMPLATE_REGIONS {
        }
        C_SLIDES {
        }
        C_MEDIA_ASSETS {
        }
        C_PLAYLIST_SLIDES {
        }
        C_PLAYLIST_SLIDE_SCHEDULE_RULES {
        }
        D_PLAYERS {
        }
        D_SCREENS {
        }
        D_ONBOARDING_DEVICES {
        }
        D_ANNOUNCEMENTS {
        }
        D_ANNOUNCEMENT_SCREENS {
        }
        I_RSS_FEEDS {
        }
        I_RSS_FEED_ITEMS {
        }
        I_API_SOURCES {
        }
        I_API_SOURCE_GROUPS {
        }
        I_WEATHER_LOCATIONS {
        }
        I_TIMETABLE_GROUPS {
        }
        I_TIMETABLE_ENTRIES {
        }
        O_APP_STATE {
        }
        O_APP_SETTINGS {
        }
        O_BACKGROUND_TASKS {
        }
        O_AUDIT_EVENTS {
        }

        A_USERS ||--o{ A_USER_ROLES : has
        A_ROLES ||--o{ A_USER_ROLES : assigned_to
        A_ROLES ||--o{ A_ROLE_PERMISSIONS : has
        A_PERMISSIONS ||--o{ A_ROLE_PERMISSIONS : granted_to
        A_USERS ||--o{ A_SESSIONS : owns
        A_USERS ||--o{ A_ACCOUNTS : has
        A_USERS ||--o| A_USER_TWO_FACTORS : secures_with
        A_USERS ||--o{ A_USER_PASSKEYS : registers
        A_USERS o|--o{ O_AUDIT_EVENTS : acts
        I_API_SOURCE_GROUPS ||--o{ I_API_SOURCES : contains

        C_CANVAS_SIZES o|--o{ C_TEMPLATES : used_by
        C_CANVAS_SIZES o|--o{ C_PLAYLISTS : used_by
        C_TEMPLATES ||--o{ C_TEMPLATE_REGIONS : contains
        C_TEMPLATES o|--o{ C_SLIDES : used_by
        C_MEDIA_ASSETS }o..o{ C_SLIDES : referenced_by
        C_MEDIA_ASSETS o{..o| C_TEMPLATES : background_for
        C_PLAYLISTS ||--o{ C_PLAYLIST_SLIDES : contains
        C_SLIDES ||--o{ C_PLAYLIST_SLIDES : included_in
        C_PLAYLIST_SLIDES ||--o{ C_PLAYLIST_SLIDE_SCHEDULE_RULES : has_rules

        C_PLAYLISTS o|--o{ D_SCREENS : uses
        D_SCREENS o|--o{ D_ONBOARDING_DEVICES : binds
        D_ANNOUNCEMENTS ||--o{ D_ANNOUNCEMENT_SCREENS : targets
        D_SCREENS ||--o{ D_ANNOUNCEMENT_SCREENS : receives

        I_RSS_FEEDS ||--o{ I_RSS_FEED_ITEMS : caches
        I_TIMETABLE_GROUPS ||--o{ I_TIMETABLE_ENTRIES : contains