` is the page's own name, not the product's, and `Base` appends the site name to
+ * the document title — so a page sets a short `title` and gets "Features — Runic Gateway"
+ * in the tab and "Features" on the page.
+ */
+interface Props {
+ /** Small uppercase line above the title. What kind of page this is. */
+ eyebrow: string;
+ title: string;
+}
+
+const { eyebrow, title } = Astro.props;
+---
+
+
+ {eyebrow}
+ {title}
+
+
+
+
+
+
diff --git a/src/components/architecture/Allowlist.astro b/src/components/architecture/Allowlist.astro
new file mode 100644
index 0000000..ee86a58
--- /dev/null
+++ b/src/components/architecture/Allowlist.astro
@@ -0,0 +1,142 @@
+---
+/**
+ * "What reaches the public" — the second of `/architecture/`'s three diagrams (D21).
+ *
+ * The homepage states the split in one sentence inside the data-path walk ("a public one
+ * carrying an allowlist of safe events, and a staff-only one carrying the rest… that split
+ * is a security boundary, not a preference"). This is the page where that sentence has to
+ * become a picture, because it is the single design decision a technical evaluator is most
+ * entitled to be suspicious of: a live feed of a game world contains things that must never
+ * be published, and "we filter it" is a claim, not a mechanism.
+ *
+ * So the diagram draws the shape of the mechanism — one stream in, one decision, two streams
+ * out — and the notes say where the decision lives and what happens when it is wrong in
+ * either direction. What it deliberately does NOT do is enumerate event kinds: that is the
+ * catalog's job in the docs, it changes with the protocol, and a marketing page holding a
+ * copy of it would be a copy that goes stale (§1).
+ *
+ * The rings sit behind the filter rather than behind the whole picture, on the phase-3
+ * principle that they mark the one place the argument actually happens.
+ */
+---
+
+
+
+
What reaches the public
+
One feed in, two feeds out
+
+ A live game world emits things that are fine on a front page and things that are not:
+ who logged in from which address, what the cheat detector flagged, what a staff member
+ did to whom. Both arrive on the same connection, so something has to divide them.
+
+
+
+
+
+
+ It is an allowlist, not a blocklist
+
+ The public stream carries the kinds of event that are named as safe; everything else
+ goes to the staff stream by default. That ordering is the whole point. A blocklist
+ fails open — the day the game emits something new, it is already published — and an
+ allowlist fails closed, so the worst case is a page that is missing something rather
+ than a page that has published an address.
+
+
+
+
+ The decision lives on your server
+
+ Not in the sidecar and not in the game. The bridge is a deliberately dumb forwarder:
+ it moves what the game emits and makes no judgements about audience. Everything
+ about who may see what is decided by the site you run, in one place, where you can
+ read it — and where changing it does not mean redeploying anything on the game host.
+
+
+
+
+ More than two audiences, in practice
+
+ Two streams is the transport. Above it sits a configurable audience model — logged
+ out, signed in, linked to a game account, staff — that decides how much of a given
+ surface each of those sees. The public stream is the floor of that, and it is the
+ one that is a boundary rather than a setting.
+
+
+
+
+ When the game is down
+
+ Nothing arrives, and the site carries on. Live surfaces say the server is offline
+ and everything that does not depend on it — the wiki, the news, accounts, the forums
+ — is unaffected. A site that goes down with the game it reports on is not much of a
+ status page.
+
+
+
+
+
Where the game stops
+
A seam, with a version on it
+
+ The core site does not know what a shard is, what a guild is, or that Ultima Online
+ exists. Everything that does lives in an installable module on the other side of a
+ declared interface — which is what makes "put your game on it" a shape rather than a
+ slogan.
+
+
+
+
+
+
+ The module brings its own everything
+
+ Not just screens: its routes, its database tables, its navigation rows, its slice of
+ the OpenAPI spec and its own prebuilt client bundle. Installing it is a paste in the
+ admin panel or a line in your environment — never a build step, because production
+ runs an image you pulled, and an operator who has to compile something has been
+ handed a maintenance job rather than a feature.
+
+
+
+
+ Failure is contained by design
+
+ A module that will not load is marked as failed and the site starts without it.
+ Disabling one is a kill switch, not a visibility flag — its routes stop answering
+ and its live connections close. Uninstalling keeps the data, and destroying the data
+ is a separate, deliberate choice made in its own dialog.
+
+
+
+
+ Teams is the shape of the contract
+
+ Core owns the Teams primitive — the roster, the forum, the notifications, the voice
+ channel — and does not own the word. A Team cannot be created in core at
+ all; it arrives from the module, which is why the UO module calls them guilds and
+ builds those pages itself. That is the pattern the whole interface is built on: core
+ supplies the machinery, the module supplies the meaning.
+
+
+
+
+ What this does not yet prove
+
+ One module exists and it is Ultima Online. A second, for a different game, is a
+ written dry-run that was deliberately never implemented — it exists to test whether
+ the contract generalises on paper. Until somebody builds the second one, the seam is
+ a well-argued design rather than a demonstrated one, and this site says so wherever
+ it comes up.
+
+
+
+
+
What you deploy
+
Two hosts, two installs
+
+ Almost everyone gets this wrong once. The website and the game-side bridge are separate
+ deployments on separate machines, and neither one installs the other — so a "Runic
+ Gateway install" is really two, done in that order.
+
+
+
+
+
+
+ The web host
+
+ A Docker Compose deployment: the site, its database, and whichever game module you
+ installed. Images are pulled rather than built, so nothing compiles here and an
+ upgrade is a pull and a restart. This is the only machine anybody points a browser
+ at, and the only one that needs a certificate.
+
+
+
+
+ The game host
+
+ The machine your game server is already on. One installer binary puts the plugin
+ into the server's tree, installs the sidecar beside it and registers the service —
+ then prints four values. It never contacts your website; you paste those four
+ values into the admin panel yourself, and that is the moment the two halves meet.
+
+
+
+
+ Why they share a host
+
+ The game talks to the sidecar over loopback, on the same machine, and dials
+ out to do it. That is what lets the game server open no port at all — and it
+ is also why there is no macOS installer build. The pair has to sit together, and no
+ game server anybody runs is on one.
+
+
+
+
+ What crosses between them
+
+ One authenticated connection, in both directions: a WebSocket carrying the live feed
+ up, and REST calls going down for point-in-time questions. Nothing else on either
+ machine talks to the other, and the sidecar answers your site and nobody else.
+
+
+
+
+ Three boundaries decide almost everything about how this software behaves: the one
+ between your two machines, the one between what the public sees and what staff see, and
+ the one between the platform and the game. Each is drawn below, with the reasoning
+ rather than the reference.
+
+
+ Nothing here is a specification. Where a real one exists it is linked — the protocol,
+ the module contract and the operator guide are all documents in the open, and they are
+ the authority when this page and one of them disagree.
+
+
+
+
+
+
+
+
+
+
Going deeper
+
The documents this page is a summary of
+
+ Everything above is an argument about shapes. These are the things that specify them,
+ and they are what a module author, an integrator or an operator should be reading.
+
+
+
+ -
+
+ The bridge protocol
+
+ What the game and the sidecar say to each other, and what the sidecar publishes.
+ Protocol {platform.protocol} today, and versioned so a mismatched pair is refused
+ rather than misread.
+
+ -
+
+ The module contract
+
+ The normative interface between core and a module — currently
+ {platform.moduleApi}. This is the document that decides whether your module
+ loads.
+
+ -
+
+ The operator guide
+
+ Setting the game side up end to end, including the failure modes and what each
+ step should look like when it worked.
+
+ -
+ The documentation on this site
+ The same ground as a guided path rather than a specification, starting from an
+ empty server.
+
+
+
+
+
+ This is a small project run by people with day jobs. There is no support desk and no
+ ticket queue, which is worth knowing before you choose where to put a question — one of
+ these channels answers in minutes and one of them may not answer at all.
+
+
+
+
+
+ -
+
+
Discord
+ The front door
+
+
+ Questions, bug reports, help getting an install working, and where the Android beta
+ is announced. No account with us to make, nothing to be approved for, and the
+ fastest way to reach somebody who has run this software.
+
+
+ Use it for
+ Anything you would otherwise open an issue for, and everything you would not.
+
+
+ Join the Discord
+
+
+
+ -
+
+
The code
+ Read freely
+
+
+ Every repository is public and readable without signing in to anything — the
+ website, the bridge, the game plugin, the installer, the module, the app and all of
+ the documentation. Clone it, read it, run it.
+
+
+ One caveat
+ {/*
+ THE SENTENCE §14 N3 SAYS WILL CHANGE. If Gitea registration is reopened —
+ manual confirm, Turnstile, no repository creation by default — this becomes
+ "issues and pull requests are open to anyone with an account", and nothing else
+ on the page moves.
+ */}
+ Registration on our Gitea is closed at the moment, so filing an issue needs an
+ account we would have to create for you. Ask on Discord and it will reach the same
+ place.
+
+ Browse the source
+
+
+ -
+
+
Security
+ Private
+
+
+ If you have found something that should not be discussed in a public channel, email
+ it. You will get a human, not a form, and there is no bounty programme to game —
+ just an acknowledgement and a fix.
+
+
+ Use it for
+ Anything that would let somebody reach a deployment, an account or a game server
+ they should not.
+
+ {brand.contactEmail}
+
+
+
+
+
+
+
Contributing
+
What is useful, in order
+
+
+ -
+
Run it and say what broke
+
+ The install path is the priority of this whole project, and the most valuable
+ thing anyone outside it can do is walk it on a machine we have never seen and
+ report where it stopped making sense.
+
+
+ -
+
Build a module for another game
+
+ There is one module and it is Ultima Online, so the claim that this platform is
+ game-agnostic is currently an argument rather than a demonstration. The
+ Integration Kit exists to be followed by somebody outside
+ this project — and it stays marked draft until it has been.
+
+
+ -
+
Fix the documentation
+
+ Documentation is versioned alongside the code it describes and a change is not
+ finished until the docs match it. If something you read was wrong, that is a bug
+ of the same kind as any other.
+
+
+
+
+
+ All of it is free software under the GPL-3.0-or-later, and contributions carry one
+ house rule worth knowing before you start: work done with AI assistance has to say so
+ — a box on the pull request and a trailer on the commit. Undisclosed AI-generated
+ contributions get closed. Every repository's CONTRIBUTING.md has the
+ details.
+
+
+ Grouped the way the software is actually divided, because that division is the thing
+ most worth understanding before you install it: the core site is game-agnostic and does
+ not know what a shard is, and everything that does arrives as an installable module.
+
+
+ Today there is one module and it covers Ultima Online, so the second group below is
+ what a UO deployment gets. On a deployment with no module, that group is simply absent
+ and the other four are unchanged.
+
+
+
+ {
+ capabilityGroups.map((group) => (
+
+
+
{group.title}
+
+ {group.moduleSupplied ? 'From the installed module' : 'Core'}
+
+
+
+ {group.summary}
+
+
+
+ ))
+ }
+
+
+
+
+
diff --git a/src/pages/integrations.astro b/src/pages/integrations.astro
new file mode 100644
index 0000000..39d6d54
--- /dev/null
+++ b/src/pages/integrations.astro
@@ -0,0 +1,301 @@
+---
+import Base from '../layouts/Base.astro';
+import PageHeader from '../components/PageHeader.astro';
+import NotBuilt from '../components/NotBuilt.astro';
+
+import platform from '../data/platform.json';
+
+/**
+ * `/integrations/` — PLAN.md §13 phase 4.
+ *
+ * §10 gives it Discord, mobile and push, SSO, "with an explicit 'not built' list". The
+ * explicit list is the reason this page is worth writing carefully: an integrations page is
+ * the one a reader scans for the name of the thing they already use, and the honest answer
+ * for several of those names is no. §2 calls the absent-features list as load-bearing as the
+ * rest, and `NotBuilt` at the foot of this page is where that lands.
+ *
+ * ---------------------------------------------------------------------------------------
+ * THE TRADE-OFFS ARE ON THE PAGE
+ * ---------------------------------------------------------------------------------------
+ * Each integration carries a `caveat` — the thing you would find out in week two. Discord
+ * voice channels make Team membership visible on a member's Discord profile, because they
+ * are granted by role; the mobile app has no server of ours to point at; SSO will not create
+ * an account. None of those is a defect and all three change whether someone wants the
+ * feature, so leaving them for the documentation would be the dishonest kind of brevity.
+ * That is D8's "understated honesty" doing something other than adjusting adjectives.
+ *
+ * No version numbers are typed here. The app version and the platform's own numbers come
+ * from `platform.json` (§12), which `checkFacts.mjs` re-reads from each repository's
+ * authority on every build.
+ */
+const title = 'Integrations';
+const description =
+ 'What Runic Gateway connects to — Discord, mobile push, single sign-on — and what it ' +
+ 'deliberately does not.';
+
+const integrations = [
+ {
+ id: 'discord',
+ name: 'Discord',
+ summary:
+ 'A bot for the server your community is already sitting in, doing three separate jobs.',
+ points: [
+ {
+ title: 'Slash commands',
+ body:
+ 'Commands registered with your guild that answer from your site — so the thing ' +
+ 'somebody wants to look up is available where the conversation is happening, ' +
+ 'rather than one tab away.',
+ },
+ {
+ title: 'Notifications into channels',
+ body:
+ 'News and Team activity bridged into the channels you choose, with a per-Team ' +
+ 'override so one group can route its own notifications somewhere else. Delivery ' +
+ 'is best-effort and one-shot: a Discord outage never backs anything up on your ' +
+ 'site.',
+ },
+ {
+ title: 'A voice channel per Team',
+ body:
+ 'A Team can be granted its own voice channel, with membership maintained by the ' +
+ 'bot rather than by whoever is online. The bot creates the category, and the ' +
+ 'panel reports how many roles your guild has left before Discord’s own limit.',
+ },
+ ],
+ caveat:
+ 'Voice access is granted with a Discord role, and roles are visible on a member’s ' +
+ 'profile — so a Team with a voice channel is a Team anyone in your guild can see the ' +
+ 'membership of. That was a deliberate trade for a limit that counts per guild rather ' +
+ 'than per channel, and it is the right one for most communities, but it is not private.',
+ },
+ {
+ id: 'mobile',
+ name: 'Mobile and push',
+ summary:
+ 'A native Android app against the same documented API the website uses, with push ' +
+ 'through a server you run.',
+ points: [
+ {
+ title: 'The same API, not a second one',
+ body:
+ 'The app is a client of the API your deployment already publishes, authenticated ' +
+ 'with short-lived tokens and rotated, revocable refresh tokens. There is no ' +
+ 'mobile-only backend to keep in step.',
+ },
+ {
+ title: 'Push through your own ntfy',
+ body:
+ 'Notifications are delivered by a self-hosted ntfy server rather than a vendor in ' +
+ 'the middle. Each person chooses which streams reach them; push arrives by ' +
+ 'default and can be switched off entirely.',
+ },
+ {
+ title: 'Trusted devices and two-factor',
+ body:
+ 'The app shares the site’s account model, including time-based two-factor ' +
+ 'codes, recovery codes, and devices you can mark as trusted and revoke later.',
+ },
+ ],
+ caveat:
+ 'The app points at no server of ours: the person installing it types the address of ' +
+ 'the deployment they belong to. That is what makes one app work for every community ' +
+ 'running this software, and it means the app is useless until somebody gives them a ' +
+ 'URL — which is a thing worth putting in your welcome message.',
+ },
+ {
+ id: 'sso',
+ name: 'Single sign-on',
+ summary:
+ 'OAuth2 and OIDC, against Google, Discord, or any provider you already run.',
+ points: [
+ {
+ title: 'Any OIDC provider',
+ body:
+ 'Google and Discord are configured by name; anything else that speaks OIDC is ' +
+ 'configured generically. Client secrets are encrypted at rest and never returned ' +
+ 'to any client.',
+ },
+ {
+ title: 'It signs people in, not up',
+ body:
+ 'An external identity has to be linked to an account that already exists on your ' +
+ 'site. Signing in with a provider never creates a user — which means the way ' +
+ 'someone joins your community stays a decision you make, not one Google makes.',
+ },
+ {
+ title: 'It respects the rest of the login rules',
+ body:
+ 'Two-factor, trusted devices and bans all still apply. An identity provider ' +
+ 'proves who someone is; it does not decide whether they may come in.',
+ },
+ ],
+ caveat:
+ 'Link-only is a policy, not a limitation to be worked around. If you were expecting ' +
+ 'to open registration by turning on Google sign-in, this will not do that, and it is ' +
+ 'not configurable.',
+ },
+];
+---
+
+
+
+
+ Three integrations exist and are in use. Each one below says what it does, and then the
+ thing you would otherwise discover in week two — because an integrations page that only
+ lists the good half is how somebody ends up rebuilding their community around an
+ assumption.
+
+
+ Everything here is configured on your own deployment, against services you already run
+ or already have an account with. Nothing routes through us; there is no us to route
+ through.
+
+
+
+ {
+ integrations.map((integration) => (
+
+ {integration.name}
+ {integration.summary}
+
+
+ {integration.points.map((point) => (
+ -
+
{point.title}
+ {point.body}
+
+ ))}
+
+
+
+
Worth knowing first
+
{integration.caveat}
+
Email, deliberately quiet
+
+ Your deployment can send email — Team notifications and newsletters, through an account
+ you connect — and it only ever sends to someone who asked for it. Email is the one
+ channel that is opt-in rather than opt-out, because an unwanted push notification is an
+ annoyance and an unwanted email is a complaint to somebody’s provider.
+
+
+ This website is a separate matter: runicgateway.com sends no email at all, has
+ no mailbox behind it and no account to make. The address in the footer is a human being.
+
+
+
+
+
+
+
+
If you need another one
+
The API is the integration point
+
+ The whole backend is described by an OpenAPI 3.0 specification that ships with the
+ server, and an installed module merges its own routes into it — so whatever you build
+ against is documented by the thing that is actually running, at
+ {' '}Module API {platform.moduleApi}. The bridge to a game server is a documented wire
+ protocol on the same principle, currently protocol {platform.protocol}.
+
+
+
+ A module is the entire game-specific half of a deployment, packaged: its routes, its
+ screens, its database tables, its navigation rows and its slice of the API
+ documentation. The core site holds accounts, Teams, the wiki, posts, moderation and the
+ admin panel, and knows nothing about any game at all.
+
+
+ That division is not an aspiration bolted on afterwards. The Ultima Online support was
+ extracted out of the site into a module, and every URL it had before the move it still
+ has — which is the only version of this claim worth making.
+
+
+
+
+ What you get
+ What installing one actually does
+
+
+ -
+
It brings its own everything
+
+ Server routes, React screens, tables, nav rows and an OpenAPI fragment the site
+ merges into its own spec. Nothing about it is a patch to the core site, so
+ upgrading either half does not involve reconciling the other.
+
+
+ -
+
You never build it
+
+ The client half ships prebuilt and the artifact is verified against a published
+ checksum before anything is written to disk. Production runs an image you pulled;
+ an operator who has to compile something has been handed a maintenance job.
+
+
+ -
+
It cannot take the site down
+
+ A module whose declared interface version does not match is marked failed and the
+ site starts without it — loudly, rather than half-loading. Disabling one closes its
+ connections and stops its routes answering.
+
+
+ -
+
Your data outlives it
+
+ Uninstalling removes the module and keeps its tables, so reinstalling picks up
+ exactly where it was. Destroying the data is a separate, opt-in choice made in its
+ own dialog, and it says what it is about to do.
+
+
+
+
+
+
+ Installing
+ Three ways in, and none of them is a build
+
+ Which one you use is a question about your host, not about the module. All three end
+ the same way: a restart, and the module's screens appear in the navigation.
+
+
+
+ {
+ installPaths.map((path) => (
+ -
+
{path.name}
+ {path.body}
+ {path.fits}
+
+ ))
+ }
+
+
+
+
+
+
The worked example
+
module-uo
+
{platform.releases['Module-uo']}
+
+ The Ultima Online module, and the reference every module that follows is measured
+ against. It is what turns a general-purpose community site into something that knows
+ what a shard is — and it is the proof that the seam described on
+ the architecture page is real, because the code on the far
+ side of it was moved there rather than designed there.
+
+
+
+
+
What it publishes
+
+ {gameIntelligence.items.map((item) => - {item.label}
)}
+
+
+ The same list features expands, read from one file that is
+ checked against the module's own manifest on every build.
+
+
+
+
+
+ It connects to a real server
+
+ The module talks to the sidecar beside your game server, not to the game. You
+ deploy that side with the installer and paste four values into the admin panel;
+ nothing here requires the game to exist, and with no server configured the site
+ renders normally and shows it offline.
+
+
+
+ It owns its own tables
+
+ Its schema is applied by the site on every boot and its data is its own. The
+ module declares which versions of the core interface it speaks — the site runs
+ {' '}{platform.moduleApi} — and refuses to load against one it does not.
+
+
+
+ It is a separate release
+
+ Versioned, tagged and published on its own cadence, independently of the site.
+ Upgrading one does not mean upgrading the other, as long as the declared interface
+ range still holds.
+
+
+
+
+
Writing your own
+
The Integration Kit
+
Draft
+
+ A four-chapter book on putting a different game on this platform — the module, the
+ sidecar beside your game server, the plugin inside it — plus a template module that
+ continuous integration builds against a pinned version of the core site, so the
+ instructions cannot quietly stop working.
+
+
+
+
Why it says draft
+
+ Because nobody outside this project has yet followed it to a working module, and that
+ is the only test of a set of instructions that counts. The badge comes off when
+ somebody does — that is the stated condition, not a mood, and it is written down so a
+ future reader knows when to take it down.
+
+
+ Everything it teaches is real and in use. What is untested is whether it is
+ sufficient: whether someone with no access to this project's context can get
+ from an empty repository to a running module using it alone.
+
+