# Design This file fixes the parts that are easy to get wrong. Choose the language and framework that fit the person's project; nothing here depends on them. ## Data model Use the database in the `database` input. | Table | Columns | | --- | --- | | `devices` | `id`, `user_id`, `platform`, `token` (unique), `app_version`, `time_zone`, `created_at`, `last_seen_at` | | `pushes` | `id`, `user_id`, `type`, `title`, `body`, `data` (JSON), `collapse_key`, `expires_at`, `created_at` | | `push_deliveries` | `id`, `push_id`, `device_id`, `state`, `attempts`, `send_at`, `provider_id`, `last_answer` | | `push_preferences` | `user_id`, `type`, `enabled`; primary key on the first two | `state` is one of `held`, `waiting`, `sent`, `failed` and `dropped`. `title` and `body` are emptied when every delivery of the push has ended. ## The services Confirm these in Apple's and Google's documentation before building. They were right when this was written. | | Apple (APNs) | Google (FCM) | | --- | --- | --- | | Address | `https://api.push.apple.com/3/device/TOKEN`, over HTTP/2 | `https://fcm.googleapis.com/v1/projects/PROJECT/messages:send` | | Sign-in | A JWT signed with ES256 by the key in `APNS_KEY`, with the key id in its header and the team id as issuer. Reuse it for 50 minutes. | An OAuth access token for the service account in `FCM_SERVICE_ACCOUNT`. Reuse it until 5 minutes before it runs out. | | Which app | Header `apns-topic` with `APNS_BUNDLE_ID` | The project in the address | | Kind | Header `apns-push-type`: `alert`, or `background` for a silent push | `notification` and `data` in the message, or `data` alone for a silent push | | Expiry | Header `apns-expiration`, seconds since 1970 | `android.ttl` | | Replace | Header `apns-collapse-id` | `android.collapse_key` | | Urgent | Header `apns-priority` 10, otherwise 5 | `android.priority` `HIGH`, otherwise `NORMAL` | Use the sandbox address `https://api.sandbox.push.apple.com` for builds made in development. Take every address from configuration, so tests can point at the stand-in. ## What an answer means | Service | Answer | Do | | --- | --- | --- | | Apple | 200 | Sent. Keep the `apns-id` header. | | Apple | 410, or 400 with reason `BadDeviceToken` | Delete the token. | | Apple | 400 with reason `DeviceTokenNotForTopic` | Delete the token and log it: the token is for another app. | | Apple | 403 | The sign-in is wrong. Make a new one once, then stop and log. | | Apple | 429, 500, 503 | Try later. | | Google | 200 | Sent. Keep the message name. | | Google | 404, or error `UNREGISTERED` | Delete the token. | | Google | 400 with error `INVALID_ARGUMENT` | Mark failed and log. Do not retry. | | Google | 401 | Get a new access token once, then stop and log. | | Google | 429, 500, 503 | Try later, after `Retry-After` if it is there. | ## Quiet hours Work in the phone's `time_zone` with the platform's time zone database, never with a fixed offset. With quiet hours from 22:00 to 08:00: | Push made at (UTC) | Phone's time zone | Local time | Sent at (UTC) | | --- | --- | --- | --- | | `2026-01-10T18:00:00Z` | `Asia/Kolkata` | 23:30 | `2026-01-11T02:30:00Z` | | `2026-01-10T18:00:00Z` | `America/New_York` | 13:00 | at once | | `2026-01-11T01:00:00Z` | `Asia/Kolkata` | 06:30 | `2026-01-11T02:30:00Z` | | `2026-03-28T22:30:00Z` | `Europe/Berlin` | 23:30 | `2026-03-29T06:00:00Z` | | `2026-10-24T21:30:00Z` | `Europe/Berlin` | 23:30 | `2026-10-25T07:00:00Z` | The last two are the nights the clocks change in Berlin. A fixed offset gets both wrong by an hour. The quiet period can cross midnight, as here, or not. A phone with a time zone the database does not know is treated as UTC. ## What the app must do 1. Ask for permission to notify at a moment that makes sense to the person, not on first launch. 2. Send the token to `POST /api/devices` on every launch and whenever the system gives a new one. 3. Tell the server on sign-out, before the session is dropped. 4. When a notification is tapped, open the address in its `data.link`. 5. When the person reads notifications, call the server so badges on their other phones are set. ## Configuration | Secret | Purpose | | --- | --- | | `DATABASE_URL` | Connection string for the chosen database. | | `APNS_KEY`, `APNS_KEY_ID`, `APNS_TEAM_ID`, `APNS_BUNDLE_ID` | Apple's push key and what goes with it. Not needed without iOS. | | `FCM_SERVICE_ACCOUNT` | The Firebase service account, as JSON. Not needed without Android. | ## Named here - A payload's size is the size of the JSON sent to the push service, without the device token. - Quiet hours that start and end at the same time mean no quiet hours. ## What this spec leaves to you Where this spec names something, use that name, so that two builds of it agree. Where it does not, the choice is yours. List what you chose in the README.