Skip to main content
The Flutter app (apps/mobile) brings eligible Tuturuuu workspace tools into a native shell. Its launcher, module availability, background behavior, and device permissions are separate from the web app’s browser runtime.

Learn by surface

Tasks, Calendar, and Finance are default launcher modules. Meet, Mail, Chat, and Notes are opt-in experiments documented in the workspace-tools guide. Turning a module on exposes its eligible launch surfaces; it does not grant workspace or account privileges. Mail keeps its exact-domain eligibility rule.

Modes (General and Education)

A mode is a display preference for one account in one workspace. It changes what the app puts first and never grants anything: every surface keeps its own permission check, workspace-hidden modules stay hidden, and guests see only what they could already open.
  • Default: General. Home is unchanged in General mode.
  • Resolution, first stored value wins:
    1. the member’s own choice for this workspace (user_workspace_configs MOBILE_AUDIENCE_MODE);
    2. the workspace default an admin with manage_workspace_settings sets (workspace_configs MOBILE_DEFAULT_AUDIENCE_MODE), so a centre can open every member’s phone in Education while members can still opt out;
    3. the account preference chosen in onboarding (user_configs MOBILE_AUDIENCE_MODE).
  • Where to change it: Settings → Workspace → Mode. Admins also see “Default for members”; personal workspaces have no member default.
  • Education Home: a “Today’s classes” card leads Home (hideable and reorderable like other Home widgets). The server decides access: the card is offered on Home and in the customization sheet only after the sessions read succeeds, which requires view_user_groups. A denial removes the card and its stored copy; any other failure keeps the last classes with an inline notice. In General mode the card’s data is never requested. Finished sessions sink below current and upcoming ones, phases update at each start and end, the list reloads after midnight, and states are words, never count chips.
  • Teacher scope: teachers see only the classes they teach by default, with a “Show all” switch. This is a presentation filter, not a security boundary. Until the consolidated Today endpoint can tell which classes a teacher teaches, the card lists all of the day’s classes and says so (“All classes today”) instead of claiming a filter.
  • Offline: the last resolved mode is cached per account and workspace, so the first frame is correct offline. A member’s own choice is queued and replayed (the config write is idempotent); the admin default is online only.
Regression coverage: test/features/audience_mode/, test/features/classes/, test/features/dashboard/view/home_mode_gate_test.dart (General never fetches; no access means absent from Home and the customization sheet), test/features/settings/view/settings_audience_mode_section_test.dart, the onboarding mode-slide cases in test/features/onboarding/onboarding_page_test.dart, and the Home order case in dashboard_layout_cubit_test.dart.

Offline rollout flags

Mobile rollout flags default to false and are cached per account and workspace. The app refreshes /api/v1/mobile/feature-flags?wsId=<workspace> at startup, on login, account/workspace changes, resume, network reconnect, and every server ttlSeconds while foregrounded, clamped to 15–3600 seconds with a 30-second fallback when no payload is known. The boundary cases are covered by mobile_flags_test.dart. Backgrounding cancels polling; resume requests fresh flags. Requests use Bearer authentication and the cached version as If-None-Match; HTTP 304 retains the payload. An unreachable server keeps the last known cached values without time expiry; a cold cache enables nothing. Logout clears all flag snapshots for that account and fences late responses. Workspace snapshots remain isolated. A server kill applies on the next successful refresh; losing connectivity does not disable flags. Unknown keys are ignored. mobile_offline is the master switch: when false, every offline_* flag is false, including test overrides. There is zero behaviour change while flags are off for the existing explicit Finance, Tasks, Calendar, and Inventory downloads. These register with a null flag. New app preparers register once through OfflinePreparationCoordinator.instance.registry.register(appKey, flagKey, preparer). The coordinator requires both the registered flag and master switch before running a flagged preparer. Existing permission and retention checks still apply. The web app owns config/feature-flags.json. From apps/mobile, run dart tool/generate_mobile_flags.dart when that manifest changes, then format the generated Dart file. The mobile manifest parity test skips explicitly while the manifest is absent. Reader regression coverage lives in test/core/feature_flags/mobile_flags_test.dart; registry/coordinator gating coverage lives in test/core/cache/offline_preparer_registry_test.dart.

Shell and offline expectations

Screens inherit the app shell’s background and single top title/actions bar. On phones and portrait tablets the floating bottom navbar owns in-app Back navigation and scroll clearance. On landscape tablets, laptops, and desktops (width >= 840dp, shortest side >= 600dp) the same destinations, including Back, move to a leading rail and the dock keeps only composers and page actions. Full-screen/system forms have their own shell rules. These conventions keep controls reachable and avoid duplicate headers. Every screen uses the same page gutters, section spacing, and wide-screen max widths. Only calendar, board, conversation, call, and media/map canvases run full-bleed. See the mobile design system. Offline availability is product-specific. Cached data is not proof that an edit reached the server. Review queued/sync states and recover through the owning product’s documented flow. Optional products should not warm private endpoints until access is known to be enabled. Offline status UI is default OFF behind offline_status_ui; the existing mobile_offline kill switch remains authoritative for offline capability. The settings preparation section accepts offlineStatusUiEnabled until the MobileFlags reader is integrated. With the flag off, its existing UI and behavior remain unchanged. With it on, app rows show readiness, indeterminate preparation progress (the coordinator has no per-app percentage), Wi-Fi/retry waits, failure, unavailability and last sync. Retry and sync timestamps use the device locale and local time zone. The compact ready count appears only in the existing offline settings section. These labels describe downloaded snapshots, not server acknowledgement of queued edits. Regression coverage: apps/mobile/test/features/settings/view/offline_status_ui_test.dart.

Versions and privacy

The toolchain reference reads the Flutter and Dart constraints and mobile package version from pubspec.yaml. Distribution artifacts and build metadata establish what a device is running. The browser bootstrap for Flutter is noindex; it is not a duplicate public marketing site. The standalone API migration uses a build-number gate at /api/v1/mobile/version for iOS and Android. The configured minimum supported build is inclusive; older builds require an update. Missing policy fails closed with 503. Mobile switches to consolidated contracts during this migration; the program accepts a temporary compatibility break followed by a forced update. External non-mobile consumers retain compatibility. The old semantic-version endpoint remains on the retained Next origin until separately reviewed. See the API contract and regression coverage. The API foundation does not itself activate the client screen or production gate. Developers changing translations regenerate localization before analysis/tests. Native app work does not require the paused Rust/TanStack Start runtime or the retired Docker cron runner. Database-dependent test fixtures still need an appropriate isolated environment; see Without Docker.

Private product feedback

Settings → Send feedback opens an account-scoped form inside the existing shell; the shell keeps its single title and dock navigation. The active platform Web /api/v1/product-feedback route owns submission, not the workspace CRM feedback store. Native calls use the current Supabase Bearer identity and never send an authoritative actor id. English and Vietnamese copy ship together. Ingress retains the shared 512 KiB request limit for every other route/method; only exact POST /api/v1/product-feedback gets the 2,850,000-byte envelope needed for base64 image plus bounded text. Both declared and actual streamed bytes are checked at the proxy and again in the owning route. The regression includes an old-limit negative control and adjacent-path/method denials. The default is off: PRODUCT_FEEDBACK_SUBMISSION_ENABLED=true enables text intake and requires a real Turnstile configuration even in development. Each explicit dispatch obtains a fresh token. The existing SQL intake owns atomic actor/network/global quota charges and the content-free idempotent receipt; unverified forwarded headers do not select a quota bucket. No automatic offline, Auth-response or challenge-response replay is allowed. HTTP 429 retains Retry-After; 409 retains the original reference. One optional PNG/JPEG/WebP screenshot is bounded at 2 MiB of source bytes. The server validates the actual format, rejects animation and more than ten million pixels, strips metadata, fits within 1920×1920, and stores at most 512 KiB of WebP. PRODUCT_FEEDBACK_MEDIA_ENABLED=true additionally requires the additive private media migration. The wrapper reuses the existing intake transaction and advisory lock: screenshot and receipt commit together, identical retries do not charge again, and adding, changing or removing media conflicts. Every Web submission, including a screenshot-free replay, uses this wrapper. Omitting a previous screenshot still conflicts when media intake is disabled; missing media schema fails closed. Small normalized screenshots live in the RLS-protected private media table, one per report; originals, filenames, public URLs and general-purpose attachments are not stored. This bounded design does not create a public Storage bucket. The app freezes an attempted draft and retains its original UUID. Only that reference is saved in account-scoped preferences; text, images and Turnstile tokens stay in memory. After restart, recovery is receipt observation only. The owner-only /receipts/{key} route remains available with submission disabled, so stopping intake does not prevent recovery. A missing receipt remains unknown and never starts another POST. An explicit in-session retry uses the same immutable draft/key with a fresh token. Initial definitive pre-acceptance 400/401/403/413/429 responses allow editing only if no earlier attempt has an unknown outcome. After a 503/transport uncertainty, a later retry rejection cannot erase the original key or unlock editing. Only a confirmed receipt resolves that uncertainty. There is no automatic polling or write replay. Staff can explicitly open a private screenshot from the Web inbox when both staff and media gates are enabled. The media route rechecks the current Auth identity and the existing SQL activated exact-domain staff assertion on each read. It returns a bounded uncached image projection, with no reporter identity, storage path or bearer URL. Staff status/archive/revision metadata stays read only. Regression coverage is in product-feedback-{handlers,service}.test.ts, product-feedback-private-media.sql, the internal-api feedback tests and product_feedback_{page,repository}_test.dart. The page tests exercise both 503 and transport uncertainty followed by each supported retry rejection. The privacy fixture first verifies synthetic camera/GPS EXIF on the input, then requires the stored WebP to omit metadata. Web replay tests exercise the real dispatcher against modeled RPC contracts; they do not replace SQL qualification. The disposable database runner applies the full current migration history before the 17-assertion media packet and type generation. Run it with bun run --cwd apps/database sb:validate:isolated --test supabase/tests/product-feedback-private-media.sql --typegen packages/types/src/supabase.ts through ttr resources run; it owns and cleans a separate temporary Supabase project. Before activation, require exact-head Web/mobile CI, hosted Auth and registry checks, real Turnstile acceptance, and device tests for image picking, account changes, pending recovery, keyboard/dock clearance and enlarged text.

Desktop beta downloads

The same Flutter app ships through the desktop beta channel for Windows x64, macOS, and Linux. The 2026-10-22 policy permits unsigned Windows direct-download installers when both signing secrets are absent. The download page and release notes disclose SmartScreen warnings and checksum verification. Configured signing failures block the Windows package. macOS still requires Developer ID signing and notarization; the Microsoft Store channel is separate. Windows in-app updates retain their publisher-signature checks, so unsigned betas use manual verified-installer updates. Packaging and receipt regressions are covered by scripts/desktop-deployment/windows-signing.test.mjs and verify-publication.test.mjs; native Windows acceptance remains a release gate. Windows x64 uses a per-user .exe installer from the official download page or GitHub desktop release. Unsigned builds may show SmartScreen Windows protected your PC or Unknown publisher. Verify the release SHA-256 checksum before using More info → Run anyway, if Windows offers it. Use the web app when organization policy blocks unsigned installers. See the desktop installation and signing plan.

Startup recovery and performance inspection

On Android and iOS, optional public model-download recovery starts after the first painted Flutter frame. This moves native transfer restoration and model file checks out of first-frame contention. The owning Settings flow retains initialization failures and retry behavior; other platforms do not schedule this recovery. Required authentication, appearance, encrypted cache and pending mutation restoration still finish before runApp. Regression coverage: test/core/startup/optional_startup_test.dart verifies paint-before-recovery ordering, one invocation, subsequent frame progress while recovery is pending, and synchronous/asynchronous failure containment. For a build-free performance pass, follow bootstrap.dart and app/view/app.dart separately: unawaited work can still compete with painting, and provider construction/locale loading happens when the root mounts. Record asset byte sizes and dependency/native plugin candidates as source measurements, not installed bundle sizes. Dynamic server icon selection references many constant glyphs in core/icons/platform_icon_data.dart; retain that contract when evaluating font subsets. Measure release size and startup timing separately in admitted CI/device workflows before claiming a numeric improvement.

First-frame critical path

Before runApp, bootstrap reads the local preferences (haptics, theme mode, system chrome, last routes) together with the consent read and gated admission in TelemetryPreference.instance.initialize, via initializeBootstrapServices. Both settle before Supabase starts. The overlap never moves Firebase earlier: Firebase is initialized only through FirebaseAdmission (signed in, and push or telemetry allowed), so a signed-out launch initializes no Firebase and no FCM. Consent is read before collection is enabled, and unsent Crashlytics reports are deleted before it is, in MobileObservability.initialize; only the package metadata read overlaps the collection switches. Local-notification setup (PushNotificationService.initialize) and the signed-in session (startSession, which is where FCM and Firebase admission happen) start after the first painted frame through scheduleOptionalStartup. startPushForCurrentAccount reads the signed-in account when it runs and skips a session an auth change already started before the first frame. Failures are logged by type only. A notification that launched the app is delivered once the session starts. Regression coverage: startup_state_test.dart and cold_start_firebase_contract_test.dart (no Firebase/FCM before sign-in, slow or failing Firebase, cold-start notification tap). These are orchestration fixtures; no device timing is claimed.

Independent startup state restoration

After Firebase/observability handlers and Supabase have settled, bootstrap uses initializeStartupState to overlap account appearance reads with offline state restoration via Future.wait. Keep the identity/MFA boundary before appearance, and keep CacheStore before OfflineMutationQueue in a single branch: a cache failure must skip queue restoration. Each branch retains its original fallback or error log with the original error/stack; both finish before routes, builder and runApp. Firebase and Supabase remain sequential to preserve platform-error handler coverage during session restoration. test/core/startup/startup_state_test.dart uses completion barriers to prove concurrency, both completion orders, queue ordering, sync/async cache and queue failure reporting, appearance fallback and unexpected-error propagation. These are orchestration fixtures, not native-plugin or device latency measurements.

Pull to refresh

Remote list surfaces support pulling down from the top, including lists shorter than the viewport and actionable empty/error states. Refresh awaits the existing cubit or repository owner, retains its account/workspace fences and does not start a second data layer. The Nova refresh affordance adds clearance for scrollable floating headers; fixed headers already pad the body. Only the owning vertical scroll view opts into always-scrollable physics, preserving nested horizontal row swipes. Calendar refresh completes only when its event reload completes. The audit below covers routed lists and remote list overlays. Cold loaders already have a request in flight. Editable forms and composers, authentication/MFA forms, QR/media viewers, active calls, local preference/static navigation screens, and reverse realtime chat/Assistant message timelines retain their existing gestures. Apps reads its registry and local preferences; it has no remote feed. Regression evidence: notifications_pull_to_refresh_test.dart exercises Inbox and Archive with empty, short and initial-error data, checks the selected cubit tab and refresh flag, holds the request to verify the refresh lifetime and then asserts new visible content. nova_refresh_indicator_test.dart covers short page physics, error viewports, canceled/upward gestures and actual floating-header geometry. The habit tracker detail Entries and Leaderboard tabs and the note-link picker also refresh through their existing owners. Explicit refresh retains empty/error presentation instead of restarting a full-page cold loader. Regression coverage includes both task-board row-action suites and exact indicator offsets for fixed and scrollable headers. Pull gestures retain the current error message while refreshing. Explicit Retry returns to loading feedback. Compact sheet empty/error states use a plain indicator with a shrink-wrapped scroll view. Regression coverage includes calendar_cubit_test.dart and nova_refresh_indicator_test.dart.