safesight-control/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build & Test Commands

• Build: go build -o managerd ./cmd/managerd
• Run: ./managerd (uses managerd.json config) or ./managerd <config-path>
• Test all: go test ./...
• Test single package: go test ./internal/service/...
• Test single test: go test ./internal/storage/... -run TestAssetsRepo_SaveTemplate
• Verbose test: go test ./internal/web/... -v -run TestUI_ActionDevicesBatchAction

Codebase Architecture

Layered Structure (no DI framework — manual wiring in main.go)

cmd/managerd/main.go     — Composition root: builds config, services, storage, router
internal/api/            — Thin HTTP handlers that delegate to services (chi router, no framework)
internal/web/            — Embedded HTML UI (Go html/template + layout.html pattern)
internal/service/        — Business logic (discovery, registry, tasks, config assets, preview rendering, template slots)
internal/storage/        — SQLite persistence (raw SQL via database/sql, pure-Go modernc.org/sqlite driver)
internal/config/         — JSON config file loading (managerd.json)
internal/models/         — Core domain types (Device, Task, DeviceTaskStatus, etc.)
templates/               — Local JSON template files loaded at runtime
templates/standard_templates/ — "Standard" templates (std_ prefix) imported into SQLite on startup

Dependency Flow (all wired in main.go)

config → service (agent client, registry, discovery)
config + service → storage (opens SQLite, creates repos)
storage → service (task service, config preview, etc.)
service + storage → api + web (HTTP handlers)
chi.Router → mounts api routes + UI

Device Communication

• AgentClient proxies HTTP requests to device-side rk3588-agent via the device's IP/port.
• Two timeout tiers: 3s for normal requests, 120s for long operations (config apply, media server, model uploads).
• All proxied requests carry X-RK-Token header from config.
• Generic passthrough: r.Handle("/devices/{id}/v1/*", proxyAgentV1) covers agent sub-routes.

Config Asset Management

The system manages four asset types stored as JSON blobs in SQLite:

Asset	Table	Key Concept
Templates	templates	Base config template with bindings/variables
Profiles	profiles	Template-specific configuration (references primary_template_name)
Overlays	overlays	Named config overrides that can be appended to any profile
Integration Services	integration_services	Third-party service definitions (e.g., RTMP, HTTP push)
Video Sources	video_sources	Camera/stream source definitions

Naming convention: names starting with std_ are read-only standard templates, imported on startup from templates/standard_templates/.

The config preview rendering pipeline: merge template + profile + overlays → resolve binding references (video sources, integration services) → expand slot tokens (${slot:name.field}) → compute SHA256 hash.

Background Goroutines

• RegistryService: 2s tick for offline pruning, 30s tick for graph polling
• DiscoveryService: UDP broadcast listener (blocking goroutine per discovery request)
• TaskService: concurrent task execution gated by a semaphore channel

Key Database Tables (SQLite, migrations in storage/migrate.go)

• devices — device registry (device_id PK, ip, port, online status, last_seen)
• templates, profiles, overlays — config assets
• integration_services, video_sources — third-party service and video source definitions
• tasks + task_devices — batch task execution (type, status, per-device status)
• device_config_state — per-device applied config state
• audit_logs — action audit trail (actor, action, target, details)

Test Patterns

• Test files co-located with source: *_test.go
• Services constructed with nil/real dependencies (no mocking framework)
• HTTP tests use httptest.NewRequest + httptest.NewRecorder
• Storage tests use in-memory SQLite (tests seed their own data via repo methods)
• Tests assert on status codes, redirect URLs, and response body content

Coding Rules

• Never use sed on Windows (Git Bash). It produces stray t characters, broken indentation, and corrupted files.
• Use rg and fd for searching (not grep/find). Both are installed.
• File editing: use the write tool for new/rewritten files and edit tool for precise changes. For complex find-and-replace, write a small temporary Go program.
• No tabs: use spaces for indentation in all source files.
• No fetch() in templates for page data — all API calls must go through Go server-side handlers. JS is only for UI interactivity (modals, carousels, confirm dialogs).
• No inline onclick with complex quoting — use data-* attributes + event delegation instead.
• Use pwsh for PowerShell commands (v7.6.1 in PATH, not powershell.exe).