62 lines
3.0 KiB
TypeScript
62 lines
3.0 KiB
TypeScript
/**
|
|
* A small invite-only social platform for sharing links and files. The
|
|
* repository holds three parts: the backend in `api/`, the frontend in `src/`,
|
|
* and in `shared/` whatever crosses the wire between them. This reference
|
|
* documents all three; [every module](./all_symbols.html) is listed by path,
|
|
* so they come grouped by part and layer.
|
|
*
|
|
* ## Backend — `api/`
|
|
*
|
|
* An Oak server over SQLite that answers the API and the WebSocket, and serves
|
|
* the built frontend. `api/main.ts` builds the application and listens. A
|
|
* request goes through a route, which parses it and answers. The route calls
|
|
* services, which hold the logic and every SQL query; they read rows through
|
|
* the model, and reach other sites only through `remote/`. Each folder holds
|
|
* one kind of module, and each file is named after its domain:
|
|
*
|
|
* - `routes/` — the HTTP API. Each router's page lists its endpoints: method
|
|
* and path, who may call it, what it does.
|
|
* - `middleware/` — what runs around every route: auth, errors, OG tags.
|
|
* - `services/` — the logic and every SQL query, one module per domain.
|
|
* - `model/` — per table, its row type, guard and mappers.
|
|
* - `validators/` — the request-body guards.
|
|
* - `remote/` — the only place that fetches from other sites; its `providers/`
|
|
* build the previews of each kind of site.
|
|
* - `lib/` — helpers that belong to no layer.
|
|
* - `db/` — the handle, its creation, migration and startup housekeeping;
|
|
* `db/migrations/` are applied in order, each once.
|
|
* - `config.ts` — the settings read from the environment; `scripts/` — the
|
|
* icon generator.
|
|
*
|
|
* ## Shared — `shared/`
|
|
*
|
|
* The types and constants both halves use, one module per domain: the API
|
|
* envelope, each domain's types and request bodies, the socket protocol, the
|
|
* validation limits and the role permissions. It imports nothing from either
|
|
* half. The server sends `Date`s; the client reads the same types through
|
|
* `Wire<T>`, with every `Date` an ISO string.
|
|
*
|
|
* ## Frontend — `src/`
|
|
*
|
|
* The React app, built with Vite and translated with Lingui. `main.tsx` mounts
|
|
* it, `App.tsx` holds the providers and the route table, `i18n.ts` the
|
|
* language. A page reads the API and the socket through contexts and hooks, and
|
|
* draws with components; utils hold what isn't React at all.
|
|
*
|
|
* - `pages/` — one component per route, each naming it, and the two guards
|
|
* that wrap the routes for the signed in and the signed out.
|
|
* - `config/` — settings read at startup.
|
|
* - `contexts/` — a `FooContext` holding the state and its `FooProvider`.
|
|
* - `hooks/` — every hook.
|
|
* - `components/` — only components.
|
|
* - `utils/` — every module that isn't React.
|
|
*
|
|
* Every layer but `pages/` and `config/` is split into the same domains (auth,
|
|
* category, chat, comment, dump, editor, feed, form, layout, player, playlist,
|
|
* profile, social, theme, ws, and shared for what belongs to no one domain), so
|
|
* the chat lives in `components/chat/`, `contexts/chat/`, `hooks/chat/` and
|
|
* `utils/chat/`.
|
|
*
|
|
* @module
|
|
*/
|