Settings and permissions by level

Otavi decides things at four levels:

• Hub everything on this hub, set by hub admins in Hub settings.
• Team each team, set by its admins in Team settings.
• Account each person, for themselves, on the Account page.
• Satellite each registered phone or Pi, either stored on the hub (its page under Satellites) or kept on the satellite itself (the phone's Settings screen, the Pi's .env).

This page lists every setting and permission with the levels where it exists: where to change something, who may do what, and how a value set at one level meets the others. In the tables, a level badge names a level, and a role badge such as Member the lowest team role allowed (Hub admin means hub admins only).

Words used here

• Default: what a level gets when it sets nothing itself, named after where it comes from: "Hub default (Off)", "Team default (On)".
• Override: a lower level setting its own value instead of the default. The level above can allow it or not: a padlock beside the setting, open for "Teams may override" or "Satellites may override", closed when they may not.
• Locked: a level above does not allow overriding. The setting shows its value, greyed, with "Locked by the hub" or "Locked by the team".
• Hub admin: the hub-wide role (is_platform_admin in the code, where the hub level is still called platform).
• Device: only the computer or phone someone signs in from, as in the two-factor "remembered devices". A recording phone or Pi is a satellite.

How the levels combine

• Settings from the registry (everything satellites receive, the team's detection thresholds and language, and each person's preferences; table below): one rule for all of them. The hub sets a value for every team, a team may set its own, a satellite its own where the setting reaches satellites. A level that sets nothing follows the one above, and says so ("Hub default (30 s)"); the built-in default stands at the top. A level can lock the one below: the hub for every team (and their satellites), a team for its satellites. Under a lock, a level keeps its own value but it does not apply, and a new one is refused with 403 LOCKED_BY_PLATFORM or LOCKED_BY_TEAM (the API codes keep the code names). A new team follows the hub for everything, except its language when its creator reads another one.
• Where they are stored: each level's value in today's columns and keys (platform_settings, tenant_settings, satellite_config_overrides; NULL = follow the level above), the locks in setting_locks. One writer checks and saves every change (PATCH /api/settings/effective), and the Python worker and SQL readers get resolved values from two views generated from the registry: tenant_settings_effective (per team) and satellite_settings_effective (per satellite, which the worker uses for the minimum confidence and range filter of the satellite whose chunk it analyses).
• Hub switches over team options: a team can open itself to newcomers only while allow_public_teams is on, and publish a public page only while allow_public_pages is on.
• A person's preferences (languages, date and time formats, start of week, PDF paper, voting from the detection list) are registry settings at the account level: the hub sets everyone's default (Hub settings, Defaults), a person their own on the Account page, and choosing "Hub default" goes back to it. A person's languages win over the team's wherever that person reads names (web pages, PDF and CSV exports, shared links); a person who has not chosen a language reads in the team's language within that team, else the hub's. Alerts and scheduled exports use the team language. The hub's lock on the language binds people too.

Settings

In the Levels column, a badge names each level where the setting exists, top down; "kept on it" marks a satellite setting stored on the satellite itself rather than on the hub.

Settings from the registry

Declared once in the settings registry (packages/shared/src/settings.ts), which the hub, the web pages, the phone and the Pi all read; this table is generated from it. The audio filter switch turns off both gates before upload, the silence gate and the YAMNet bird gate with its category drops, on phones and Pis alike Pi 1.6.5.

Access and joining

Detection and inference

Satellites: schedule, status and admin-only settings

Storage, retention and images

All hub level.

Alerts

Display and language

Settings kept on the satellite itself

• Phone (Settings screen): keep the screen on, record when the app opens, vibrate on detection, GPS on or off and its interval, manual position, name. The phone also remembers whether it was recording, so that an update resumes it.
• Raspberry Pi (.env, OTAVI_SAT_*): capture mode and audio input, sample rate and chunk length, GPS mode and fixed position, whether the YAMNet model runs at all, telemetry interval, data folder, log level. Its .env may also set starting values (inference mode, minimum confidence, range filter, YAMNet threshold, recording profile) that the hub replaces on its first configuration push.
• Before the first configuration: phones and Pis run with the registry's defaults (DEFAULT_SATELLITE_CONFIG), the same values the hub sends a team that sets nothing (phone 1.27+, Pi 1.6.4).

Deployment switches

Set in the hub's .env by whoever runs the server; see Configuration.

• OTAVI_AUTH_PLATFORM_ADMIN_EMAILS: who becomes a hub admin.
• OTAVI_AUTH_MFA_ENCRYPTION_KEY: makes two-factor sign-in available.
• OTAVI_EBIRD_API_KEY: expected species and eBird-based rarity.
• OTAVI_SMTP_*: every email (welcome, invites, email alerts, emailed exports).
• OTAVI_HUB_METRICS_TOKEN: the Prometheus metrics endpoint.
• OTAVI_BACKUP_*: nightly backups.

Permissions

Roles inside a team, lowest first: viewer, member, admin, owner. A hub admin may do in every team what its owner may. The registrant of a satellite is the person who registered it.

"Manage a satellite" means: a hub admin, an admin of the satellite's team, or its registrant while the team's policy is "members". A satellite's own key may act on that satellite only: rename it, rotate its key, edit its settings.

A role counts in the team the action concerns: the team being viewed for lists and statistics, the item's own team for anything done to a detection, a rule, a note or a satellite. An API key acts for one team with the role it was given; "not an API key" marks what needs a person signed in.

Every action is declared once, in the permissions registry (packages/shared/src/permissions.ts), with who may perform it and what gates it. The web offers what the rule allows (the same declarations), each API route names the action it performs, and one guard applies the rule to every route: 401 when no one is signed in, 403 when the role or the kind of caller is not allowed, 404 when the team or the item is out of reach. The tables below are generated from the registry.

Account

Teams

Satellites

Detections and data

Alerts

Hub

Public