hotel_pi/CMS_CONFIG.md

Kiosk Configuration System

Overview

The kiosk uses a CMS-managed configuration system via Directus. Settings are stored in the settings collection and can be managed through the Directus admin interface without needing to change environment variables.

Configuration Fields

Core Settings

Field	Type	Default	Description
key	String	general	Unique identifier for this settings group (should always be "general")
title	String	Guest	Welcome title displayed in idle/home screens
use_ip_location	Boolean	false	If true, uses IP geolocation; if false, uses manual location
manual_location	String	``	Manual location string (e.g., "Disneyland, Anaheim, CA")
idle_timeout_seconds	Integer	300	Seconds before returning to idle screen
plex_enabled	Boolean	true	Enable/disable Plex integration
restaurants_enabled	Boolean	true	Show/hide restaurants section
attractions_enabled	Boolean	true	Show/hide attractions section
brand_color	String	#1f2937	Primary brand color (hex)
metadata	JSON	{}	Extensible JSON for custom settings

Setup Instructions

1. Create the Settings Collection in Directus

Access Directus admin at http://localhost:8055 and:

1. Create a new collection called settings
2. Add the fields listed above with their types
3. Create the initial record with key: "general"

Alternatively, if using Directus auto-migrations, the schema should be applied automatically.

2. Seed Initial Configuration

Insert the default settings into the database:

INSERT INTO directus_collections.settings (id, key, title, use_ip_location, manual_location, idle_timeout_seconds, plex_enabled, restaurants_enabled, attractions_enabled, brand_color)
VALUES (
  gen_random_uuid(),
  'general',
  'Guest',
  false,
  'Your Hotel Location',
  300,
  true,
  true,
  true,
  '#1f2937'
);

3. Frontend Integration

Option A: Using Config Store (Recommended)

In your Svelte components:

<script>
  import { config, welcomeTitle, location, configLoading, initConfig } from '$lib/configStore.js';
  import { onMount } from 'svelte';

  onMount(() => {
    initConfig();
  });
</script>

{#if $configLoading}
  <p>Loading configuration...</p>
{:else}
  <h1>Welcome, {$welcomeTitle}!</h1>
  <p>Location: {$location}</p>
{/if}

Option B: Using Config Module Directly

import { fetchConfig, getLocation } from '$lib/config.js';

const config = await fetchConfig();
console.log('Welcome title:', config.title);

const location = await getLocation();
console.log('Location:', location);

Location Options

Using IP Geolocation

// In Directus, set:
// use_ip_location: true
// manual_location: "" (can be empty)

// The system will use ipapi.co to determine location
// Returns format: "City, Region, Country"

Using Manual Location

// In Directus, set:
// use_ip_location: false
// manual_location: "Disneyland, Anaheim, CA"

// Returns exactly what you set in manual_location

Updating App.svelte

Replace environment variable usage with config store:

Before:

const welcomeName = import.meta.env.VITE_WELCOME_NAME || 'Guest';
const IDLE_TIMEOUT = (import.meta.env.VITE_IDLE_TIMEOUT || 5) * 60 * 1000;

After:

import { welcomeTitle, idleTimeoutMs, initConfig } from './lib/configStore.js';
import { onMount } from 'svelte';

onMount(() => {
  initConfig();
});

let welcomeName = 'Guest';
let IDLE_TIMEOUT = 300000;

welcomeTitle.subscribe(val => welcomeName = val);
idleTimeoutMs.subscribe(val => IDLE_TIMEOUT = val);

Caching

The config is cached for 5 minutes to reduce database queries. To force a refresh:

import { refreshConfig } from '$lib/configStore.js';

await refreshConfig();

Extending Configuration

To add custom settings without modifying the schema, use the metadata field:

In Directus:

{
  "customFeature": true,
  "apiKey": "abc123",
  "theme": "dark"
}

In JavaScript:

const config = await fetchConfig();
const customFeature = config.metadata.customFeature;

API Endpoints

The config module doesn't require backend changes—it queries Directus directly:

GET /items/settings?filter={"key":"general"}

Response format:

{
  "data": [
    {
      "id": "uuid",
      "key": "general",
      "title": "Guest",
      "use_ip_location": false,
      "manual_location": "Disneyland, Anaheim, CA",
      ...
    }
  ]
}

Environment Variables

No environment variables needed! Everything is managed via Directus. However, you still need:

• VITE_API_URL: Points to Directus instance (default: http://localhost:8055)

Troubleshooting

Config not loading

• Check Directus is running and accessible
• Verify settings collection exists with key: "general" record
• Check browser console for errors

Location not updating

• If using IP geolocation, check ipapi.co is accessible
• If using manual location, verify use_ip_location: false and manual_location is set

Stale config after updates

• Config is cached for 5 minutes
• Force refresh with refreshConfig() or wait for cache to expire