> For the complete documentation index, see [llms.txt](https://docs.snapfix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.snapfix.com/how-the-apps-work/shared.md).

# Shared behavior

{% hint style="info" %}
Draft, written by an agent and not yet checked by a person ([how to read these docs](https://docs.snapfix.com/how-to-read.md)). [Source on GitHub](https://github.com/snapfix/docs/blob/main/spec/shared.md).
{% endhint %}

Behavior that many screens rely on: sign-in and session expiry, switching sites, notifications and emails, date and number formats, global errors, offline sync and permission checks. Each part states the cross-cutting rule, cites the code, and links the screen, API and feature docs that own the details.

Code read at: web\_app\_v2 @ 0989b8e685, ios @ aa31967ac8, android @ 86068bfeea, api\_php\_live\_v2 @ ef3c4319f6, authpy @ 5d5758661c, apipy @ 0e83c85e5a, php-apis @ 238ca4414e, dynamic-link @ 4d1cd0eb62. Known defects carry BUG, SEC, UX or PERF tags ([fixes/](https://github.com/snapfix/docs/blob/main/fixes/README.md)); open questions carry ASK tags ([ASK.md](https://github.com/snapfix/docs/blob/main/ASK.md)).

## Sign-in and session expiry

Every client holds two tokens from authpy: an access token and a refresh token. `POST /login` and `POST /refresh-v2` return them ([Auth API](https://docs.snapfix.com/engineering-reference/api/auth.md)). What the tokens claim, how long they last and how the servers check them is in [User tokens](https://docs.snapfix.com/engineering-reference/api.md#user-tokens); the production lifetimes are open \[[ASK-32](https://github.com/snapfix/docs/blob/main/ASK.md#ask-32-how-long-do-sessions-last-in-production)]. The screens are [Sign in](https://docs.snapfix.com/how-the-apps-work/screens/account/sign-in.md), [Login code](https://docs.snapfix.com/how-the-apps-work/screens/account/login-code.md) and [Set password](https://docs.snapfix.com/how-the-apps-work/screens/account/set-password.md); the product view is [Sign in](https://docs.snapfix.com/product/features/account/sign-in.md).

### What each client keeps

| Client  | Tokens                                                                                                                                                       | Signed-in flag                    |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------- |
| Web     | Browser local storage, record `authData`, with the user's data (web\_app\_v2 @ 0989b8e685, `src/app/services/user/user-helper/user-helper.service.ts:40-54`) | The same record                   |
| iOS     | `UserDefaults`, key `TOKEN_SAVED` (ios @ aa31967ac8, `SVProgressHUD/JWTHelper.swift:20`, `:59`, `:65`)                                                       | `isLoggedIn` in `UserDefaults`    |
| Android | `SharedPreferences`, keys `AccessToken` and `RefreshToken` (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/utils/TokenPrefUtil.java:20-40`)   | `LoggedId` in `SharedPreferences` |

The apps also keep the sign-in password in plain text on the phone.

### Signed-out visitors

* **Web.** Pages behind `authMainGuard` need a stored access token, refresh token and user data; without them the browser goes to `/auth/sign-in` (web\_app\_v2 @ 0989b8e685, `src/app/services/auth/auth-guard/auth-main/auth-main.guard.ts:13-17`). A signed-in browser that opens sign-in goes to `/fix` (`src/app/services/auth/auth-guard/auth-signin/auth-signin.guard.ts:13-16`). Both guards check that the tokens are there, not that they are valid; expiry is handled by the renewal below.
* **Apps.** The launch screen decides between the walkthrough, sign-in and the home screen: [Splash](https://docs.snapfix.com/how-the-apps-work/screens/account/splash.md).

### Renewal on each client

* **Web.** Before a request with a token goes out, an expired access token is renewed first (web\_app\_v2 @ 0989b8e685, `src/app/services/auth/auth-interceptor/auth.interceptor.ts:61-70`). A `401` on any other call forces one renewal and repeats the call, except on the authpy routes the web calls with the shared Basic login (sign-in, SSO, sign-up, password reset and username checks: `src/app/services/http/http.service.ts:159-180`) and on the renewal itself (`auth.interceptor.ts:82-89`, `:101-103`). Parallel calls share one renewal (`src/app/services/auth/auth-token/auth-token.service.ts:47-61`). A request that should carry a user token but has none is dropped: the caller gets neither an answer nor an error (`auth.interceptor.ts:78`).
* **iOS.** A response with the message "token has expired", or a `401`, starts a renewal, and the request is sent again once the renewal succeeds (ios @ aa31967ac8, `APIManagers/APIManager.swift:1418-1428`, check at `:2091-2100`). `JWTHelper.getRefreshToken` runs one renewal at a time; a caller that finds one running checks again up to three times, five seconds apart, and succeeds once the token has changed (`SVProgressHUD/JWTHelper.swift:209-234`).
* **Android.** Screens that get the message "The incoming token has expired" run `RefreshTokensTask` and repeat their call; `ManageParentUserViewModel` is one example (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/viewModels/ManageParentUserViewModel.kt:97-104`). `ParsingManager.parseData` turns a `401` into that message (`app/src/main/java/gmail/com/snapfixapp/network/ParsingManager.java:122-123`). `RefreshTokensTask` calls `refresh-v2` on the build's environment. If a renewal is already running, it waits three seconds and reports success unless that renewal failed (`app/src/main/java/gmail/com/snapfixapp/tasks/RefreshTokensTask.java:101-125`). A success stores the new access token and, when one comes back, the new refresh token (`:131-142`). A renewal that fails for another reason, such as no connection, just reports failure (`:154-158`).

What a refused renewal does:

| Client  | Refusal with `401`                                                                                                                                                                                                                                                                                                                                                                                                              | Refusal with `403` or `409`                                                                                                                                                                                                                                                                                                                    |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Web     | Any failed renewal is treated alike (a refused answer becomes a `401`: `auth-token.service.ts:63-64`). A password or code user (`login_src` `snapfix`) gets the mini sign-in dialog, which cannot be closed and starts on the code step ([Login code](https://docs.snapfix.com/how-the-apps-work/screens/account/login-code.md)). Anyone else is signed out at once with no message (`auth.interceptor.ts:105-114`, `:128-140`) | The same                                                                                                                                                                                                                                                                                                                                       |
| iOS     | The mini login. An SSO user with SSO on gets the provider's sign-in, and then the mini login as well, because the `return` after the provider call is commented out \[[ASK-274](https://github.com/snapfix/docs/blob/main/ASK.md#ask-274-what-should-an-ios-single-sign-on-user-see-when-the-session-expires)]. A phone user with WhatsApp codes on first picks SMS or WhatsApp (`JWTHelper.swift:68-120`, `:276-277`)          | Sign-out, with no message (`JWTHelper.swift:278-279`, `:300-302`)                                                                                                                                                                                                                                                                              |
| Android | The sign-in dialog when a screen is open; otherwise the task fails (`RefreshTokensTask.java:147-153`). Google users are signed out and in again for auto sign-in, Apple and Microsoft users restart their provider sign-in, and everyone else gets the auto sign-in sheet (`app/src/main/java/gmail/com/snapfixapp/utils/LoginDialogUtils.java:81-140`)                                                                         | The logout broadcast (`RefreshTokensTask.java:143-146`), which the home screen handles by signing out with no message (`app/src/main/java/gmail/com/snapfixapp/activity/BusinessListingActivity.java:4269-4318`). A `409` also sends the verification broadcast first, so the home screen opens the verification sheet with the refusal's text |

authpy refuses a renewal with `409`, not `401`: an unknown user, a blocked or deleted token, or an expired token sent without a refresh token (authpy @ 5d5758661c, `app.py:217-328`). So `409` is the common refusal. authpy also renews expired tokens of either type. On the web help pages, a refused guest login also sends the visitor to sign-in with no message.

```mermaid
sequenceDiagram
    participant C as Client
    participant A as authpy
    participant R as Snapfix APIs
    C->>A: Sign in with password, code or SSO
    A-->>C: Access token and refresh token
    C->>R: Request with the access token
    R-->>C: 401 or "token has expired"
    C->>A: Renew with the refresh token
    alt Renewal accepted
        A-->>C: New access token, maybe a new refresh token
        C->>R: Send the request again
        R-->>C: Answer
    else Renewal refused
        A-->>C: 409, 403 or 401
        C->>C: Sign-in dialog or sign-out (see the table)
    end
```

### Server checks on each request

* **api\_php\_live\_v2 `/v1/app`.** The route group lists the middleware `verifyTempPassword`, `verifiedUser`, `set.database.connection`, `authorize`, `blacklist`, `blockedToken` and `rate.limiter` (api\_php\_live\_v2 @ ef3c4319f6, `app/Providers/RouteServiceProvider.php:37-46`). A missing, expired, badly signed or non-access token gets `401`, and so does a blocked one (`app/Http/Middleware/VerifyTempPassword.php:46-75`, `app/Services/JwtAuthService.php`, `app/Http/Middleware/BlockedToken.php:41-50`). A token that cannot be decoded at all takes the generic error path, `400` (`app/Http/Responses/ApiResponse.php:39`). A temporary password gets `428` and an unverified email or phone `409`; the rules and exceptions are in [What a user token does not prove](https://docs.snapfix.com/engineering-reference/api.md#what-a-user-token-does-not-prove). The admin routes skip the temporary-password, blacklist and blocked-token checks.
* **Fresh tokens.** Deleting the account needs a token from a fresh sign-in; otherwise the answer is `406` (`app/Http/Controllers/v1/Versions/v1_0/App/UserController.php:195-196`), and the web opens the mini sign-in dialog (web\_app\_v2 @ 0989b8e685, `src/app/components/profile-drawer/profile-delete/profile-delete.component.ts:89`). With a fresh token, a password change does not ask for the old password (`app/Http/Requests/v1/User/UpdatePasswordRequest.php:18-22`, `:44-47`).
* **apipy.** Most routes use `@jwt_required()`; an expired token gets `401` with apipy's own body (apipy @ 0e83c85e5a, `app.py:179-185`).
* **php-apis.** The dispatcher reads the token, but actions take the user from the request; see [User tokens](https://docs.snapfix.com/engineering-reference/api.md#user-tokens).

### Sign-out

Sign-out is local on every client: no server route ends a session. authpy, apipy, php-apis and api\_php\_live\_v2 have no sign-out route, and authpy's revoked-token loader is commented out (authpy @ 5d5758661c, `app.py:148`). The only server-side stop is a staff block of a device or user, which marks the tokens `blocked` in [token\_jwt](https://docs.snapfix.com/engineering-reference/db/tables/token_jwt.md) (`model/feature_token_ops.py:650-668`, `:767`, `:796`); a renewal with a blocked refresh token is refused (`:301-303`).

| Client  | Clears                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Keeps                                                                                                                         |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Web     | All local and session storage except six keys: device ID, saved marketing popup IDs, sort order, locale, first-use flags and app version; then the account cache. Opens `/auth/sign-in` with no message (web\_app\_v2 @ 0989b8e685, `src/app/services/auth/auth-helper/auth-helper.service.ts:123-148`)                                                                                                                                                                                                                                                             | —                                                                                                                             |
| iOS     | `isLoggedIn`, the stored push token, the current site and filters, the user's group data in memory; opens the login screen as the root, with no message (ios @ aa31967ac8, `AppUtility.swift:4455-4520`)                                                                                                                                                                                                                                                                                                                                                            | `TOKEN_SAVED` is never removed. Dropping the local tables is commented out (`AppUtility.swift:4465`), so the local data stays |
| Android | After a confirmation: the selected site, `LoggedId`, the device token, alarms and notifications; opens Login and clears the back stack (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/activity/MyProfileActivity.kt:2340-2372`; the logout broadcast does the same at `app/src/main/java/gmail/com/snapfixapp/activity/BusinessListingActivity.java:4286-4318`). The auto sign-in sheet's "Log out" clears `LoggedId` and the device token but not the selected site (`app/src/main/java/gmail/com/snapfixapp/utils/LoginDialogUtils.java:116-131`) | `AccessToken` and `RefreshToken`: `TokenPrefUtil` has no way to clear them. The local database stays                          |

* **Push stops for the device.** At sign-out each app saves its device again without a push token, so the senders skip it ([POST /fbu\_devicetoken](https://docs.snapfix.com/engineering-reference/api/notifications.md#post-fbu_devicetoken)).
* **iOS calls a legacy route.** Five seconds after sign-out, iOS posts the access token to a `/signout` route on a separate host that no repo serves (`AppUtility.swift:4459-4463`, `SVProgressHUD/JWTHelper.swift:16-18`, `:313-321`) \[[ASK-270](https://github.com/snapfix/docs/blob/main/ASK.md#ask-270-is-the-legacy-sign-out-route-that-ios-calls-still-live)].
* **Deleted accounts** are covered by [Profile deleted](https://docs.snapfix.com/how-the-apps-work/screens/account/profile-deleted.md).

### Signing in as another user on the same device

* **Android.** A sign-in as a different user from the last one opens [Download data](https://docs.snapfix.com/how-the-apps-work/screens/account/download-data.md); the same user goes to the home screen (`app/src/main/java/gmail/com/snapfixapp/activity/LoginActivity.kt:466-477`).
* **iOS.** A sign-in as a different user drops the local data tables (all but the API endpoint table) with no check for changes not yet sent (`SnapFix/SmsEmailLogin/SmsEmailLoginVC/SmsEmailLoginVC.swift:499-503`). The home screen warns about unsent tasks elsewhere (`SnapFix/HomeVC.swift:2758-2766`).

## Switching sites

The product rules are in [Switching sites](https://docs.snapfix.com/product/features/groups/site-switching.md) and the control is the [Site switcher](https://docs.snapfix.com/how-the-apps-work/screens/groups/site-switcher.md). This part covers what each client saves and reloads.

* **Web.** The side menu ignores a click on the current site and logs `account_select_parent` for any other (web\_app\_v2 @ 0989b8e685, `src/app/components/side-menu/account-list-menu/account-list-menu.component.ts:139-165`). A multi-site opens [My sites](https://docs.snapfix.com/how-the-apps-work/screens/console/my-sites.md) at `/multi-site/my_sites`. A site is saved with `switchAccount`, which clears the selected group, task and room, drops the account cache when the site changes, and stores the site's region URLs (`phpBaseUrl`, `pyBaseUrl`) before any site request goes out (`src/app/services/account/account-helper/account-helper.service.ts:158-181`, `:235-241`). The current page stays only if its first path segment is `fix`, `plan`, `assets`, `comply`, `chat`, `housekeeping`, `dashboard-reports`, `account` or `admin-reports`; any other page goes to `/fix` (`:218-233`). Choosing a site in the Multi-Site Console saves it and opens `/fix` (`src/app/pages/multisite-console/sites/sites.component.ts:95-102`). The site list comes from [GET /v1/app/parents](https://docs.snapfix.com/engineering-reference/api/console.md#get-v1appparents) (`src/app/services/account/account-http/account-http.service.ts:29-35`).
* **iOS.** A site in the same region is saved at once as `selectedParentId`; a site in another region is only announced (ios @ aa31967ac8, `SnapFix/ParentSwither/SelectParentVC.swift:366-380`). For another region the app needs a connection, and otherwise shows "Interenet connection required to change Snapfix Account!" (spelled so in the strings file). It downloads that region's sites and their rooms, areas and checklists, and saves the new site only after the download (`SnapFix/BusinessListing+ParentSwither.swift:142-145`, `:198-252`, `:258-278`). The Fix tab returns to the page last used on that site (`SnapFix/FixTabPageViewController.swift:101-105`).
* **Android.** The site sheet leaves out churned sites and, when the saved site is not in its list, selects the first listed site without asking (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/bottomSheet/ParentSwitcherBottomSheet.java:156-234`). A tap on another site goes to `BusinessViewModel.selectParent` (`app/src/main/java/gmail/com/snapfixapp/activity/BusinessListingActivity.java:3799-3815`). A site in the same region is stored at once and the screens reload; changing the site also clears the Simon sessions (`app/src/main/java/gmail/com/snapfixapp/viewModels/BusinessViewModel.java:414-464`, `app/src/main/java/gmail/com/snapfixapp/utils/PrefUtils.java:236-241`). For another region it checks the connection first, then stores the site, empties the group lists and loads the region's data (`BusinessViewModel.java:466-520`). If the Fix tab is open, it reopens the Fix page last used on that site (`BusinessListingActivity.java:3805-3815`).
* A user whose sites have no groups is signed out by the apps \[[ASK-38](https://github.com/snapfix/docs/blob/main/ASK.md#ask-38-should-a-user-whose-sites-have-no-groups-be-signed-out)]. On the web, a marketing popup for the new site waits for the next check.

**Blocked sites.** The token lists the sites the user is blocked from in `user_claims.exc_parents` ([User tokens](https://docs.snapfix.com/engineering-reference/api.md#user-tokens)); staff block a user per site with `POST /block-users` ([Users API](https://docs.snapfix.com/engineering-reference/api/users.md)).

* **Web.** `checkAndFilterBlockedAccounts` removes those sites from the list. If the current site is blocked, it moves to the first remaining site and opens `/fix`; with no site left the list is empty (`account-helper.service.ts:63-95`). It runs after every renewal (`auth-token.service.ts:72`).
* **iOS.** `ParentExclusionManager.extractJWTTokenAndSave` keeps the list. If the selected site is blocked, it clears the selection and shows the main screen; if the device holds no site at all after a renewal, it signs out (`Managers/ParentExclusionManager.swift:15-37`).
* **Android.** `JwtUtils.extractTokenForExcludeParentList` saves the list and, when the user is signed in, sends the recreate broadcast. The check that would move the user off a blocked selected site is commented out (`app/src/main/java/gmail/com/snapfixapp/utils/JwtUtils.java:47-80`).

## Notifications and emails

### Push

What each push says and when it is sent is in [Push notifications](https://docs.snapfix.com/product/features/notifications/push-notifications.md).

* **Registration.** iOS and Android send the device's push token and notification switches to [POST /fbu\_devicetoken](https://docs.snapfix.com/engineering-reference/api/notifications.md#post-fbu_devicetoken). The web registers no device: its endpoint list names the route (web\_app\_v2 @ 0989b8e685, `src/app/shared/enums/endpoints.enum.ts:55`), but no code calls it.
* **Devices.** Rows live in [firebase\_user\_device\_token](https://docs.snapfix.com/engineering-reference/db/tables/firebase_user_device_token.md); only the newest row of each device counts (api\_php\_live\_v2 @ ef3c4319f6, `app/Services/UserDeviceService.php:10-24`). Whether production has the group device-token table is open \[[ASK-169](https://github.com/snapfix/docs/blob/main/ASK.md#ask-169-does-production-have-the-group-device-token-table)].
* **Senders.** Two backends send pushes, and two others ask one of them to:
  * apipy's sender, `_initNotificationV2`, behind every apipy push route. Who gets what and which pushes are silent is in [Push delivery](https://docs.snapfix.com/engineering-reference/api/notifications.md#push-delivery).
  * api\_php\_live\_v2's `NotificationService` queues `SendFcmNotification` jobs, one for visible and one for silent pushes (`app/Services/NotificationService.php:108-150`), sent through the Laravel FCM channel (`app/Notifications/FeatureFcmNotification.php:41-43`). `TokenService::getDeviceTokens` sorts the devices into the two lists (`app/Services/TokenService.php:106-147`).
  * php-apis calls apipy's `req-to-notify-group-admin` and `req-to-notify-user-on-new-userbusiness` (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:11359`, `:24124`, `:26130`), and authpy calls `req-to-notify-user-for-qr-job` and `req-to-notify-site-admin` (authpy @ 5d5758661c, `model/feature_qrform.py:972`, `model/feature_user_auth.py:1294`). The routes are listed under [Related routes](https://docs.snapfix.com/engineering-reference/api/notifications.md#related-routes).
* **Switches.** The per-type switches live in [tPri\_UserNotifSettings](https://docs.snapfix.com/engineering-reference/db/tables/tpri_usernotifsettings.md), are read by [GET /user-notification-settings](https://docs.snapfix.com/engineering-reference/api/notifications.md#get-user-notification-settings) and are changed on [Notification settings](https://docs.snapfix.com/how-the-apps-work/screens/notifications/settings.md). Their defaults are open \[[ASK-171](https://github.com/snapfix/docs/blob/main/ASK.md#ask-171-what-should-four-notification-switches-default-to)]. Android saves switch changes only when the user leaves the screen, and neither app says when saving fails.
* **Mute.** A member who muted a group gets only silent pushes for it ([Push delivery](https://docs.snapfix.com/engineering-reference/api/notifications.md#push-delivery), [PUT mute](https://docs.snapfix.com/engineering-reference/api/notifications.md#put-v1appnotificationbusinessuuidmute)).
* **Silent by design or by fault.** Planned-task reminders, the sign-up notice to group admins and chat attachments other than text \[[ASK-170](https://github.com/snapfix/docs/blob/main/ASK.md#ask-170-should-photos-videos-voice-notes-and-documents-in-a-task-chat-alert)] go out silent.

**Showing a push on the device.**

* **iOS, app open.** The payload's `body` is read; `type` may be a number or a string (ios @ aa31967ac8, `Appdelegate/AppDelegate.swift:827-838`). Type `98` reloads the group's data (`:839-841`). A chat message (type `97`) shows no banner while that chat is open, and a banner with sound otherwise (`:842-851`). For other pushes, the checks for a reload in progress, an open chat of the same task and a push without an alert call the completion with no banner but do not return, so the completion is called again with banner and sound (`:872-885`). A malformed body can crash the app.
* **Android.** A push with a `silent` flag follows the flag; a push without one goes through the device's own switch check (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/service/MyFirebaseMessagingService.java:275-279`). That check runs before the type is read, so it sees type `-1` and no group (`:269`, `:278-280`). Due-date reminders and admin approval requests show even when silent (`:281-283`) \[[ASK-166](https://github.com/snapfix/docs/blob/main/ASK.md#ask-166-should-android-show-due-date-reminders-and-approval-requests-when-the-user-has-turned-notifications-off)], and a group muted on the device stays hidden (`:315-319`).

**Tap routing.** A tap opens a screen from the push's `type` and its group (`businessUUID`). Each receiving screen describes its own entry, for example [Task detail](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md).

* **iOS.** The tapped payload is stored (`Appdelegate/AppDelegate.swift:1038-1062`). When the app starts from the tap, the splash screen reads it: a chat push opens the Fix tab and the chat (`SnapFix/SplashScreen/SplashScreenVC.swift:120-143`). Otherwise `handleClickNotification` handles it (`AppDelegate.swift:1063-1188`): a chat push opens the chat; type `51` opens the Fix tab; any other push selects the group's site, opens the Plan tab for an asset register or the Fix tab for a task group, and opens the group and the task. A group that is not on the device opens the group list and the task.
* **Android.** The tap intent depends on the type (`MyFirebaseMessagingService.java:492-520`): a schedule push opens the group list in schedule mode; a push about a user added to a group, or a sign-up sent to the group admin, opens the group list; otherwise an asset register opens its asset list, and a task group opens its task list with the task (and the chat message, for a chat reaction). A group that is not on the device opens the task list with the group only. An alert message opens the splash screen with its text (`:523-525`).

### Links in emails, texts and pushes

Links go through the dynamic-link page, which sends a computer or web view to the web's [Account access](https://docs.snapfix.com/how-the-apps-work/screens/account/account-access.md) page with the link's `ctx`, and a phone to the app and then, after 1.5 seconds, to the store (dynamic-link @ 4d1cd0eb62, `src/app/components/main/main.component.ts:48-82`). The details are in [Deep link](https://docs.snapfix.com/how-the-apps-work/screens/account/deep-link.md); what each email says is in [Email links](https://docs.snapfix.com/product/features/account/email-links.md).

### Email

Four backends send email. Only setting names are listed here.

| Sender                                                                                                | Transport                                                                                                                                                                                                                                                                                                                                                                | Settings (names only)                                                                                                                                                                                                                                                                                                                        |
| ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| api\_php\_live\_v2, `SendEmail` job (api\_php\_live\_v2 @ ef3c4319f6, `app/Jobs/SendEmail.php:31-35`) | The mailer named by `MAIL_MAILER`, `smtp` by default (`config/mail.php:16`). `mailgun`, `ses` and `internal` have their own providers; any other value uses SMTP (`app/Services/Mail/EmailProviderResolver.php:12-31`). `internal` posts the mail with a Basic login to the internal messaging service (`app/Services/Mail/Transports/InternalEmailTransport.php:49-50`) | `MAIL_MAILER`, `MAIL_HOST`, `MAIL_PORT`, `MAIL_USERNAME`, `MAIL_PASSWORD`, `MAIL_FROM_ADDRESS`, `MAIL_FROM_NAME` (`config/mail.php`); `MAILGUN_DOMAIN`, `MAILGUN_SECRET`, `MAILGUN_ENDPOINT` (`config/services.php:18-20`); `MASSAGING_INTERNAL_URL`, `MASSAGING_INTERNAL_USERNAME`, `MASSAGING_INTERNAL_PASSWORD` (`config/mail.php:91-93`) |
| php-apis (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:4370-4430`)           | Amazon SES through `AWSSESHelper::sendEmail`, from `noreply`. `sendMailThroughMailGun` uses SES too                                                                                                                                                                                                                                                                      | `AWS_S3_REGION`, `AWS_ACCESS_KEY`, `AWS_SECRET_KEY` (`html/api/snapfix/seshelper.php:84-88`)                                                                                                                                                                                                                                                 |
| authpy (authpy @ 5d5758661c, `ses.py:14-23`)                                                          | Amazon SES through boto3                                                                                                                                                                                                                                                                                                                                                 | `AWS_REGION`, `AWS_ACCESS_KEY`, `AWS_SECRET_KEY`, `SES_SENDER` from `security.json`                                                                                                                                                                                                                                                          |
| apipy (apipy @ 0e83c85e5a, `ses.py:14-15`)                                                            | `sendEmailThroughSES` returns at once through `sendEmailThroughProxyAPI`, which posts the mail to the internal messaging service with a login written in the code (`ses.py:57-67`). The SES code after it never runs                                                                                                                                                     | None read: the login is in the code                                                                                                                                                                                                                                                                                                          |

The value of `MAIL_MAILER` in production is open \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)], and so is which provider each backend really uses \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. Who gets the daily group email is open \[[ASK-121](https://github.com/snapfix/docs/blob/main/ASK.md#ask-121-what-sends-the-daily-group-email-and-to-whom)], and whether one-time codes go by WhatsApp \[[ASK-34](https://github.com/snapfix/docs/blob/main/ASK.md#ask-34-is-whatsapp-delivery-of-one-time-codes-meant-to-ship)].

### Marketing popups

Popups are set in the staff admin app ([Marketing popups](https://docs.snapfix.com/how-the-apps-work/screens/staff/marketing-popups.md), feature [Marketing popups](https://docs.snapfix.com/product/features/notifications/marketing-popups.md)). Whether the daily window follows the popup's time zone is open \[[ASK-167](https://github.com/snapfix/docs/blob/main/ASK.md#ask-167-should-a-marketing-popups-daily-window-follow-the-popups-time-zone)], and whether language-targeted popups reach iOS is open \[[ASK-168](https://github.com/snapfix/docs/blob/main/ASK.md#ask-168-does-a-language-targeted-marketing-popup-reach-ios-users)].

## Date and number formats

### Time zones

* **Server.** The Laravel clock is UTC (api\_php\_live\_v2 @ ef3c4319f6, `config/app.php:104`); whether the servers really run on UTC is open \[[ASK-55](https://github.com/snapfix/docs/blob/main/ASK.md#ask-55-do-the-scheduler-and-api-servers-run-on-utc)]. A site has its own zone, `timezone_name` in [tPri\_Parent](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parent.md), and planner and reminder times follow it ([Dates and times](https://docs.snapfix.com/engineering-reference/api.md#dates-and-times), [Reminders](https://docs.snapfix.com/product/features/notifications/reminders.md)).
* **Web.** Every call carries the browser's zone name (`device-tz`) and offset (`device-tz-offset`), set by the interceptor from `HttpService` (web\_app\_v2 @ 0989b8e685, `src/app/services/http/http.service.ts:123-124`).
* **Apps.** Neither iOS nor Android sends either header; a search for `device-tz` in both repos finds nothing.
* **Date filters.** The `/v1/app` task filters for due date, due today, overdue, created date and activity date read `device-tz-offset` and fall back to `GMT+0000` (`app/Traits/Filters/DueDate.php:18`, `ActivityDate.php:14`, `CreatedDate.php:14`, `DueToday.php:13`, `OverDue.php:16`; used by `app/Http/Filters/App/JobFilter.php:37-46`). The web sends `device-tz-offset` with every call (web\_app\_v2 @ 0989b8e685, `src/app/services/http/http.service.ts:124`). The apps filter their task lists on the device; their date filter code builds saved feed-filter preferences, not these requests (ios @ aa31967ac8, `SnapFix/FreeTier/Extension+Helper.swift:538-539`; android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/utils/FeedFilterMapper.kt`, used only by `UserPreferenceRepository.kt:200-208`).
* **Other time-zone defects:** housekeeping "today" starts at midnight UTC; Android's "tomorrow" is wrong behind UTC; reminder dialogs do not say the time is the site's and send the device's zone; delivery times mix UTC and local time; survey dates are read in the browser's zone; popup dates break with a day-first locale.

### Web

* **Language.** `LocaleService.getLocale` uses the `locale` saved in local storage; with none, it picks the browser's language (an exact match first, then the base language, so `en-GB` becomes `en`), and otherwise English (web\_app\_v2 @ 0989b8e685, `src/app/services/locale/locale.service.ts:18-29`, `:46-63`). Which languages each platform offers is open \[[ASK-37](https://github.com/snapfix/docs/blob/main/ASK.md#ask-37-which-languages-should-each-platform-offer)]. Some chat texts and dates stay in English.
* **Dates.** `DatetimePipe` shows `MMM DD HH:mm` (such as "Nov 15 09:30"), or `MMM DD` with `showTime` off. A date in another year shows `MMM DD YYYY`, with the time only when the caller sets `showTimeWithYear`. A `specialFormat` replaces all of this. It formats with moment, in the stored locale and the browser's zone (`src/app/pipes/datetime/datetime.pipe.ts:16-41`).
* **Other date layouts.** Some pages pass their own format: the housekeeping task preview uses `HH.mm MMM DD, YYYY` (`src/app/pages/housekeeping/task-preview-drawer/task-preview-drawer.component.html:121`, `:130`); the planned-task due date uses `ddd MMM DD YYYY` with `h:mm A` (`src/app/pages/plan/planned-task/planned-task-due-date/planned-task-due-date-dialog/planned-task-due-date-dialog.component.ts:75-76`), and so do the planned-task times and date field (`src/app/pages/plan/planned-task/planned-task-details/planned-task-details.component.ts:432`, `:464`; `src/app/pages/plan/planned-task/planned-task-details/planned-task-date/planned-task-date.component.ts:44`). The same kind of date reads differently from page to page. Chat times mix 12-hour and 24-hour clocks. The staff admin app's formats are a separate problem, and an asset date on the shared task page in web\_tasks uses the week-numbering year.
* **Numbers.** Cost totals use Angular's `number: '1.2'`: at least two decimal places, up to three (`src/app/pages/task/task-time-cost/task-time-cost-total/task-time-cost-total.component.html:27`). The currency is the site's symbol, or its code when there is none (`src/app/pages/account-settings/account-settings-account-details/account-settings-account-details.component.html:216`). A checklist's percentage shows "100" when complete and two decimals otherwise (`src/app/pages/task/task-checklist/task-checklist-summary/task-checklist-summary.component.ts:57-62`; [Checklist](https://docs.snapfix.com/how-the-apps-work/screens/checklists/checklist.md)).

### iOS

* **Language.** `formatType` uses the app language's locale; in English it uses `en_GB` for formats with `HH:mm`, which keeps a 24-hour clock (ios @ aa31967ac8, `Extensions/Date+String.swift:24-38`).
* **Zone.** Dates use the device's zone; the line that would set GMT is commented out (`Date+String.swift:35-36`).
* **Formats.** Full date and time `dd MMM yyyy HH:mm` (`:84-85`), the dashboard `EEE dd/MM/yyyy` (`:87-88`), a header format `dd MMM yyyy, HH:mm:ss z` (`:174-176`).

### Android

* **Language.** `LocaleHelper.getAppLocale` uses the language picked in the app, or else the device's, and always forces Latin digits (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/utils/LocaleHelper.kt:28-62`).
* **Display.** `DateUtils.displayFormat` formats in that locale (`app/src/main/java/gmail/com/snapfixapp/utils/DateUtils.java:61-63`). The patterns are `EEE dd/MM/yyyy` for dates, `hh:mm a` (12-hour) for times, `EEE MMM dd yyyy` for due dates, `MMM dd yyyy HH:mm` for chat dates and `MMMM dd yyyy` for the dashboard's activity period (`:49-55`, `:288`, `:683-685`).
* **Fixed English.** Some values use fixed English patterns: `dd/MM/yy HH:mm` for `getDisplayDateTime`, `HH:mm` for chat times, `HH:mm:ss` for activity times, and `yyyy-MM-dd HH:mm:ss` for storage (`:35-47`, `:245-247`, `:291-296`). Job chat dates use `MMM d` or `MMM d, yyyy` (`app/src/main/java/gmail/com/snapfixapp/fragment/JobChatFragment.java:9436-9440`) and `MMM dd HH:mm` (`:14526`) in the app locale.
* **Zone.** Stored times are converted with the device's zone (`DateUtils.java:173-197`).
* **Numbers.** `DecimalFormat` takes the device's decimal symbol: `###.#` for file sizes (`app/src/main/java/gmail/com/snapfixapp/utils/FileUtils.java:454`) and `.##` for two-decimal values (`JobChatFragment.java:14119`, `app/src/main/java/gmail/com/snapfixapp/bottomSheet/AddCostBottomSheet.java:137`).

The platforms disagree: the web and iOS show 24-hour times in English, Android 12-hour. Which format each platform should show is open \[[ASK-271](https://github.com/snapfix/docs/blob/main/ASK.md#ask-271-which-date-and-time-format-should-each-platform-show)].

## Global errors

The API error bodies and status codes are in [Responses](https://docs.snapfix.com/engineering-reference/api.md#responses).

### Web

* **One path for most calls.** Calls go through `AuthInterceptor` (registered in web\_app\_v2 @ 0989b8e685, `src/app/app.config.ts:95-99`) and `HttpService.request` (`src/app/services/http/http.service.ts:43-71`).
* **Alert.** An answer that is not a success (`result`, or `status` `success` or `true`) shows the server's `message` in the alert dialog, or "Internal server error" when there is none, in every language. A failed request does the same, except for `401`, `406`, `409` and `428`, which have their own handling (`:182-191`, `:243-251`; the codes in `src/app/shared/enums/global.enum.ts:13-18`). Both are skipped when the call sets `skipErrorMessage` (`:55`, `:246`).
* **The answer still reaches the caller** after the alert (`:67`), so a caller that does not check it can show success after a refusal.
* **One dialog at a time.** `AlertService.openAlertDialog` returns `false` while a dialog is open, so a second error at that moment is not shown (`src/app/services/alert/alert.service.ts:26-40`).
* **The interceptor's own dialogs.** A `409` opens the verification dialog and a `428` the create-password dialog, for every call except the renewal (`src/app/services/auth/auth-interceptor/auth.interceptor.ts:82-85`).
* **Toasts.** `NotificationService` has info, warning, error and success toasts, which last 3000 ms unless the caller sets a duration, and a loading toast that stays until it is closed (`src/app/services/notification/notification.service.ts:10-40`).
* **Uncaught errors** go to Datadog through `provideDatadogErrorHandler()` (`src/app/app.config.ts:47`).
* **No error page.** An unknown route redirects to `/fix` in the app (`src/app/app.routes.ts:202`) and to sign-in in the auth area (`src/app/pages/auth/auth.routes.ts:15`).

### iOS

* **Responses and codes.** `APIManager.handleResponse` (ios @ aa31967ac8, `APIManagers/APIManager.swift:2101-2139`) renews the session on "token has expired" or `401`, opens the verification screen on `409` and the password screen on `428` (both only when the password screen is not already required: `openVerifyAlert`, `:2027-2052`; `openPasswordScreen`, `:2014-2026`). A `result` of `true` is a success; anything else is a failure, and the calling screen decides what to show.
* **A failed call can get no answer.** In `apiCallWithUrlString`, a failed request calls its completion only when the response has a text body (`:1407-1416`). A failure with no body, such as a lost connection, never calls it.
* **Texts.** The strings "Something went wrong" and "Something went wrong. Please try again." exist (`SnapFix/Localization/en.lproj/Localizable.strings:1510-1511`), as does "Your session has expired. Please login again to continue." (`:1418`).

### Android

* **Parsing.** `ParsingManager.parseData` (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/network/ParsingManager.java:110-151`) passes the server's message to the caller when `success` is false. A `401` becomes "The incoming token has expired". A `409` or `428` sends the verification broadcast, which the screens that listen for it turn into the verification sheet or the create-password screen. Every other failure, a `403`, and a request that fails outright pass the English "Something went wrong. Please try again.", although `strings.xml` has a translated `something_went_wrong`. The background variant is `parseDataBlocking` (`:84-100`).
* **Offline.** Some actions check the connection first with `InternetUtils.checkAndShowAlert`, for example a site switch to another region (`app/src/main/java/gmail/com/snapfixapp/viewModels/BusinessViewModel.java:415-417`).
* An empty message reaches the help screens when a request gets no answer.

### Across the apps

* The apps show one message for every document error.
* Some Laravel errors return message keys, not text. Admin route auth errors answer `400` "Something went wrong". A failed password call writes the password to the log. With `APP_DEBUG` on, errors include stack traces (`app/Http/Responses/ApiResponse.php:46-51`).

## Offline sync

The apps keep a local copy of the site's data, filled by read calls such as [POST /v1/app/tasks/data](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasksdata), and upload changes when they can. On [Home](https://docs.snapfix.com/how-the-apps-work/screens/tasks/home.md), Snap and "+" still create tasks offline. [Feed](https://docs.snapfix.com/how-the-apps-work/screens/tasks/feed.md) and [Task detail](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md) say which actions need the server.

### iOS

* **Local store.** A local SQLite database (ios @ aa31967ac8, `Managers/DBManager/DBSchemaManager+CreateTable.swift`). Rows carry `fSyncStatus` (`Constants.swift:721`): `0` up to date, `1` not synced, `2` error (`Constants.swift:333-338`).
* **Triggers.** The network watcher calls `networkReachable()` when the connection returns, which updates the counter, starts `TaskManager.getPendingTask` and sends pending push messages (`Managers/SyncManager.swift:23-43`, `:98-106`). `startService` starts the background task only with a connection (`:75-95`).
* **Queue.** A `getPendingTask` call during a run marks another run to follow (`Managers/TaskManager.swift:131-152`). A file upload is tried three times (`LIMIT_RETRY`, `Constants.swift:390`); after the third failure the row is marked as an error (`TaskManager.swift:514-526`, `:582-590`).
* **Offline alert.** When the connection drops, an alert opens only for one reachability state, which the code reads as "mobile data is off for the app": "You must be connected to the Internet to carry out this task. Please connect and try again.", with "GO TO SETTINGS" (`SyncManager.swift:45-67`). Other states show nothing.
* **Known problems.** "Sync all Data" is hidden in the side menu. The offline planned-tasks list shows ordinary tasks. A first download that fails offline blames the account. A voice task is dropped with no message when the session has expired.

### Android

* **Local store.** Room. Sync status values are `0` complete, `1` not synced, `2` updated, `3` error (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/model/ConstantData.java:79-82`), not the same numbers as iOS.
* **The sync job.** `DataSyncStarterUtils.start` queues one unique WorkManager job, `snapfix_data_sync_work`, that runs only with a connection; while one is queued or running, a new request is dropped (`KEEP`: `app/src/main/java/gmail/com/snapfixapp/room/utils/DataSyncStarterUtils.kt:14-34`). The job runs `SyncAllDataUseCase` (`app/src/main/java/gmail/com/snapfixapp/domain/usecase/SyncAllDataUseCase.kt`); a start during a run sets a flag, and the job runs once more when it finishes (`app/src/main/java/gmail/com/snapfixapp/service/DataSyncWork.kt:33-72`). A few places start the older foreground `DataSyncService` instead (the profile screen, the task tag, asset and location dialogs, the sign-in dialog), which reruns the same way (`app/src/main/java/gmail/com/snapfixapp/service/DataSyncService.kt:43-76`).
* **Triggers.** Screens call `BaseActivity.startSyncService` after saving a change (`app/src/main/java/gmail/com/snapfixapp/activity/BaseActivity.kt:679-692`); a sign-in from the auto sign-in sheet starts a sync (`app/src/main/java/gmail/com/snapfixapp/utils/LoginDialogUtils.java:107`); and the network receiver starts one, checks the groups' tasks and reloads the site data when the connection returns (`app/src/main/java/gmail/com/snapfixapp/service/NetworkChangeReceiver.java:63-79`, registered at `app/src/main/java/gmail/com/snapfixapp/activity/BusinessListingActivity.java:487-497`). The receiver skips the first change after it is registered (`NetworkChangeReceiver.java:48-59`).
* **Errors.** After each run, rows in error go back to "not synced", so the next run tries them again (`SyncAllDataUseCase.kt:55`, `app/src/main/java/gmail/com/snapfixapp/data/repository/SyncRepository.kt:924-927`, for example `app/src/main/java/gmail/com/snapfixapp/room/dao/AreaDao.kt:38-39`).
* **Token renewal in the sync.** `SyncRepository.withRetry` wraps the sync's posts and the contractor notice (`SyncRepository.kt:939`, `:950`, `:1229`). On an expired token it renews once through `RefreshTokensTask` and sends again; a second expiry in that call goes to the caller. Otherwise it waits 1 second, tries again, waits 2 seconds and makes a last call: three calls in all (`:1035-1057`, limits at `:1399-1402`).
* **Texts.** The offline counter reads "You are offline." and "The count indicates the number of tasks to be updated when you are online." (`app/src/main/res/values/strings.xml:2076`).
* **Known problems.** When the site-data request returns an unexpected message, the reload screen deletes the local data. The schedule list spinner never stops offline. Site details changes are lost when the user cancels the no-connection alert.

### Web

The web has no offline mode and no connection check in `src/app/` (web\_app\_v2 @ 0989b8e685). Requests fail and show the error alert ([Global errors](#global-errors)).

### Rules across the apps

* **Sign-out** keeps the local data on both apps ([Sign-out](#sign-out)); iOS drops it when another user signs in ([Signing in as another user](#signing-in-as-another-user-on-the-same-device)).
* **A site in another region** needs that region's data: iOS downloads it and then saves the site, Android saves the site and then loads it ([Switching sites](#switching-sites)).

## Permission checks

The roles and what each may do are in [product/roles.md](https://docs.snapfix.com/product/roles.md). This part says where the code checks them. Only the server's checks protect data; the client checks decide what is shown and where a user is sent.

| Where            | Check                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | What it does                                                                                                                                                                                                                                         |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Web routes       | `authAdminGuard` (site admin or group admin), `authComplyGuard` (site admin), `authHousekeepingGuard` (site admin, housekeeping on, no multi-site), `authChatGuard` (chat on), `authMultisiteGuard` (a multi-site chosen) (web\_app\_v2 @ 0989b8e685, `src/app/services/auth/auth-guard/*/`: `auth-admin.guard.ts:13`, `auth-comply.guard.ts:11`, `auth-housekeeping.guard.ts:12`, `auth-chat.guard.ts:12`, `auth-multisite.guard.ts:13`)                                                                                                             | Sends the user to `/fix`. They read the site saved in the browser                                                                                                                                                                                    |
| Web controls     | `PermissionService` (below); the side menu's admin section shows when the site role is `Admin` (`src/app/components/side-menu/account-list-menu/account-list-menu.component.ts:160`)                                                                                                                                                                                                                                                                                                                                                                  | Shows or hides controls                                                                                                                                                                                                                              |
| iOS controls     | For example `BusinessContext.groupSettingScreenAcess()`: admins, or members with `perBusSettingsScreenAccess` (ios @ aa31967ac8, `SnapFix/Asset/ViewModel/BusinessContext.swift:189-191`); the QR code and delete rows for admins only (`SnapFix/BusinessDetailsVC.swift:786-791`); task creation in a room for active members with `perJobCreateNew`, or admins (`SnapFix/RoomsView/SelectGroup/SelectGroupVC.swift:284`); housekeeping approval for admins or self-checkers (`SnapFix/HouseKeeping/View Model/HouseKeepingViewModel.swift:358-360`) | Shows or hides actions                                                                                                                                                                                                                               |
| Android controls | The member's user type compared with the admin type (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/viewModels/TaskViewModel.java:991-994`, `app/src/main/java/gmail/com/snapfixapp/repository/JobRepository.kt:222-226`); on the Assets page, admins open group settings and others the group purpose screen (`app/src/main/java/gmail/com/snapfixapp/fragment/AssetGroupListingFragment.java:597-604`)                                                                                                                               | Shows or hides actions                                                                                                                                                                                                                               |
| API, `/v1/app`   | `app/Traits/Authenticated.php`: `isAdminOfBusiness` (`:20-31`), `isReadOnly` (`:47-58`), `hasPermission` (`:66-77`), `getPermissions` (`:84-95`), and the policies in `app/Policies/`, for example `JobPolicy.php:105-112` (api\_php\_live\_v2 @ ef3c4319f6)                                                                                                                                                                                                                                                                                          | Checks the caller's role and permissions in each group. Calls on the admin and internal route groups pass these checks; the platform comes from the route name, not the request (`app/Helpers/common.php:413-424`)                                   |
| API, admin       | `app/Http/Middleware/AuthorizeAdminApi.php` (bearer token) and `app/Http/Middleware/WebAdmin.php:23` (the staff flag)                                                                                                                                                                                                                                                                                                                                                                                                                                 | Lets only staff use the admin routes. Whether the token is checked with authpy's key is open \[[ASK-202](https://github.com/snapfix/docs/blob/main/ASK.md#ask-202-does-the-laravel-admin-api-check-tokens-with-the-key-that-authpy-signs-them-with)] |

**The web's `PermissionService`** (web\_app\_v2 @ 0989b8e685, `src/app/services/permission/permission.service.ts`):

1. `group` checks, in order: the paywall key (`:20-23`); an `Inactive` membership, unless the caller ignores it (`:26-29`); the group role `Admin`, which allows everything after this point (`:32`); the `approvalRequired` key, which everyone else is denied, so only admins see the "Require approval" switch (`:34-36`; used in `src/app/pages/task/task-actions/task-actions.component.ts:325`, `:363-368`, and `task-actions.component.html:146`), while approving and rejecting follow [Task detail](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md); missing group settings (`:39`); and last the permission key in the member's group permissions (`:42-47`).
2. `task` denies a locked or archived task, and a task with a time range outside that range (`:50-64`). A cleaning or inspection task with a time range, or one with an assignment type, is allowed at once, before any group check, and so is every task with a time range whose `assignmentType` is missing (`:56-59`) \[[ASK-281](https://github.com/snapfix/docs/blob/main/ASK.md#ask-281-should-the-web-let-anyone-act-on-time-ranged-housekeeping-and-assigned-tasks)]. The checklist key is then always allowed (`:66-68`); everything else goes to `group` (`:70`).
3. `report` needs the paywall's advanced reporting flag, `webapp_advancedreporting_enabled` (`:73-77`).

**Known gaps.** php-apis acts on the user named in the request, not the token's user, and its task actions do not check access to the task. Five Laravel task endpoints check only that the caller is signed in. apipy's staff routes accept any user's login, and its task routes trust the user in the URL. Which permissions planned tasks should need is open \[[ASK-51](https://github.com/snapfix/docs/blob/main/ASK.md#ask-51-which-permissions-should-planned-tasks-need)]. Each screen doc's "Who can do what" says who may use its controls, for example [Task detail](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md); the site permission data is in [GET /user/{userUUID}/site/{siteUUID}/permission](https://docs.snapfix.com/engineering-reference/api/console.md#get-useruseruuidsitesiteuuidpermission).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.snapfix.com/how-the-apps-work/shared.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
