Concepts
These pages explain how GEM works — the mental model behind the system. They complement the Admin Reference (what each screen does) and the Guides (how to accomplish a task).
Architecture
GEM is a single Node.js server that owns every device connection and all automation, with thin clients connecting to it over REST and WebSocket. This page describes the moving parts.
Data Model
GEM's configuration is a handful of entity types that reference each other. Understanding how they relate makes the admin interface — and the API — much easier to navigate.
Attributes & the Registry
Attributes are how GEM stores nearly everything that varies per entity. A single mechanism carries both configuration (a device's IP address, a zone's relay mapping) and live runtime state (current brightness, temperature, online status).
Role-Based Access Control
GEM controls who can do what through roles. A user holds one or more roles; permissions are additive — the user gets the union of every role's grants. (The guide Create a Role covers the day-to-day mechanics; this page explains the model.)
Secure Attributes
Sensitive attribute values — passwords, API keys, private keys — are encrypted at rest using AES-256-GCM. Encryption and decryption are transparent: the rest of the system reads and writes these attributes normally and never sees ciphertext.
Relay Semantics
Relay-driven hardware (gates, garage doors, locks, lighting contactors) reports and accepts a raw contact state — open or closed. What that contact means depends on the equipment and the subsystem. GEM centralizes this translation so drivers never hardcode it.