The apps#

Hinata ships a single Flutter client that runs from one codebase on Android, iOS, Web and macOS. There is no separate mobile app and desktop app to keep in sync — the same screens, the same state, the same networking layer adapt to whatever they run on. This page explains how the app connects to your server, how it decides whether it is up to date, how you sign in, and how a single app talks to many servers at once.

One Flutter codebase — Android, iOS, Web and macOS from a single app.

One codebase, four platforms#

The client is built with Flutter. State is managed with bloc/cubit, routing with go_router, localization with i18next, and every network call goes through a single ApiClient built on dio (automatic token refresh, Accept-Language header). Because there is only one codebase, a feature lands everywhere at once.

• Responsive by design. Layout adapts through golden-ratio-derived breakpoints rather than fixed pixel widths, so the same UI reflows cleanly from a phone to a tablet to a desktop window to a browser tab.
• Localized. The UI ships in English and German (i18next), and error messages are localized by the server through the Accept-Language header — the client sends the user's language, the server returns the message already translated.
• Light & dark. A navy navigation rail, a warm-paper workspace and the signature honey-amber accent #D9A032 that reads identically in light and dark mode, with liquid-glass surfaces on the mobile nav, the ⌘K palette and the attachment lightbox.

How it works: from launch to workspace#

Every fresh launch walks a short, predictable path before you land in your workspace.

Connect#

The very first thing a native app asks for is a server URL. It probes /api/v1/meta and refuses to continue until the server responds, so you can never end up "connected" to a host that isn't a Hinata server. Previously used servers appear as one-tap shortcuts beneath the URL field, which makes re-connecting after a server was briefly unreachable a single tap.

Version gate#

On every start the app reads the server's advertised minimum client version. If the installed app is older, it shows an update-required screen instead of the workspace. Operators control this value with the HINATA_APP_MIN_VERSION environment variable, or override it live in the Admin area → App settings (the database value wins). This means you can force every client onto a new build the moment a breaking change ships — no client-side coordination required.

Setup wizard#

Point the app at a freshly deployed server and it walks you through first-run setup in the UI: your organization name and the first administrator account. If you would rather bootstrap unattended, set HINATA_SETUP_AUTO_COMPLETE=true together with HINATA_SETUP_ORGANIZATION_NAME and the admin credentials, and the wizard is skipped. See Setup & first run.

Sign in#

Once a server is set up, you authenticate with either:

• Local credentials — username/e-mail and password. Self-registration, e-mail verification, forgot-password and optional admin approval are all supported and toggled by feature flags (see Authentication).
• SSO — OpenID Connect, OAuth 2.0, SAML 2.0 or LDAP, configured by the operator in the Admin area. SSO returns to the app through the hinata://auth-callback deep link. See Single sign-on.

When two-factor authentication (TOTP) is enabled on an account, sign-in adds a one-time-code challenge after the password step.

Multi-server: one app, many servers#

A single Hinata app can talk to any number of independent servers, and switch between them without signing out of the others.

• Save multiple servers. Add each server once; the app remembers them.
• Switch freely. Move between servers from the switcher; each keeps its own session.
• Per-server scoped tokens. Access tokens are scoped to the server that issued them — switching servers never leaks credentials across instances.

The Server Manager#

The liquid-glass Server Manager is where you administer your saved servers. It probes every saved server in parallel on open, so each row shows a live status — a pulsing dot and a real ping in milliseconds — and flips from checking… to online (with latency) or offline as results land.

From the manager you can:

• Add a server — the app runs a connection test before saving, so an unreachable or wrong URL is caught immediately.
• Edit a saved server's name or URL.
• Delete a server you no longer use.
• Switch to any online server with a tap.

Where to get the app#

There are three ways to run the client, depending on who you are.

The published store builds are white-label apps: because native apps carry no baked-in server URL, one published app can serve every operator through the Hinata Connect gateway.

Where to go next#

• White-label & branding — ship your own branded client.
• Authentication — local accounts, registration, 2FA.
• Single sign-on — connect an identity provider.
• Setup & first run — configuring a fresh server.