# 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 | | --- | --- | | `notifications` | `id` (grows with time), `user_id`, `type`, `data` (JSON), `dedupe_key`, `created_at`, `read_at`, `emailed_at` | | `notification_preferences` | `user_id`, `type`, `in_app`, `email`; primary key on the first two | | `notification_settings` | `user_id` (primary key), `email_mode` (`each` or `daily`), `time_zone`, `last_email_at`, `last_digest_on` | Indexes: `user_id`, `id` descending for the inbox; `user_id` where `read_at` is null for the count; a unique one on `user_id`, `type`, `dedupe_key` where the key is set. A missing preference row means the type's defaults. Rows exist only for what a person changed. ## Rules - The cursor is the `id` of the last notification shown. The next page is everything with a smaller `id`. Page numbers skip or repeat rows when new ones arrive. - "Mark all as read" sends the `id` of the newest notification the page knows about, and the server marks only those at or below it. - For the 24 hours in R1, a job clears `dedupe_key` on notifications 24 hours old or older, which frees the unique index. - Titles are made when a notification is shown, from `type` and `data`, so a change of wording applies to old notifications too. Escape everything taken from `data`. ## Email A job runs every minute. For each person with email in mode `each`, it takes the notifications that are unread, not yet emailed, older than `email_delay_minutes` and of a type whose email is on. If there are any and `last_email_at` is older than the delay, it sends one email and sets `emailed_at` on each in the same transaction as `last_email_at`. The daily summary is the same job with another test: the local time in the person's `time_zone` has passed 08:00 and `last_digest_on` is before today's local date. Work out local time with the platform's time zone database, never with a fixed offset. Put sending behind one small interface so tests capture messages without a network. Use the `app_name` input as the sender's name and in the subject. ## The unsubscribe token ``` payload = user id, a full stop, type token = base64url(payload) + "." + base64url(HMAC-SHA-256(UNSUBSCRIBE_SECRET, payload)) ``` Compare the signature in constant time. The page reached by `GET` changes nothing until its button is pressed, because mail scanners follow links. ## Configuration | Secret | Purpose | | --- | --- | | `DATABASE_URL` | Connection string for the chosen database. | | `EMAIL_API_KEY` | Sends the emails. Optional in development. | | `EMAIL_API_URL` | Where `send_email` posts each message. Optional in development. | | `EMAIL_FROM` | The address every email is sent from. Optional in development. | | `UNSUBSCRIBE_SECRET` | Signs unsubscribe links. At least 32 random bytes. | ## Who is signed in The spec reaches the app's sign-in through one function, `current_user(request)`. It answers with the person's id, and says whether they are an administrator where this spec asks. In the person's app it reads their session. When there is no app yet, build this stand-in and nothing more: a page that lists two seeded people, one of them an administrator, with a button for each that sets a signed cookie naming them. The stand-in refuses to start in production. ## Sending email Send every email through one function, `send_email(to, subject, text)`. - With `EMAIL_API_URL` and `EMAIL_API_KEY` set, it makes one `POST` to `EMAIL_API_URL` with the header `Authorization: Bearer ` and the JSON body `{"from": EMAIL_FROM, "to": ..., "subject": ..., "text": ...}`. Any 2xx answer means sent. The person points the address at their email service, or at a few lines that translate for it. - With neither set, outside production, the message goes to a local outbox that tests read. It is not printed: a message can hold a link that signs someone in. In production the app refuses to start without both. ## Named here - A missing preference row means inbox on and email on. - A repeat is blocked until 24 hours have passed. At 24 hours exactly it is created. - `unread_count` is a JSON number. ## 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.