# 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 | | --- | --- | | `waitlist_entries` | `id`, `email` (trimmed, lowercase), `email_key` (unique; by the rule in R1), `code` (unique), `referred_by`, `referral_counts`, `ip`, `state`, `joined_at`, `confirmed_at`, `confirm_order` | | `waitlist_invites` | `id`, `entry_id`, `code_hash` (unique), `sent_at`, `expires_at`, `redeemed_at` | `state` is one of `pending`, `confirmed`, `invited` and `joined`. `confirm_order` is 1 for the first entry to confirm, 2 for the second, and so on, given in the transaction that confirms. `referral_counts` says whether this entry counts as a referral for the entry in `referred_by`. ## The line ``` score = confirm_order - boost * (number of entries that count as its referrals) ``` `boost` is the `referral_boost` input. Order by `score`, then by `confirm_order`. Only entries in state `confirmed` are in the line; an invited person's place closes up behind them. Seven people, with a boost of 3: | Place | Person | Confirmed as number | Referrals that count | Score | | --- | --- | --- | --- | --- | | 1 | `gus` | 7 | 4 | -5 | | 2 | `dev` | 4 | 2 | -2 | | 3 | `ana` | 1 | 0 | 1 | | 4 | `ben` | 2 | 0 | 2 | | 5 | `cho` | 3 | 0 | 3 | | 6 | `fay` | 6 | 1 | 3 | | 7 | `eli` | 5 | 0 | 5 | `cho` and `fay` both score 3. `cho` confirmed first, so `cho` is ahead. Work the line out with one query that sorts. Do not store places: every referral would change many rows. ## Rules - Decide whether a referral counts once, when the referred entry confirms, and store the answer. Later changes to the rules do not rewrite the past. - The three rules of R3 need the IP address of each join. Delete it 30 days after the entry confirms. - The status token is the entry's id, a full stop, and an HMAC-SHA-256 of the id keyed with `WAITLIST_SECRET`, both in base64url. Compare in constant time. - Invitation codes are 10 random letters and digits, stored as SHA-256 hashes. - Put sending behind one small interface so tests capture messages without a network. Four messages: confirm, you are on the list, you are invited, your invitation ran out. Use the `app_name` input in each. - In CSV, put a single quote in front of any cell that starts with `=`, `+`, `-` or `@`. ## 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. | | `WAITLIST_SECRET` | Signs status 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 - "In a day" is the last 24 hours. `googlemail.com` counts as Gmail. ## 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.