# 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 | | --- | --- | | `changelog_entries` | `id` (a UUID, made once), `slug` (unique), `title`, `body`, `kind`, `publish_at`, `updated_at`, `removed_at`, `emailed_at` | | `changelog_seen` | `user_id` (primary key), `seen_at` (only if `in_app_badge` is on) | | `changelog_subscribers` | `id`, `email` (unique, lowercase), `confirmed_at`, `created_at` (only if `email_subscribers` is on) | An entry is public when `publish_at` has passed and `removed_at` is empty. There is no separate "published" switch to forget: a draft has no `publish_at`. ## Addresses The slug is the title in lowercase, with every run of characters that are not letters or digits turned into one hyphen, cut to 60 characters, with no hyphen at either end. If it is taken, add `-2`, `-3` and so on. | Title | Slug | | --- | --- | | `Dark mode is here!` | `dark-mode-is-here` | | ` Faster exports ` | `faster-exports` | | `Fixed: CSV import (again)` | `fixed-csv-import-again` | | A second `Dark mode is here!` | `dark-mode-is-here-2` | ## The feed - The feed's `id` and every entry's `id` are `urn:uuid:` followed by a UUID. The entry's is its own `id` column. The feed's is a fixed UUID in configuration. - `title` is the `app_name` input followed by ` changelog`. - An entry's `published` is `publish_at`. Its `updated` is `updated_at` if it was edited after publishing, and `publish_at` otherwise. The feed's `updated` is the newest of those. - Times are written as `2026-11-13T09:30:00Z`. - `content` has `type="html"`, holding the rendered body with its `<`, `>` and `&` escaped once more, as Atom requires. - The `ETag` is a hash of the feed's bytes, in quotes. ## Unseen ``` unseen = entries where publish_at > the later of (seen_at, the account's creation) and publish_at <= now and removed_at is empty ``` A person with no row in `changelog_seen` is treated as having `seen_at` equal to when their account was made. ## Email - Sending is a job that runs once a minute: it takes public entries whose `emailed_at` is empty, sends them, and sets `emailed_at`. An edit never clears it. - The unsubscribe token is the subscriber's id, a full stop, and an HMAC-SHA-256 of the id keyed with `CHANGELOG_SECRET`. The headers are `List-Unsubscribe` and `List-Unsubscribe-Post: List-Unsubscribe=One-Click`. - The page reached by `GET` changes nothing until its button is pressed. ## Configuration | Secret | Purpose | | --- | --- | | `DATABASE_URL` | Connection string for the chosen database. | | `EMAIL_API_KEY` | Sends the emails. Only with `email_subscribers`. | | `EMAIL_API_URL` | Where `send_email` posts each message. Only with `email_subscribers`. | | `EMAIL_FROM` | The address every email is sent from. Only with `email_subscribers`. | | `CHANGELOG_SECRET` | Signs unsubscribe links. Only with `email_subscribers`. | ## 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 - The feed's author is the app's name. A time an administrator types is read as UTC. - A title with no letter or digit gets the slug `entry`. ## 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.