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.

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, and the team's detection thresholds and language; 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 the tenant_settings_effective view, generated from the registry.
• 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.
• Account over team: a person's bird-name languages win over the team language wherever that person reads names (web pages, PDF and CSV exports, shared links). Alerts and scheduled exports use the team language.

Settings

Legend: ✓ = the setting exists at that level. In the Satellite column, "hub" = stored on the hub for each satellite, "local" = kept on the satellite itself.

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 counts as at least admin in every team. 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.

Account

Teams

Satellites

Detections and data

Alerts

Hub

Public