GPS Settings

GPS display preferences are stored as system-global key-value pairs in the SystemConfig table. These settings apply to all users — GPS is a system-internal feature, not per-user.

Available Keys

Key	Default	Values	Description
gps.speed_unit	"kmh"	kmh, mps, mph, knots	Speed unit for display
gps.coordinate_format	"decimal"	decimal, dms	Coordinate display format
gps.timezone	"utc"	utc, local	Timestamp display timezone
gps.retention_days	null	integer or null	Data retention window; null = unlimited

REST Endpoints

Method	Path	Permission	Description
GET	/v1/system-config	settings:read	List all system config entries
GET	/v1/system-config/{key}	settings:read	Get single config entry
PATCH	/v1/system-config/{key}	settings:write	Update config value

GraphQL

• systemConfigs(prefix: String) → [GqlSystemConfig] — pass "gps." to fetch all GPS settings
• systemConfig(key: String) → GqlSystemConfig
• updateSystemConfig(key: String!, value: JSON!) → GqlSystemConfig

Examples

Get all system config entries:

GET /v1/system-config

Response (entries are wrapped in a configs array; each includes updated_at):

{
  "configs": [
    { "key": "gps.coordinate_format", "value": "decimal", "description": "Coordinate format: decimal, dms", "updated_at": "2026-06-22T00:00:00+00:00" },
    { "key": "gps.retention_days", "value": null, "description": "Data retention in days, null = unlimited", "updated_at": "2026-06-22T00:00:00+00:00" },
    { "key": "gps.speed_unit", "value": "kmh", "description": "Preferred speed unit: kmh, mps, mph, knots", "updated_at": "2026-06-22T00:00:00+00:00" },
    { "key": "gps.timezone", "value": "utc", "description": "Display timezone: utc, local", "updated_at": "2026-06-22T00:00:00+00:00" }
  ]
}

Entries are ordered by key ascending. GET /v1/system-config/{key} and PATCH return a single bare object (no configs wrapper).

GPS settings can be narrowed in GraphQL via systemConfigs(prefix: "gps.").

Update speed unit:

PATCH /v1/system-config/gps.speed_unit
{ "value": "knots" }

Audit

Every PATCH on a setting emits a setting_updated audit event with the key, old value, and new value.

Behaviour Notes

• Settings keys are pre-seeded in the migration. No endpoint exists to create new keys.
• Values are stored as JSONB — strings must be quoted ("kmh" not kmh), numbers as-is, null as null.
• gps.retention_days — when set to an integer, the API prunes GPS data older than N days. Pruning schedule is application-internal (not exposed as an API).

RBAC Permissions

Permission	Description
settings:read	View system settings
settings:write	Modify system settings