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.

Documents and Education

The mobile document editor shows the owner and the last edit time from the document it opened. Returning to the list reloads the active workspace, and an autosave that finishes after navigation refreshes it again. The Web list API orders by edit time across pages, with creation time as the fallback when the metadata migration is pending. Course Practice is available for enrolled learners when learner progress is enabled. It draws up to 20 multiple-choice questions from published modules and their linked quiz sets. The server grades the completed session and records the attempt. Retrying a submission reuses its session key. The workspace quiz library supports local practice. The Attempts tab loads additional learner attempts alongside any Teach results the actor can access. The Web document route and learner quiz-attempt route tests cover the ordering fallback and enrolled-course question selection. The mobile Documents and Education widget suites cover their screen behavior.

Automatic cache refresh

The mobile app revalidates visited, cache-backed resources for the signed-in account and active workspace after App Lock admits requests. Resume, restored connectivity, and a silent push hint can request a refresh. The encrypted cache keeps the last authorized response available while the request runs. Notifications, chat, mail, tasks, and calendar use freshness windows of 45 seconds, one minute, two minutes, three minutes, and five minutes respectively. Other resources inherit their cache policy. Automatic requests share up to three slots, coalesce by cache key, and back off after failures. User-initiated refreshes remain available through the unlock gate. Foreground resume, reconnect and push refreshes can run on cellular, with battery saver or data saver enabled, and below 20% battery. Android WorkManager and iOS BGAppRefreshTask can record a one-shot wake hint. OS refresh requires an unmetered network, at least 20% battery, and system power and data saving off. The app processes the hint after foreground unlock, when it can check the active account and workspace. If a resource is still fresh or in backoff, the app retains the hint and retries on a later foreground resume. A data-only push with syncHint: "1" uses the same admission path and does not display a notification. Push hints revalidate eligible notifications, chat, and mail resources with existing read endpoints. Coverage: smart_sync_test.dart exercises policy, timestamps, bounded concurrency, deduplication, retry delays and the unlock gate.

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 full-height leading rail and the dock keeps only composers and page actions. Below 1280dp the rail is 80dp of icons with tooltips, matching the web’s collapsed sidebar; from 1280dp (13-inch laptops and wider) it is a 240dp sidebar with each destination’s label. 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. Apps keeps Search above the launcher list when there is room, including while the list scrolls. Pinned apps stay out of Recents. Contacts keeps the crm launcher ID and accepts /crm as a route alias so pinned apps and deep links continue to open. The Apps regression tests cover filtering, recents, and dock clearance. Inbox retries queued read changes on open, on resume, and after a transient network or server failure. A single-item read change stops automatic replay after four ordinary retryable failures and offers tap-to-retry. A server response that the notification no longer exists clears its queued read change. The inbox reloads from the current account and workspace after queue replay. The offline mutation admission tests cover replay, deleted notifications, and manual recovery. 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.

Home on tablets and desktops

Home fills wide screens instead of a narrow column. Scope: the Flutter app’s Home dashboard on every platform; other root pages share the wider root canvas (1600dp on expanded bodies) and the rail or sidebar.
  • Columns. Cards flow into balanced columns: each card goes to the shortest column, so a short card never leaves one side empty. Columns are at least 320dp: one on phones, two on portrait tablets, three beside the rail or the laptop sidebar, four on wide desktops. Today and Up next are separate cards.
  • Scale. The greeting, date and Today at a glance numbers step up with the width Home receives, and so does the gap between cards.
  • Today at a glance. On tablets and wider it is a KPI strip under the greeting. On phones it stays a card in the order chosen in Customize. Hiding it hides the strip too.
  • Failed cards. A card whose load fails says which section failed, that the data is safe, and offers Retry, which reloads only that section. Pull to refresh still works on touch screens, but no message asks for it.
Regression coverage: test/features/shell/view/home_render_cases.dart (phone, both tablet orientations, laptop and wide desktop; failed-card Retry), test/core/responsive/sliver_responsive_cards_test.dart and the shell rail tests.

Security check (Turnstile)

The server decides when a request needs a Turnstile token: the adaptive step-up on writes and the offline-download guard on explicit bulk reads. The abuse-guard Worker does not issue Turnstile challenges. The app decides only how to ask:
  • Background first. Every step-up first tries an invisible solve. Sign-in and feedback start one when they open, so the submit usually finds a token ready. A ready token is handed to one request of the same account (or the same signed-out state), within three minutes by a monotonic clock (Turnstile tokens expire after 300 seconds), and never reused.
  • Never on reads or navigation. A plain read (Home, lists, opening a screen) never shows the check. If the background solve cannot get a token, the read fails like any other request and its card offers Retry.
  • A card in context, never a dimmed full-screen dialog. When Cloudflare needs interaction, a small card appears above the dock on phones and in the bottom corner on wider screens. Not now, Escape or system Back cancels that one action; Back closes the card before it navigates or offers to exit. An unanswered card gives up after three minutes, and a sign-out or account switch settles it.
    • In-app writes and explicit offline downloads: the page stays usable around the card and Tab is not trapped, because the app is replaying one already-formed request. Escape also works from the text field the person was typing in when the card opened, and is left to the page elsewhere.
    • Sign-in, QR sign-in and feedback forms: the card is a route of its own. The form takes no input, focus stays in the card and Back closes the card first, so what is submitted is what the form shows.
  • Sign-in stays consistent. The sign-in form runs one check at a time and gives its token to the latest submit. The token is dropped if the email or password changed, the step changed, the person opened another page from sign-in, add-account is being cancelled, or code verification started. The code step shows the address the code went to. While Turnstile is configured, nothing is submitted without a token.
  • One token, one request. Proof preparation for Native Integrity never carries the step-up token; only the protected request does.
The security property is unchanged: every protected action still sends a token the server verifies with Siteverify, and the server’s session clearance (15 minutes after a pass) and the native client credential still apply. Regression coverage: test/data/sources/api_client_prompt_policy_test.dart, test/features/auth/widgets/security_check_dialog_test.dart, security_check_prewarm_test.dart, and the configured sign-in suite test/features/auth/view/login_email_mode_captcha_test.dart, which CI runs with Turnstile defines and an exact test count.

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 on Apple silicon and Intel, and Ubuntu x64. The download page shows each available beta with installation details and a SHA-256 checksum. A platform without an available installer shows Coming soon, and the web app remains available. The download states are covered by build-download-options.test.ts in the Web download route. 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.