# 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 |
| --- | --- |
| `comments` | `id`, `client_id` (unique per author), `subject_type`, `subject_id`, `parent_id`, `author_id`, `body`, `created_at`, `edited_at`, `deleted_at`, `deleted_by` |
| `comment_edits` | `id`, `comment_id`, `body_before`, `at` |
| `comment_mentions` | `comment_id`, `user_id`; primary key on both (only if `mentions` is on) |
| `comment_reactions` | `comment_id`, `user_id`, `symbol`; primary key on all three (only if `reactions` is on) |
Index `comments` on `subject_type`, `subject_id`, `parent_id`, `created_at`.
## The Markdown that is understood
Paragraphs, line breaks, `**bold**`, `*italic*`, `` `code` ``, fenced code
blocks, links written as `[text](address)`, bare addresses that start with
`http://` or `https://`, lists with `-` or `1.`, and quotes with `>`. Nothing
else: no headings, images, tables or HTML.
Elements allowed in the result: `p`, `br`, `strong`, `em`, `code`, `pre`, `a`,
`ul`, `ol`, `li`, `blockquote`. Attributes allowed: `href` and `rel` on `a`, and
`class="mention"` on `a` for a mention.
Build the HTML from parsed pieces, escaping every piece of text. Do not produce
HTML and clean it afterwards.
| Written | Shown as |
| --- | --- |
| `**hi**` | `
hi
` |
| `hi` | `<b>hi</b>
` |
| `` | `<script>alert(1)</script>
` |
| `[x](https://example.com)` | `x
` |
| `[x](javascript:alert(1))` | `[x](javascript:alert(1))
` |
| `[x](JaVaScRiPt:alert(1))` | `[x](JaVaScRiPt:alert(1))
` |
| `[x](data:text/html,hi)` | `[x](data:text/html,hi)
` |
| `https://example.com/a?b=1&c=2` | `https://example.com/a?b=1&c=2
` |
| `` | `
` |
| `# Title` | `# Title
` |
| `` `` `` | `<i>
` |
## Mentions
A mention is `@` followed by a username, where the `@` is at the start of the
text or follows a space, a line break or an opening bracket, and the username is
followed by the end of the text or by a character that cannot be in a username.
Usernames here are letters, digits and hyphens; use the app's own rule if it
differs. Matching ignores case. Text inside code is never a mention.
| Written | Mentions |
| --- | --- |
| `@ana hi` | `ana` |
| `thanks @ana.` | `ana` |
| `(@ana)` | `ana` |
| `@Ana` | `ana` |
| `@ana @ana` | `ana`, once |
| `mail me at x@ana.com` | nobody |
| `` `@ana` `` | nobody |
| `@nobody-by-this-name` | nobody; shown as plain text |
A mention is shown as a link to the person's page with `class="mention"`.
## Rules
- Take the time from one function, so tests can set it. Use the `edit_minutes`
input for R6.
- An answer from the API for a deleted comment holds its id, its place in the
thread and `deleted: true`, and nothing else.
- The six symbols for R8 are a list in code.
## Configuration
| Secret | Purpose |
| --- | --- |
| `DATABASE_URL` | Connection string for the chosen database. |
## 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.
## Named here
- A mention links to `profile_url(username)`, a function the app supplies. The
stand-in answers `/people/`.
- A mention may follow `(`, `[` or `{`. Lengths are counted in Unicode code
points.
## 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.