pi-videoreg

videoreg-api method conventions — Method<Name>(ApiMethod) template, method-to-plugin assignment (logic lives where state lives), snake_case method keys, response format {status, data} / {status, error}, registration in plugin_builder.py, calling other plugins via api_client.exec and parsing responses (is_ok / get_data / get_error), error handling, i18n for response strings. Trigger when implementing or modifying a videoreg-api method in plugins/<plugin>/methods/.

videoreg high-level architecture — three-layer request flow (HTTP path and command path), planning algorithm for a new feature, review checklist, principle that logic lives in the plugin owning the state, names must match across layers, response format convention {status, data/error}. Trigger when planning a feature, deciding where a method or command should live, reviewing a handler/method/module, or any cross-cutting architectural question. Implementation templates live in videoreg-plugin / videoreg-api / videoreg-http-backend / videoreg-command.

videoreg gateway command conventions — Command<Name>(GatewayCommand) template, command-to-plugin assignment (same as api-methods — logic lives where state lives), registration via GatewayCommandMethod in plugin_builder.py, replying via gateway.send_text / send_image / send_video / send_document, capability check via gateway.support, entry vs internal commands declared in the plugin's manifest.yaml (with optional weigh/hidden), i18n for replies. Trigger when creating or modifying a user-facing command in plugins/<plugin>/commands/.

videoreg plugin conventions — plugin id vs short name, plugin folder layout (plugin.py, plugin_builder.py, methods/, commands/, translations/), assembly order in plugin_builder.py (init_logger / init_socket / init_journal_client / init_api_client / init_api_servier), plugin lifecycle (start/stop), service-to-plugin mapping in videoreg.manifest.yaml. Trigger when creating a new plugin, modifying plugin.py or plugin_builder.py skeleton, or registering a plugin in the manifest. Excludes api-method and command bodies — see videoreg-api and videoreg-command.

videoreg FolderWatcher conventions — abstract class in sdk/folder_watcher.py for monitoring a directory via inotify-simple, subclasses implement async on_file_created(filename), blocking inotify.read runs in run_in_executor with a 500ms timeout and a threading.Event for clean shutdown, lifecycle wiring (watcher.start() in plugin.start(), await watcher.stop() in plugin.stop()), implementation example in plugins/org_vrg_camera/h264_watcher.py. Trigger when creating a new folder watcher, modifying an existing one (e.g. h264_watcher.py / jpeg_watcher.py), or wiring a watcher into a plugin's lifecycle.

videoreg frontend conventions — Vue 3 SPA without Vue Router (history.pushState navigation), page component template with fetch + credentials same-origin, settings sub-page registration (back button, settingsPages arrays, SettingsComponent card), Icon component (Material Symbols inline SVG), i18n via $t/$p, reusable components and design system rules. Trigger when creating or modifying Vue components in plugins/org_vrg_http/static/js/, adding a new page or settings sub-page, or working on the videoreg web UI.

videoreg HTTP backend conventions — handler template (system handlers without api-client vs plugin handlers using api-client), thin-transport rule, kebab-case route ↔ handle_<verb>_<resource> ↔ api-method naming, dependencies from request.app (api_client / logger / videoreg / jwt_handler / user_manager), parsing api responses (is_ok / get_data / get_error), parallel aggregation via asyncio.gather, route registration in plugins/org_vrg_http/plugin.py, public-path auth rules. Trigger when implementing or modifying an HTTP handler in plugins/org_vrg_http/handlers/.

videoreg internationalization conventions — engine in sdk/i18n.py (class I18n, accessible as runner.i18n), translation files in sdk/translations/ and plugins/<id>/translations/ (ru.yaml / en.yaml, plugin strings merged on top of global), flat dot-namespaced keys (camera.start_recording), CLDR plural forms (one/few/many/other), Python API plugin.runner.i18n.t/p with {{var}} substitution, JS API VrgI18n / $t / $p loaded via GET /api/i18n, locale set in videoreg.manifest.yaml, fallback to en then to the key itself. Trigger when adding or modifying translation keys in any translations/*.yaml, using $t/$p in Vue components, using i18n.t/p in Python, or setting up i18n in a new plugin.

videoreg event journal conventions — business-event log separate from technical logging, file format (.videoreg/data/plugins/org_vrg_core/journal/YYYY-MM-DD.txt), JournalRecord/JournalClient/JournalServer in sdk/journal.py, initialization via plugin.init_journal_client() in plugin_builder.py, sending events with self.journal_client.write(JournalRecord(...)), unique event names across plugins. Trigger when adding or modifying business events (start/stop, recording lifecycle, charging events, …), wiring journal_client into a plugin, or working with sdk/journal.py.

videoreg design system rules — editing plugins/org_vrg_http/static/style.css (CSS variables, dark theme, no hardcoded colors/spacing), keeping docs/CSS.md in sync, responsiveness from 320px to desktop, what's allowed (extending classes, new modifiers) vs not allowed (renaming/removing existing classes). Trigger when changing visual appearance, color scheme, typography, spacing, shadows, layout consistency, or responsiveness in the videoreg web UI.