The Seed web app is the server that turns a daemon into a website. It sits in front of a daemon and serves a space at a domain. That is a site. Anyone with a browser can read it, and this documentation is served by it. hyper.media, every *.hyper.media site and every self-hosted site run it.
The web app serves four things:
A page for every document, rendered on the server.
The typed Seed API, for programs.
The site services under /hm/api. They let a desktop app register the site, and they let browsers sign in.
A small editor, so people can comment and edit from the web with a real signature.
Where the code is
The code is in frontend/apps/web, package @shm/web. It is built with Remix on Node, Vite, React Query, the shared editor, Sentry and Tailwind.
app/entry.server.tsx is the server entry. It loads .env first, then everything else.
app/routes/$.tsx is the catch-all route that renders documents.
app/routes/api.$.tsx is the Seed API.
The app/routes/hm.api.* files are the site services.
How it talks to the daemon
The server holds one gRPC-web client to DAEMON_HTTP_URL, the daemon's HTTP port. The loaders that render pages and the API both use this client.
When a request carries a bearer token, the client adds Authorization: Bearer <token> to its call. So a signed-in browser can read the private content it is allowed to see. The API also passes the browser's own authorization header into every gRPC call it makes.
If the daemon rejects a bearer token, the request fails with a 401, even for public content. The page loader shows that as a server error. If a site refuses to load after a key change, clear the cookie.
Caching. When the server renders a page, it caches the answers of Query, QueryBlock, InteractionSummary and ListCitations for 30 seconds, 500 entries at most. The code is in server-universal-client.ts.
An entry holds the promise of a call that is still running. So when the server renders one page several times at once, the renders share one gRPC call.
That client never sends a token, so the cache only ever holds the public view.
API answers to browsers carry Cache-Control: private, no-store, and there is no HTTP cache in front of the app.
Citations. A list of citations, and the counts in an interaction summary, fetch one page of 500 citations and never more (listAllPages with maxPages in @shm/shared). Reading every citation of a document with very many citations would keep the daemon's read pool busy. So a document with more than 500 citations shows a cut count. The panel that opens from the citation count of a block is also one page of ListCitations, with one entry for each citing block. It does not read the activity feed, which keeps one event for each publication.
Site identity and registration
A site is a daemon, this app and a JSON file. The file is config.json in the data directory. It holds availableRegistrationSecret, and after registration also registeredAccountUid and sourcePeerId. Until a site is registered, it shows a "not registered" page. Registration goes like this:
The owner opens https://site/hm/register?secret=… and pastes the link into the publish dialog of the desktop app.
The desktop app posts to /hm/api/register.
When the site and the desktop app share a daemon, as in local development, the peer ids match. Then the site skips the connection and the push of content, because the content is already there. A second file format, service-config.json, serves several sites with custom domains from one deployment. Sites explains the model, and Self-hosting gives the steps.
Set SEED_IS_GATEWAY=true and the site becomes a gateway. A gateway serves /hm/<account>/<path> URLs for any account. A normal site serves one registered space. hyper.media runs as a gateway.
An owner can register a site from the desktop app or from a browser, or let Seed Hosting run the site. Publishing a space to a domain describes that flow, which the web app shares with the desktop app.
Space settings in the browser
The owner of a space can change its settings in a browser. While you view a space you own, open the account menu, or the options menu on the space's home document, and choose Space Settings. There you change the general settings, the identity, the navigation and the web domain.
The settings look like the ones in the desktop app: a list of sections beside the detail pane, or a section list with back navigation on a small screen.
Each section has its own URL under /:settings, or /hm/<uid>/:settings on a gateway.
The entry in the account menu shows in desktop and mobile browsers. It is hidden when you view someone else's space.
A change is signed with the session key of the signed-in owner. This also works when the owner manages the space through the origin of another site.
On any page of a space, its owner can add a link to the top bar without opening the settings:
Add or edit links shows after the links while the pointer is over them. On a touch screen it always shows. In the phone menu it is below the links.
The new link goes at the end, and the app publishes it at once. The bar holds up to six links. When the bar is full, the dialog only offers Manage links.
Manage links, in the same dialog, opens the Navigation settings. There you edit, reorder and remove links.
Routes
Route | Purpose |
|---|---|
| Documents, rendered on the server, with |
| The Seed API: GET queries and CBOR POST actions, handled by the shared typed router. See Seed API. |
| The identity of the site: registered account, peer id, addresses, protocol id, gateway flag, the URL of the notify service and the URL of the app environment. |
| The site services. |
| POST only, with |
| POST only, with the same secret. After the hostname of an enterprise node changes, it publishes the organization's home document again with the new site address. |
| The sign-in check and the sign-in page of a members-only site. |
| Pages of the app itself. |
| The email notification settings. Every notification email links to it. The token in the link is the credential. So the page is open on a members-only site, and it sends |
URLs explains versions, block fragments and view terms.
How a page is rendered
The server loads the data a page needs, and the browser takes it over without asking again. The rule is simple: the server loads exactly the queries that the components will ask for.
The loaders in app/loaders.ts find the document or comment for the URL. They follow redirects.
Then they fill a React Query cache. Each request gets its own QueryClient (app/queries.server.ts, staleTime: Infinity).
The apps share the query definitions, in @shm/shared (models/queries.ts). queryResource, queryDirectory, queryAccount, queryQueryBlock, queryDocumentCollaborators and the others each return a {queryKey, queryFn}. The same object works for prefetchQuery on the server and for useQuery in a component.
The server loads in two rounds. Each round is a set of parallel Promise.allSettled calls, so one failure never breaks a page.
The document, the home document of the site, both directories, the collaborators of the document and of the home, and the documents in the breadcrumb.
From the content of the document: the data of every query block, every embedded document and the account of every author.
The server puts the cache into the loader data, and the page restores it in a HydrationBoundary. The browser fetches anything that is missing when it needs it. The server does not load interaction summaries (the counts of comments and citations) on purpose. To compute one, the daemon reads the citations of the target, and a page can show thirty cards. The browser fetches the summaries for the cards on screen.
renderDocumentToHTML in @shm/editor renders the body of the document on the server, as the same HTML the editor produces, from the same cache. The editor then starts on top of it, and the reader never sees an empty frame. The shared packages describes that renderer and the handoff.
Signing in the browser
A browser identity is an Ed25519 key pair. WebCrypto makes it in a form that cannot be exported, and the browser stores it in IndexedDB. This key is the session key.
A browser key does not own a space. It acts for an account that the vault holds. The account gives it an AGENT capability, and the key's profile is an alias of the account. Sign in with Seed describes this flow.
The browser builds and signs comments and document edits with the SDK, and posts them through the PublishBlobs action.
For private content the app also calls the daemon's authenticate call. It keeps the bearer token it gets in an HTTP-only cookie.
Configuration
Variable | Meaning |
|---|---|
| The daemon's HTTP port. |
| Where |
| The site's public origin. |
| The origin of the hosting API. The server gives it to the browser at runtime. The default is |
| Gateway mode. |
| Web signing and the vault origin used for sign-in. |
| Where |
| Admin secret for the multi-site service mode. |
| The notify service to use, normally |
| The app environment this site offers. The site reports it as |
| Members only: every page needs a signed-in member. See the enterprise node. |
| A public node, such as |
The /hm/notifications page signs its requests in the browser with the session key. It talks to the notify service that the vault named at sign-in, and not to NOTIFY_SERVICE_HOST. The notify API explains how every client finds its notify service. Notify describes the signed inbox and the older unsigned email form.
Running it
pnpm web # on :3000, against the daemon of the desktop development app
pnpm web:standalone # on :3099, with its own daemon./dev up runs it on port 3000 beside the other services. Self-hosting covers the container a site runs.
Working with it
In the Seed app
The desktop app serves the same typed /api/<Key> routes from the same code on its local API bridge. It registers a space with a site through /hm/api/register.
CLI
The CLI reads and writes through a site's /api. It uses hyper.media unless --server names another site. When you give it an https:// URL, it uses the site in that URL.
SDK
createSeedClient('https://site') talks to /api/<Key>. See The SDK.
Seed API
Seed API documents everything under /api, and Site services documents /hm/api.
Agents
Seed Agents read and write Hypermedia through a site's /api, hyper.media by default. They read the site's /hm/api/config to learn which account the site publishes.
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime