Go to file

khannurien f20ca83f0c v4: every email is rendered by its template in api/mail/ on one layout that takes the instance's style, and sent one way — the welcome email was built and sent inside the register route and the reset link in its service, each writing Markdown, running marked, and calling a nodemailer wrapper whose cc, bcc, replyTo and send result nothing used. Now api/mail/ holds one template per email (welcome.ts, password-reset.ts) on layout.ts's EmailKit, which draws each block with inline styles in a style from styles.ts: the six site styles' palettes, copied from src/themes/, and what makes each recognisable in a mail client (Brutalist's hard border and shadow, GeoCities' ridge and rainbow rules, Times' underlined ink links, Kanagawa's colored quotes, dates and wordmark, Melange's spice bar). On the "auto" scheme the light palette is inlined and the dark one swapped in by a prefers-color-scheme block; a chosen scheme sends only its own. User-written text is escaped where it lands. strings.ts holds every email's words in English and French. GERBEUR_EMAIL_LOCALE picks the language and GERBEUR_DEFAULT_STYLE the instance's style, which the welcome and reset emails are drawn in; GERBEUR_WELCOME_EMAIL_BODY still replaces the welcome's Markdown, whose blocks now take the style too. email-service sends a rendered email with its recipient and headers, refuses to load when GERBEUR_SMTPS_URL is set without GERBEUR_FROM_EMAIL (sends used to fail one by one), and takes a test transport, through which the tests now read what was sent. The welcome send moves to user-service's sendWelcomeEmail. The style and scheme names move to shared/theme.ts, which the server now needs. README, mod.ts and .env.example describe mail/ and the new variables, and drop the "notifications, invites" email that never existed. 221 backend tests pass (new: the layout's schemes, styles and escaping, both templates, the welcome on sign-up, a reset link from the email that works), and deno check, deno lint, doc:lint, deno fmt, tsc and eslint are clean.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

2026-10-04 21:11:54 +00:00

.devcontainer

devcontainer: update lock file

2026-09-19 20:12:37 +00:00

.gitea/workflows

v3: src/ is documented like api/ and shared/, and the reference covers the whole repository — the frontend had no module docs, JSDoc on some components and hooks and not on others, props typed inline in half the components and in private interfaces in the rest, // comments on declarations, and no return types on 147 exported functions, so deno doc --lint over src/ found 637 errors. The rule api/ follows is applied to every non-test module of src/: a /** … @module */ block, JSDoc on every export and every field of an exported interface, /** */ for declarations and // for notes, verbs for functions ("Renders…" for a component), parameters named in the prose, {@link} only for symbols in scope, and a page's JSDoc names its route and who may see it (App.tsx's module doc lists the route table). For deno doc to show them, every exported function states its return type: components React.JSX.Element (or | null, or a portal), memo and forwardRef components their exotic types, contexts React.Context<…>, and a hook returning several things a documented Use<Name>Result interface (useAuth, useRequiredAuth, useFading, useEmojiTrigger, useMentionAutocomplete, useDumpCardLink, usePlayRichContent; FeedCacheResult, YouTubePlaylistControls and UseApiFormReturn are renamed to match). Every component that takes props takes an exported, documented <Name>Props interface — the 64 inline prop types are lifted into one, DumpFeed gets DumpFeedProps extending MainFeedProps. React types go through the global React namespace: the four default imports of react are gone, since deno doc can't follow them. Two duplicates go too: useMentionAutocomplete's UserResult was shared/'s UserSuggestion, and JournalCard re-exported JournalShape for no one; i18n.ts no longer re-exports Lingui's i18n, which its three users now import from @lingui/core. deno task doc and doc:lint now take src/ (but its tests and the generated locales), the index page gains a Frontend section linking every module by layer and domain, mod.test.ts walks src/ as well, and the docs workflow runs on changes to src/. deno doc doesn't document npm packages, so it takes a type imported from one — react-hook-form's FieldValues in the form fields, frimousse's SkinTone — for a private one; doc:lint now goes through doc-lint.ts, which fails on every diagnostic but those, 25 of them. The README states the frontend's part of the rule. No behaviour changes; 205 backend and 628 frontend tests pass, and tsc, deno check and deno lint are clean.

2026-09-28 07:31:22 +00:00

api

v4: every email is rendered by its template in api/mail/ on one layout that takes the instance's style, and sent one way — the welcome email was built and sent inside the register route and the reset link in its service, each writing Markdown, running marked, and calling a nodemailer wrapper whose cc, bcc, replyTo and send result nothing used. Now api/mail/ holds one template per email (welcome.ts, password-reset.ts) on layout.ts's EmailKit, which draws each block with inline styles in a style from styles.ts: the six site styles' palettes, copied from src/themes/, and what makes each recognisable in a mail client (Brutalist's hard border and shadow, GeoCities' ridge and rainbow rules, Times' underlined ink links, Kanagawa's colored quotes, dates and wordmark, Melange's spice bar). On the "auto" scheme the light palette is inlined and the dark one swapped in by a prefers-color-scheme block; a chosen scheme sends only its own. User-written text is escaped where it lands. strings.ts holds every email's words in English and French. GERBEUR_EMAIL_LOCALE picks the language and GERBEUR_DEFAULT_STYLE the instance's style, which the welcome and reset emails are drawn in; GERBEUR_WELCOME_EMAIL_BODY still replaces the welcome's Markdown, whose blocks now take the style too. email-service sends a rendered email with its recipient and headers, refuses to load when GERBEUR_SMTPS_URL is set without GERBEUR_FROM_EMAIL (sends used to fail one by one), and takes a test transport, through which the tests now read what was sent. The welcome send moves to user-service's sendWelcomeEmail. The style and scheme names move to shared/theme.ts, which the server now needs. README, mod.ts and .env.example describe mail/ and the new variables, and drop the "notifications, invites" email that never existed. 221 backend tests pass (new: the layout's schemes, styles and escaping, both templates, the welcome on sign-up, a reset link from the email that works), and deno check, deno lint, doc:lint, deno fmt, tsc and eslint are clean.

2026-10-04 21:11:54 +00:00

public

v3: added a chatbox

2026-06-29 20:25:10 +00:00

shared

2026-10-04 21:11:54 +00:00

src

2026-10-04 21:11:54 +00:00

.dockerignore

v3: added opengraph support to the app, wrote README instructions incl. a Docker image

2026-03-26 19:55:48 +00:00

.env.example

2026-10-04 21:11:54 +00:00

.gitignore

v3: the backend is documented for deno doc, one way in every file, and the docs build and publish themselves — comments were in three shapes: file headers as // lines, as an untagged /** */ (which deno doc drops, only an @module block counts) or missing; 43 exports described by a // deno doc can't see, two JSDoc blocks sitting on the wrong declaration and one duplicated; endpoints commented in 5 of 18 route files, three ways, on router.get() calls no doc tool reads. The rule, applied to every non-test module of api/, migrations included: each opens with a /** … @module */ block; every export has JSDoc, and so does every field of an exported interface; a comment describing a declaration is /** */, // only notes code; functions open with a verb, everything else with a noun phrase; parameters are named in the prose, {@link} only for symbols in scope; whatever throws to its caller says so with @throws (for an APIException, the statuses and when); a router's JSDoc lists its endpoints, method and path, who may call it, what it does. deno doc --lint goes from 528 errors to none in api/ (shared/ keeps its 385; it is next). The lint also wanted explicit types on config.ts's settings and a few return types, JsonLdResult exported, and the routers typed Router. deno task doc builds the HTML reference into docs/ from every module of api/ and shared/ but the tests, deno task doc:lint lints it; the index page is the module doc of a root mod.ts (deno.json's exports), which introduces the backend, shared/ and the frontend to come and links every module, and mod.test.ts fails when one is missing. The docs workflow builds it on every push to main that touches them and publishes it to the gh-pages branch, like publish-assistant's. Two defects found along the way are fixed: a private playlist's cover was served to anyone who had its id or slug, and now needs its owner's media token, as private dump files do (playlistImageUrl adds it for private playlists only, so public cover URLs stay the same for everyone); og.ts and static.ts each filled index.html's placeholders, and now share lib/index-html.ts, so the OG middleware picks up a rebuilt index.html instead of keeping the first it read. The README states the documentation rule. 205 backend and 628 frontend tests pass.

2026-09-27 21:07:40 +00:00

deno.json

v3: fix the privacy and security findings of the comment pass — private dumps' broadcasts, mentions and attachments reached people who can't see them, and a few smaller holes. A dump's every write now goes through ws-service's broadcastDumpChange(before, after), which decides the audience: a private dump's creation, edits and deletion reach its owner's sockets alone (its deletion id went to everyone before), going private is dump_deleted for everyone else and dump_updated for the owner (whose other tabs dropped it), going public dump_created for everyone else. Mentions in a private dump, a comment on one, or a private playlist's description notify no one until it goes public (mentions are deduplicated per context, so going public notifies them once), and a moderator's edit of a comment, chat message or playlist mentions in the author's name. A link preview of a private playlist is refused, as one of a private dump already was: the preview is stored in the linking dump, which others may see. Attachments record the type of the resource that links them (migration 0018 backfills it); one linked by a private dump or playlist, or a comment on a private dump, is served only with its owner's media token, which Markdown now adds to attachment URLs, and one whose resource is gone answers 404 and is purged at startup. The Bandcamp provider claimed bandcamp.com.evil.example (the pattern wasn't anchored) and now reuses bandcamp-tralbum's anchored one; the YouTube provider took any site's ?list= for a YouTube playlist and missed m., music., youtube-nocookie and /live/ links, and now shares canonical-url's rules. Sign-in does the same scrypt work for an unknown username as for a wrong password, so timing no longer tells which exist. Usernames and emails are unique regardless of case (migration 0017, which refuses to run over existing clashes and names them): "Bob" and "bob" could both sign up and a mention picked one, emails had no constraint, and a reset request in another case silently sent nothing. The Open Graph tags escape the site name and build their URLs on PUBLIC_URL and FRONTEND_URL instead of the request's origin, which a proxy may rewrite.

2026-09-29 15:19:07 +00:00

deno.lock

v3: coverage tasks for both suites — deno task test:coverage runs the Deno tests of api/ and shared/ with coverage and writes the report to coverage/api, deno task test:web:coverage runs the Vitest suite with @vitest/coverage-v8 (at vitest's own 5.0.2) into coverage/web. Each prints a table and leaves an HTML report and an lcov.info. They write to separate folders because deno test --clean empties its whole output directory, which would take the frontend report with it. The frontend report counts src/ without src/test/ and the generated src/locales/; the backend report still lists api/test/helpers.ts and setup.ts, since deno.json has no coverage exclude and a separate deno coverage --exclude pass merged the raw profiles into different figures. No behaviour changes.

2026-09-27 20:30:05 +00:00

doc-lint.ts

v3: comments say what the code can't — the documentation pass wanted JSDoc on every export and every field of an exported interface, which filled the code with restatements ("The dump.", "Whether it is loading.", "The props of X.", "Renders the X.") and module docs that told a reader nothing ("The hot and new feeds, and the props every main feed of the index takes."); some were wrong as well as vague. Every comment in api/, shared/ and src/ is rewritten under one rule, now stated in the README's "Comments" section: every module and export still has a JSDoc, and it gives context (who uses it and where), usage (what a caller must know: a precondition, what it leaves to the caller, a side effect) or its place in the chain (where its input comes from, where its output goes); a field, parameter, private function or local gets one only when it adds to its parent's, and context about a whole type goes on the type; a type's doc is phrased from the value's side ("Returned to Y by X when Z", "Passed to Y by X"); full sentences, as short as they can be, no label-colon-list; // goes wherever the code isn't obvious and says why, and the section banners and narration go. Every claim was checked against the code, which turned up some forty comments that were wrong: DumpCard's claimed it was only used by the hot and new feeds, the WebSocket welcome claimed to be a socket's first message (presence comes first), UpdateUserRequest said null removes a description (it keeps it), deletedDumpIds leaves out that it also holds dumps made private, THEME_COLOR claimed to mirror index.html's, and the like. The routers' JSDoc now says where they are mounted and what becomes of a thrown APIException. doc-lint.ts lets a field without a doc through; a module or export without one still fails. No code changes; 204 backend and 628 frontend tests pass, and doc:lint, deno check, deno lint and tsc are clean.

2026-09-29 14:31:14 +00:00

Dockerfile

v3: api/ gets one layout rule and keeps to it, and whatever crosses the wire is defined once, in shared/ — api/model/interfaces.ts and src/model.ts declared the same 40 types by hand and had drifted: the error envelope, email required on one side and optional on the other, Invitee/InviteTreeEntry and LinkPreview/UrlPreviewResponse for one shape each. The validation limits, the role permissions, the chat length cap, the @mention pattern and the Bandcamp and YouTube player responses were copied too, behind "keep in sync" comments. shared/ now holds them once, one file per domain (api, category, chat, comment, dump, follow, mention, notification, permissions, player, playlist, search, user, validation, ws), and imports nothing from either half. The server sends Dates; the client reads Wire<T>, the same type with every Date an ISO string, and turns it back with src/utils/shared/deserialize.ts. APIErrorCode becomes a const object, since the frontend's erasableSyntaxOnly rejects an enum. The shared types showed two real gaps: the avatar upload and GET /api/users/me return the full self user and the frontend read them as public users, and a stored session may predate media tokens, so the client keeps it as its own Session type. The backend rule: each folder holds one kind of module, each file is named after its domain. routes/ parse and answer; services/ hold the logic and every SQL query (lib/auth.ts's token check moves to user-service); remote/ is the only place that fetches from other sites — the guarded fetch and the HTML scraping out of rich-content-service, public-address, the Bandcamp and YouTube resolvers, the link providers, the image proxy (fetch, checks and cache, out of routes/preview.ts) and the Twemoji glyphs (out of lib/site-icons.ts). model/ holds per table a row type, its guard and its mappers; validators/ the request guards; db/connection.ts the handle and transaction(), db/startup.ts the purges and default admin that db.ts ran on import, called at the same moment. Tests mirror the source one file per module, test/<layer>/<module>.test.ts, with shared/'s under shared/test/ (deno task test runs both); the test that covered the bandcamp and soundcloud providers together is two now, and the backend can() has its own, so 202 tests. deno lint src/ is clean too: window.* becomes globalThis.*, and test bodies and act() callbacks that never awaited lose their async. The README states the rule. No behaviour changes; the catalogues only move their source references.

2026-09-27 20:19:48 +00:00

eslint.config.ts

v3: the frontend gets a test suite, and the bugs it turned up are fixed — deno task test:web runs 612 tests over src/ in about 11s: Vitest on jsdom with Testing Library, built on the app's own Vite config so the SWC/Lingui transform and the .po loader are what ship. src/test/ holds the harness: a routing fetch stub (queued once-responses, fallback defaults), a FakeWebSocket the tests open, feed and drop, jsdom polyfills, fixtures, and two render helpers — one over hand-set context values, one over the real provider tree (auth, socket, player, follows, categories, chat). It covers every util and hook, every provider (the socket protocol end to end: votes and likes with ack/timeout/error rollback, chat sends/echoes/retries/read markers/reconcile, reconnect backfill), the components (header and search history, cards, Markdown, thumbnails, media and global player, the text editor's mentions/emoji/uploads, comments, the new-dump modal, the chat), and every page.

2026-09-27 14:35:41 +00:00

index.html

v3: the frontend ships compressed, caches for good, and stops reaching for other people's servers — a review of the bundle's size found the server was the biggest cost. Oak's send() compressed nothing and sent every hashed chunk with max-age=0, so a first visit to the home page moved about 710 KB of JS and CSS where 200 KB would do, and every later one revalidated some thirty files. The build now writes .br and .gz next to every JS, CSS, JSON and SVG file (a precompress plugin, brotli 11), which send() already serves when the browser accepts them; /assets and /emojibase are cached for a year as immutable, index.html is no-cache, and static responses carry Vary: Accept-Encoding. A missing file under either prefix is a 404 rather than index.html with a 200, which an open tab after a deploy used to try to run as a script; the app now reloads on vite:preloadError, at most once a minute. manualChunks sent everything in node_modules to one vendor chunk, so react-hook-form and frimousse loaded with every page though only the lazy form and editor chunks use them, and its markdown rule missed hast, vfile, unified and property-information while every feed loads Markdown through DumpCard anyway; only react, react-dom, scheduler and react-router get a chunk of their own now, the rest is left to the bundler. Up-front JS goes from 133 to 96 KB gzip, the home page from 178 to 160. Fonts: index.html blocked rendering on a Google Fonts stylesheet, opening two more hosts and handing each visitor's IP to Google; they come from @fontsource now, with src/fonts.css declaring only the latin and latin-ext faces (the packages' own CSS declares every subset, which added 6 KB gzip to the stylesheet), so Vite hashes the woff2 files into /assets and a browser still only downloads its theme's font. The families are the variable builds ("Saira Variable" and so on); Fraunces keeps its opsz, SOFT and WONK axes. Emoji: frimousse fetched emojibase-data@latest from jsDelivr, unpinned and third-party; emojibase-data 17.0.0 is a dependency now, its data and messages for each lingui locale are emitted under /emojibase/17.0.0 (served from node_modules in dev), and the picker is pointed there.

2026-09-27 11:44:08 +00:00

LICENSE

initial commit, boilerplate stuff

2026-03-15 17:15:46 +00:00

lingui.config.ts

v3: performance pass, bundle size pass, i18n pass, docker pass

2026-04-08 13:19:39 +00:00

mod.ts

2026-10-04 21:11:54 +00:00

package.json

2026-09-27 20:30:05 +00:00

README.md

2026-10-04 21:11:54 +00:00

tsconfig.app.json

initial commit, boilerplate stuff

2026-03-15 17:15:46 +00:00

tsconfig.json

initial commit, boilerplate stuff

2026-03-15 17:15:46 +00:00

tsconfig.node.json

initial commit, boilerplate stuff

2026-03-15 17:15:46 +00:00

vite.config.ts

2026-09-27 11:44:08 +00:00

vitest.config.ts

2026-09-27 20:30:05 +00:00

README.md

gerbeur

A small invite-only social platform for sharing links and files. Users can post URLs and media (YouTube, SoundCloud, Bandcamp, images, audio, video, …), vote, comment, follow each other, build playlists, and search content. A real-time WebSocket layer handles live presence, vote counts, and notifications. The UI is localized (English and French) and ships multiple visual themes.

Stack

Layer	Technology
Runtime	Deno 2.x
API	Oak (HTTP + WebSocket)
Database	SQLite via `node:sqlite`
Frontend	React 19 + Vite 8

Development

Prerequisites

Deno 2.x

Setup

cp .env.example .env
# Edit .env: set GERBEUR_JWT_SECRET to the output of: openssl rand -hex 32

Run

deno task dev

This starts both the API server (port 8000, with file watching) and the Vite dev server (port 3000) concurrently.

Open http://localhost:3000. On first run a default admin / admin account is created — change the password immediately.

Environment variables

See .env.example for the full list with descriptions. Key variables:

Variable	Description	Default
`GERBEUR_JWT_SECRET`	JWT signing secret — required, generate with `openssl rand -hex 32`	—
`GERBEUR_PUBLIC_URL`	Public-facing URL of the server (no trailing slash) — used for CORS, WebSocket origin, email links, OG URLs	`http://localhost:GERBEUR_PORT`
`GERBEUR_PORT`	Internal port Oak listens on	`8000`
`GERBEUR_LISTEN_HOST`	Network interface Oak binds to; use `127.0.0.1` to restrict to loopback	`0.0.0.0`
`GERBEUR_FRONTEND_URL`	Frontend base URL for email links and CORS; auto-added to allowed origins — the only variable needed when the frontend runs on a separate host	`GERBEUR_PUBLIC_URL`
`GERBEUR_ALLOWED_ORIGINS`	Comma-separated extra origins for CORS/WebSocket; `PUBLIC_URL` and `FRONTEND_URL` are always included — typically only needed in dev for the Vite server	`""` (empty)
`GERBEUR_SITE_NAME`	Site name used in the browser tab, app header, OG meta tags, and emails	`gerbeur`
`GERBEUR_SMTPS_URL`	SMTPS connection URL for outgoing email (`smtps://user:pass@host:465`); unset sends no email	unset
`GERBEUR_FROM_EMAIL`	Sender of every email — required when `GERBEUR_SMTPS_URL` is set, or the server won't start	unset
`GERBEUR_EMAIL_LOCALE`	Language of every email: `en` or `fr`	`en`
`GERBEUR_DEFAULT_STYLE`	The instance's style (`smooth`, `brutalist`, `geocities`, `nyt`, `kanagawa`, `melange`), used by the welcome and reset emails	`smooth`
`GERBEUR_WELCOME_EMAIL_BODY`	Markdown body for the account-creation welcome email; supports `{{username}}` and `{{site_name}}`	built-in template
`VITE_API_PROTOCOL`	API protocol baked into the frontend bundle (see Production)	`http`
`VITE_API_HOSTNAME`	API hostname baked into the frontend bundle	`localhost`
`VITE_API_PORT`	API port baked into the frontend bundle	`8000`

Production

Docker (recommended)

The standard deployment runs API and frontend in a single container. The API server (Oak) serves the compiled frontend as static files, so both share the same origin — no VITE_API_* build args needed. Set GERBEUR_PUBLIC_URL to the externally-visible URL; it is automatically allowed for HTTP/WebSocket requests.

docker build -t gerbeur .

docker build -t gerbeur .

docker run -d \
  -p 8000:8000 \
  -v gerbeur-db:/app/api/sql \
  -v gerbeur-uploads:/app/api/uploads \
  -e GERBEUR_JWT_SECRET=$(openssl rand -hex 32) \
  -e GERBEUR_PUBLIC_URL=https://example.com \
  -e GERBEUR_SITE_NAME=mysite \
  --name gerbeur \
  gerbeur

The two volumes are required for persistence:

gerbeur-db — SQLite database (api/sql/gerbeur.db), initialized automatically on first run
gerbeur-uploads — user-uploaded files (api/uploads/)

Separate API and frontend (optional)

If you need to run the API on a different host than the frontend, pass the API location as build args so it gets baked into the frontend bundle. In that setup, add the frontend origin to GERBEUR_ALLOWED_ORIGINS so cross-origin HTTP/WebSocket requests are accepted:

docker build \
  --build-arg VITE_API_PROTOCOL=https \
  --build-arg VITE_API_HOSTNAME=api.example.com \
  --build-arg VITE_API_PORT=443 \
  -t gerbeur .

Reverse proxy

Put a reverse proxy (nginx, Caddy, …) in front of the container to handle TLS. Forward everything to port 8000. Example Caddyfile:

example.com {
    reverse_proxy localhost:8000
}

Project structure

shared/            # Imported by both halves: API and socket types, limits, permissions
  test/            # Tests of shared/ (Deno): test/<module>.test.ts
api/
  main.ts          # Entry point — Oak application, middleware, routes
  config.ts        # Environment variables
  middleware/      # Oak middleware: errors, auth, OG tags
  routes/          # One router per URL prefix: HTTP + WebSocket, no SQL
  services/        # Business logic and every SQL query
  remote/          # Everything that fetches from other sites
  mail/            # One template per email, and the layout they share
    providers/     # Link metadata providers (YouTube, SoundCloud, Bandcamp, …)
  model/           # Per table: row type, row guard, row ↔ API mappers
  validators/      # Per domain: request body guards
  lib/             # Helpers with no SQL and no outbound fetch: JWT, slugs, files, …
  db/
    connection.ts  # The database handle and transaction(); creates a new database
    startup.ts     # Housekeeping run when the database opens
    schema.sql     # Database schema
    migrate.ts     # Migration runner
    migrations/    # Versioned schema migrations
  test/            # Backend tests (Deno): test/<layer>/<module>.test.ts
  sql/
    gerbeur.db     # SQLite database (not committed)
  uploads/         # User-uploaded files — avatars, dumps, thumbnails, … (not committed)
src/               # React frontend (Vite)
  config/          # API base URL, feed tabs, player mode
  pages/           # One component per route, nothing else
  components/      # React components only (.tsx)
  contexts/        # FooContext.ts + FooProvider.tsx pairs
  hooks/           # Every hook (useFoo.ts)
  utils/           # Every non-React module: pure helpers, storage, API glue
  test/            # Frontend tests (Vitest): test/<layer>/<domain>/<Module>.test.tsx
  locales/         # Lingui message catalogues (en, fr)
  themes/          # Per-theme CSS files
  i18n.ts          # Lingui runtime setup
public/            # Static assets (favicon, manifest, service worker)

Whatever crosses the wire is defined once, in shared/: the API envelope (shared/api.ts), each domain's types and request bodies (shared/dump.ts, shared/user.ts, …), the socket protocol (shared/ws.ts), the validation limits and the role permissions. The server sends Dates; the client reads Wire<T>, the same type with every Date an ISO string, and turns it back with src/utils/shared/deserialize.ts. shared/ imports nothing from either half.

The backend is split by layer, one kind of module per folder, and each file is named after its domain: the dumps are routes/dumps.ts, services/dump-service.ts, model/dump.ts and validators/dump.ts. Routes parse and answer, services hold the logic and the SQL, remote/ is the only place that fetches from other sites, and mail/ renders each email that services/email-service.ts sends. Tests mirror the source one file per module, so the tests of services/chat-service.ts are in test/services/chat-service.test.ts.

Comments

A comment says what the code can't. If deleting it would lose nothing, it is the wrong comment: on an export, rewrite it; anywhere else, delete it.

Every module and every export has a JSDoc (/** */). Each gives at least one of:

Context: who uses it and where (a page and its route, a caller, a WebSocket message).
Usage: what a caller must know to use it correctly, such as a precondition, an invariant, what it leaves to the caller, or a side effect. Add an example only when the call isn't obvious.
Place in the chain: where its input comes from and where its output goes.

A doc opens with the role, then the mechanism, then the details. Its first sentence says what part of the app the thing serves or what problem it solves, so a reader who has never seen it knows why it exists. How it does that (what feeds it, what reads it, how it's split) comes next, and the details last. Each sentence makes sense given only the ones before it. Not "Declares the three contexts WSProvider fills from the WebSocket. They are split so that a feed doesn't re-render with every chat message", which leaves the reason for last, but "Live updates from the server reach the pages through three contexts, split so that a feed doesn't re-render with every chat message. WSProvider fills them from its WebSocket."

Once the role is said, a type's doc is phrased from the value's side, naming the producer and the consumer: "Returned to Y by X when Z", "Passed to Y by X". It is never "What X returns to Y" or "What X passes to Y".

Don't pack a doc into a label followed by a colon and a list ("X: one thing, plus some other thing"). Write sentences with a subject and a verb.

When the obvious comment is useless, write the useful one: the context is always there. A field (of an interface, or a parameter) gets a doc only when it adds something its parent's doc doesn't. Context that concerns the whole type goes on the type, not on one of its fields. The same goes for private functions and locals. None of these count as a doc:

a restatement of the name or type (/** The dump. */, "Whether it is loading.", "The props of X.", "Renders the X.");
a description of what the body, the JSX or the SQL plainly does;
a list that goes stale (every caller of a widely used component): name the kind of caller instead.

When a comment is there, it is as short as it can be, often one sentence, and it is written in full sentences. Labels and fragments ("Upvotes on dumps.") don't count. A module doc is a few lines at most. It opens with the module's role in the app, then says how it plays it, who calls it and what it hands back, and it doesn't repeat what its exports' docs say. @throws stays on whatever throws to its caller, with the statuses of an APIException and when each happens. A router's module doc lists its endpoints (method, path, who may call it), since the code states them nowhere in one place. A summary never ends in a colon: the reference shows it alone.

// comments go wherever the code isn't obvious. They explain why, not what: a workaround, an ordering constraint, a surprising limitation, a security reason, an event handler that must not bubble.

Every claim is checked against the code (grep the callers). A wrong comment is worse than none.

Reference

In the frontend, every exported function states its return type, so the reference can show it: a component returns React.JSX.Element (or | null), a hook returning several things returns a documented Use<Name>Result interface. A component that takes props takes an exported <Name>Props interface. React's types are used through the global React namespace rather than a default import of react, which deno doc can't follow.

deno task doc builds the HTML reference into docs/ from every module of api/, shared/ and src/ but the tests (and the generated src/locales/). Its index page is the module doc of mod.ts at the root, which introduces the repository's three parts and their layers in prose; deno doc builds the list of every module itself, grouped by path. The docs workflow publishes it on every push to main that touches them. deno task doc:lint checks the rules the linter can see, and that no summary ends in a colon, through doc-lint.ts. Two kinds of diagnostic are let through. A field without a doc passes, since a field gets one only when it adds to its type's. deno doc doesn't document npm packages, so it takes a type imported from one (react-hook-form's FieldValues, say) for a private one, and those references pass too.

Each of the frontend's components/, contexts/, hooks/ and utils/ is split into the same domain folders — auth, category, chat, comment, dump, editor, feed, form, layout, player, playlist, profile, social, theme, ws — plus shared/ for what belongs to no single domain. So the chat lives in components/chat/, contexts/chat/, hooks/chat/ and utils/chat/, and its tests in test/<same path>. Files are imported directly (no index.ts barrels), and everything uses named exports.