Development

Development

Development goals

RoomGoblin should remain classroom-focused, configurable, container-friendly, AI-readable, and safe to deploy without embedding one site's infrastructure into public source.

Read first

AI assistants and contributors should read:

1. AGENTS.md
2. VERSION and CHANGELOG.md
3. docs/AI-CONTEXT.md
4. docs/ROOM-TOPOLOGY.md and docs/ai/ROOM-TOPOLOGY.md before changing TVs, displays, sources, AV routing, classes, automation targets, presentations, media, Morning Announcements, or Music Assistant TV selection
5. the relevant technical documentation
6. implementation source

The direct source tree on main is canonical.

Local workflow

git clone https://github.com/wagnerks1990/RoomGoblin.git
cd RoomGoblin
cp .env.example .env
npm install

Source layout

src/                 main backend, storage, startup recovery
public/controller/   operator/controller interfaces
public/display/      display renderer
maintenance-agent/   maintenance service + extension layer
host-agent/          host-level service and controlled wrapper
config/              generic configuration examples/schema
docs/                canonical technical documentation
wiki/                Git-tracked GitHub Wiki mirror
AGENTS.md             AI/contributor operating contract
.github/              Copilot instructions, CI, image publishing

Standard production conventions

checkout: /opt/classroom-hub
host agent socket: /run/classroom-control-hub/host-agent.sock

Runtime .env, databases, data, uploads, backups, keys, credentials, stream endpoints, managed integration state, and site hardware mappings stay outside Git.

Release discipline

Every release should:

1. update VERSION and package metadata;
2. keep runtime surfaces converged through release stamping/wrappers;
3. search for stale current-baseline version assumptions;
4. run CI-equivalent validation and regression tests;
5. build both Docker images;
6. verify persistent-data/database compatibility;
7. test Host Agent socket access and maintenance startup ordering;
8. test authentication/capability migration behavior;
9. test matrix-only routing, persisted names, stable polling controls and stale topology-save rejection;
10. test managed integration adopt/deploy/recreate behavior;
11. test critical classroom behavior;
12. update CHANGELOG.md, docs/, wiki/, and focused AI context.

Validation

The Security gates workflow performs a full-history Gitleaks scan and blocks pull requests that introduce dependencies with moderate-or-higher known vulnerabilities. Both actions are pinned to full reviewed commit SHAs. The validated-main and tagged-release publication gates require this workflow to pass. Main validation also scans both built runtime images and blocks fixable high/critical vulnerabilities. Dependabot separately monitors the two npm graphs, GitHub Actions, and the Android Agent Gradle build.

Every tracked shell script is syntax checked; adding a new .sh file therefore does not require manually extending a workflow filename list.

The directly downloaded Gradle 9.6.0 distribution is verified against Gradle's published SHA-256 checksum in both Android CI and the maintenance image build. Do not update the distribution or checksum independently.

node --check src/server.js
node --check src/storage.js
node --check src/startup-recovery.js
node --check maintenance-agent/server.js
node --check maintenance-agent/extensions.js
node tools/validate-controller.js
python3 -m py_compile host-agent/server.py host-agent/start.py
npm test
bash -n install.sh
docker compose config
docker build -t classroom-control-hub:test .
docker build -t classroom-control-hub-maintenance:test maintenance-agent

Deployment/recovery invariants

• DATABASE_FILE is authoritative; never silently switch to another existing SQLite file.
• Back up every data/*.db through SQLite .backup before migration.
• Stop the app before active-database canonicalization and validate the destination with PRAGMA quick_check.
• Built-in profiles with missing/empty capabilities are repaired; valid custom capability lists are not overwritten.
• Administrator resolves to capabilities:["*"].
• Password punctuation including ! and # survives setup/login/scrypt paths.
• Maintenance Compose health checks the Host Agent directly instead of waiting on the main application.
• Room topology is retired; the original matrix and receiver stores are authoritative.
• Keep stable IDs, archived topology data, AV mappings, groups and credentials intact.
• Matrix port count remains independent of content-receiver count.
• Existing Docker containers may be discovered/adopted for safe lifecycle operations.
• New container creation remains restricted to supported integration templates.
• Supported optional managed Docker add-ons are Mosquitto, Govee2MQTT, Music Assistant, and Node-RED; Veyon and Veyon WebAPI remain native host services.
• Integration persistent data survives container recreation/removal.
• HTTP remains restricted to a trusted LAN until TLS is deliberately reintroduced.

Priority and scheduling invariants

• Morning Announcements are highest priority.
• Manual and automatic announcement starts use the same priority state.
• Ant Media detection uses HLS as the primary signal when available.
• When announcements end, the scheduler re-evaluates current date/class/time and re-runs the winning current display automations before Background Music resumes.
• Do not restore stale pre-announcement snapshots.
• Timer continuation is only for an explicitly linked continuation of the same base class or period.
• Integration health is independent.
• Slow optional integration probes must not block initial Overview rendering.

Current known-good baseline

1.0.0-alpha.82 is the production-readiness review baseline. A newer VERSION supersedes the version number but not these invariants unless deliberately changed and documented. Alpha.81 freezes and drains writers for a point-in-time encrypted export, snapshots recovery identities consistently, and preserves durable all-state rollback.

Installers copy executable host runners into /usr/local/libexec and must not change tracked source modes in /opt/classroom-hub. A supported update that starts from a clean checkout must leave git status --short empty.

Production updates

The supported production path selects origin/main and requires its exact validated published image pair before changing source or services:

sudo bash /opt/classroom-hub/deploy/update-production.sh

Do not document an unconditional git pull origin main as the normal production update path. The updater verifies both immutable image revisions and refuses silent downgrade or unvalidated substitution. No separate deployment branch advances. Follow Main-based updates for the one-time legacy updater transition.

Testing areas

Regression testing should cover:

• active DB selection with historical alternate database files present;
• administrator/profile recovery and punctuation-heavy passwords;
• controller load/authentication and Overview responsiveness;
• matrix-only layout and TV/source names surviving refresh/reload;
• unmapped output rename without creating receivers, and visible save failures;
• unchanged matrix polls do not replace controls or issue routing commands;
• stale topology saves fail without changing current or archived configuration;
• Docker discovery/adoption and supported add-on lifecycle;
• display connect/reconnect and version convergence;
• scheduled automation and manual Run Now/Test Now;
• class timer resolution, explicit continuation, and transition timers;
• no-school/remote/half-day/delay rules;
• Morning Announcements HLS detection/playback/audio controls;
• announcement priority and post-release failsafe resync;
• Background Music pause/resume/recovery;
• independent MQTT/Govee/Pluto/Veyon/host-agent health;
• Host Agent socket after migration/reinstall;
• persistence across container rebuilds.

Pull requests

Keep changes focused and explain schema migrations, environment variables, persistent paths, security/privilege changes, add-on templates, topology/domain changes, and behavioral invariants. Update the relevant docs in the same change. Topology changes must keep docs/ROOM-TOPOLOGY.md, wiki/Room-Topology.md, and docs/ai/ROOM-TOPOLOGY.md synchronized.

AGP supplies built-in Kotlin support. Do not apply the standalone org.jetbrains.kotlin.android plugin or the removed android.kotlinOptions DSL. Kotlin inherits the Java 17 target from android.compileOptions; preserve that target and the Android SDK/package/signing compatibility settings.

Builds use Android API 37.2 and Build Tools 36.0.0 for AGP 9.4 and OkHttp 5.5. Keep CI and the maintenance APK stage aligned. This changes compile-time APIs only: minSdk = 26, targetSdk = 35, package identity and signing stay unchanged.