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:
- the member’s own choice for this workspace (
user_workspace_configsMOBILE_AUDIENCE_MODE); - the workspace default an admin with
manage_workspace_settingssets (workspace_configsMOBILE_DEFAULT_AUDIENCE_MODE), so a centre can open every member’s phone in Education while members can still opt out; - the account preference chosen in onboarding (
user_configsMOBILE_AUDIENCE_MODE).
- the member’s own choice for this workspace (
- 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.
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 withsyncHint: "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 thecrm 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 frompubspec.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.
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.
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 bybuild-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 beforerunApp.
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
BeforerunApp, 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 usesinitializeStartupState 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.