Repository Public
1<!-- Author: Simon-Pierre Boucher — contact@spboucher.ai -->2<!-- File: docs/SYSTEM-INTEGRATION.md -->3<!-- Description: SP Mail Next — how the apps integrate with the system (push, notifications, extensions, shared state, signing) and what remains manual. -->45# SP Mail Next — system integration67Server contract: `sp-mail/docs/next/ARCHITECTURE-NEXT.md` §3 D-N4, D-N10, §4.2 and `docs/next/PUSH.md`. Code: `Sources/Shared/System/` (app side), `Packages/SPMailSystem` (logic shared with the extensions, unit-tested), `Sources/Widgets`, `Sources/ShareExtension`, `Sources/NotificationService`, `Sources/Intents`.89## Targets and identifiers1011| Target | macOS (Developer ID) | iOS / iPadOS (App Store Connect) |12|---|---|---|13| App | `ai.spboucher.spmail` | `ai.spboucher.spmail.ios` |14| Widgets | `ai.spboucher.spmail.widgets` | `ai.spboucher.spmail.ios.widgets` |15| Share extension | `ai.spboucher.spmail.share` | `ai.spboucher.spmail.ios.share` |16| Notification service | `ai.spboucher.spmail.notifications` | `ai.spboucher.spmail.ios.notifications` |1718Debug builds insert `.dev` after the app identifier (`ai.spboucher.spmail.dev.widgets`, …), use their own shared group and the URL scheme `spmail-dev`.1920## Shared state (decision D-N10)2122Two channels, both written by the app only (`SharedStateWriter`), read by the extensions through `SharedStore`:23241. **Shared keychain access group** `3YM54G49SN.group.ai.spboucher.spmail` — the session token (copied with `SharedContainer.migrateToken`, the app's own entry is kept), the extension state (signed in, preview level, app lock, mailboxes) and the key of the sealed snapshot. Any build signed by the team can declare this group: nothing to register at Apple.252. **App Group container** — the sealed widget snapshot and the share queue (sealed files, 1 MiB chunks). macOS uses the Team-ID-prefixed group `3YM54G49SN.group.ai.spboucher.spmail` (no registration under Developer ID). iOS needs `group.ai.spboucher.spmail` registered and attached to the four App IDs.2627The mail database stays in the app container; no extension opens it. Sign-out and a revoked session clear both channels.2829### App Group on iOS — the one manual step3031The App Store Connect API key used by `Scripts/provision.py` and by automatic signing can turn the *App Groups capability* on (done for the four iOS App IDs), but it cannot create a group identifier nor attach it to an App ID: an archive signed with the group entitlement fails with « Provisioning profile … doesn't support the group.ai.spboucher.spmail App Group ».3233Until that step is done, the iOS Release build is signed **without** the container entitlement and degrades cleanly: token, state and widget snapshot go through the shared keychain group (widgets, the notification service and the share extension all work); the only loss is that a share **with files** cannot be queued for the app — the share extension sends it directly through the API instead (text-only drafts can still be queued).3435To enable the container, once, in the Apple Developer account (Certificates, Identifiers & Profiles):36371. Identifiers → App Groups → **+** → identifier `group.ai.spboucher.spmail`.382. On each of `ai.spboucher.spmail.ios`, `.ios.widgets`, `.ios.share`, `.ios.notifications`: App Groups → Configure → select that group → Save.393. Archive with `SPMAIL_IOS_APP_GROUP=1 Scripts/ios-archive.sh archive` (selects `Config/*-iOS-AppGroup.entitlements`).4041Optional, same place: enabling « Communication Notifications » on `ai.spboucher.spmail.ios` (not a capability type of the API either) and adding `com.apple.developer.usernotifications.communication` to the app entitlements lets the notification service show the sender monogram as an avatar. Without it the notification is delivered as a normal one.4243## Push and notifications4445- Registration: asked once a session exists (never before sign-in); the APNs environment is read from the signature (`PushEnvironmentDetector`), not from the build configuration; re-registration on token, session, app version or locale change; the device is deleted on sign-out. A server without APNs credentials is shown as « Non configuré sur le serveur » and the app announces new mail by itself.46- One notification per message: when the server's push pipeline is active for this device the app posts no local notification; otherwise it posts one, never for a message already announced (ledger + what is in Notification Centre), under the same request identifier as the server's `apns-collapse-id`.47- Categories `MAIL_NEW` (reply with text, mark as read, archive, delete on iOS), `MAIL_REMINDER` (open, remind in one hour, done), `MAIL_ALERT`. Actions run through the sync engine / the normal send path. Reply and delete always require the device to be unlocked; with the app lock on, every mail action does.48- Privacy: the server applies the account's preview level; the notification service extension lowers it further when SP Mail is locked or the device hides senders and subjects. Widgets and Spotlight follow the same level.49- Background work: iOS decides if and when `BGAppRefreshTask` / `BGProcessingTask` run; nothing stays connected while the app is suspended. With an active push pipeline the app asks for a sparse refresh only (cache and widgets), none in Low Power Mode or Low Data Mode.5051## Deep links5253`spmail://conversation?mb=<mailbox>&email=<id>[&thread=<id>]`, `spmail://inbox[?mb=]`, `spmail://compose`, `spmail://search?q=`, `spmail://reminders`, `spmail://share`; `mailto:` on both platforms. Identifiers are opaque; a link never carries content. Universal links (`applinks:`) are not used: the server's `apple-app-site-association` lists `webcredentials` only.5455## Signing and release5657```58Scripts/provision.py --check # dry run59Scripts/provision.py # bundle ids, capabilities, one Developer ID profile per macOS bundle → Build/profiles/60Scripts/release.sh && Scripts/verify-release.sh # macOS: app + three extensions, each with its own profile61Scripts/ios-archive.sh archive && Scripts/ios-archive.sh export62```6364## Development stack with push6566`Scripts/dev-backend.sh start` runs a private backend whose APNs host is the local fake (`Scripts/dev-fake-apns.mjs`, requests logged in `Build/fake-apns.jsonl`). A simulator cannot receive those pushes: `Scripts/system-shots.sh` delivers the same payloads with `xcrun simctl push` and drives the UI (`Tests/SystemUITests`).6768## What only a physical device can verify6970Real APNs delivery (token, environment, topic), the notification service extension (not launched for `simctl push`), widgets on a real Lock Screen, Handoff between devices, background refresh timing, Siri phrases, the macOS Release build launched from a notarised copy.71